snice 1.4.0 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # Snice
 
-A lightweight TypeScript framework for building web components with decorators and routing.
+An imperative TypeScript framework for building vanilla web components with decorators and routing
 
 ## Quick Start
 
@@ -21,16 +21,16 @@ Snice takes an **imperative approach** to web components. Unlike reactive framew
 - Require **explicit method calls** to update visual state
 - Give you **full control** over when and how updates happen
 
-This approach eliminates the complexity of reactive systems, virtual DOM diffing, and unexpected re-renders. You write straightforward code that does exactly what you tell it to do.
+This approach gives you direct control over DOM updates without hidden complexity or automatic re-renders.
 
 ## Core Concepts
 
 Snice provides a clear separation of concerns through decorators:
 
-### Component 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`** - Sets up routing and navigation between different views
+- **`@page`** - Defines routable page components that render when their route is active, with URL params passed as attributes
 
 ### Property & Query Decorators
 - **`@property`** - Declares properties that can reflect to attributes
@@ -131,7 +131,7 @@ class UserCard extends HTMLElement {
   @property({ reflect: true })
   name = 'Anonymous';
   
-  @property({ reflect: true })
+  @property({ attribute: 'user-role' })  // Maps to user-role attribute
   role = 'User';
   
   @property({ type: Boolean })
@@ -152,7 +152,7 @@ class UserCard extends HTMLElement {
 
 Use it with attributes:
 ```html
-<user-card name="Jane Doe" role="Admin" verified></user-card>
+<user-card name="Jane Doe" user-role="Admin" verified></user-card>
 ```
 
 
@@ -168,56 +168,26 @@ class ThemeToggle extends HTMLElement {
   @property({ reflect: true })
   theme: 'light' | 'dark' = 'light';
   
-  @property({ type: Boolean })
-  animated = true;
-  
-  @query('.toggle-button')
-  button?: HTMLElement;
-  
-  @query('.theme-icon')
+  @query('.icon')
   icon?: HTMLElement;
   
   html() {
     return `
-      <button class="toggle-button">
-        <span class="theme-icon">🌞</span>
+      <button>
+        <span class="icon">🌞</span>
       </button>
     `;
   }
   
   @watch('theme')
-  onThemeChange(oldTheme: string, newTheme: string, propertyName: string) {
-    // propertyName will be 'theme'
-    // Update icon when theme changes
+  updateTheme(oldValue: string, newValue: string) {
     if (this.icon) {
-      this.icon.textContent = newTheme === 'dark' ? '🌙' : '🌞';
-    }
-    
-    // Update button styling
-    if (this.button) {
-      this.button.classList.remove(`theme--${oldTheme}`);
-      this.button.classList.add(`theme--${newTheme}`);
-    }
-    
-    // Animate if enabled
-    if (this.animated && this.button) {
-      this.button.classList.add('transitioning');
-      setTimeout(() => {
-        this.button?.classList.remove('transitioning');
-      }, 300);
+      this.icon.textContent = newValue === 'dark' ? '🌙' : '🌞';
     }
   }
   
-  @watch('animated')
-  onAnimatedChange(oldValue: boolean, newValue: boolean, propertyName: string) {
-    // propertyName will be 'animated'
-    if (this.button) {
-      this.button.classList.toggle('animations-enabled', newValue);
-    }
-  }
-  
-  @on('click', '.toggle-button')
-  toggleTheme() {
+  @on('click', 'button')
+  toggle() {
     this.theme = this.theme === 'light' ? 'dark' : 'light';
   }
 }
@@ -234,9 +204,9 @@ You can watch multiple properties with a single decorator:
 
 ```typescript
 @watch('width', 'height', 'scale')
-updateDimensions(oldValue: number, newValue: number, propertyName: string) {
+updateDimensions(_old: number, _new: number, _name: string) {
   // Called when any of these properties change
-  console.log(`${propertyName} changed from ${oldValue} to ${newValue}`);
+  console.log(`${_name} changed from ${_old} to ${_new}`);
   this.recalculateLayout();
 }
 ```
@@ -245,8 +215,8 @@ Watch all property changes with the wildcard:
 
 ```typescript
 @watch('*')
-handleAnyPropertyChange(oldValue: any, newValue: any, propertyName: string) {
-  console.log(`Property ${propertyName} changed from ${oldValue} to ${newValue}`);
+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
 }
 ```
@@ -335,24 +305,16 @@ class ToggleSwitch extends HTMLElement {
   toggleButton?: HTMLElement;
 
   html() {
-    return `
-      <button class="toggle">
-        <span class="slider"></span>
-      </button>
-    `;
-  }
-  
-  css() {
-    return `...`;
+    return `<button class="toggle">OFF</button>`;
   }
   
   @on('click', '.toggle')
   @dispatch('toggled')
   toggle() {
     this.isOn = !this.isOn;
-    this.toggleButton?.classList.toggle('on', this.isOn);
-
-    // Return value becomes event detail
+    if (this.toggleButton) {
+      this.toggleButton.textContent = this.isOn ? 'ON' : 'OFF';
+    }
     return { on: this.isOn };
   }
 }
@@ -400,10 +362,7 @@ CSS is automatically scoped to your component.
 ```typescript
 import { Router } from 'snice';
 
-const router = Router({
-  target: '#app',
-  routing_type: 'hash'
-});
+const router = Router({ target: '#app', type: 'hash' });
 
 const { page, navigate, initialize } = router;
 
@@ -439,9 +398,104 @@ initialize();
 
 // Navigate programmatically
 navigate('/about');
-navigate('/users/123');  // Sets id="123" on UserPage
+navigate('/users/123');  // Sets userId="123" on UserPage
 ```
 
+### Route Guards
+
+Protect routes with guard functions that control access:
+
+```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;
+
+// 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';
+
+// Protected page with single guard
+@page({ tag: 'dashboard-page', routes: ['/dashboard'], guards: isAuthenticated })
+class DashboardPage extends HTMLElement {
+  html() {
+    return `<h1>Dashboard</h1>`;
+  }
+}
+
+// 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>`;
+  }
+}
+
+// Guard that uses route params to check resource-specific permissions
+const canEditUser: Guard<AppContext> = async (ctx, params) => {
+  const user = ctx.getUser();
+  if (!user) return false;
+  
+  // params.id comes from route '/users/:id/edit'
+  const response = await fetch(`/api/permissions/users/${params.id}/can-edit`);
+  return response.ok;
+};
+
+// 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>`;
+  }
+}
+
+@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>`;
+  }
+}
+
+// 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>
+    `;
+  }
+}
+
+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:
@@ -493,221 +547,169 @@ Use it:
 
 ## Channels
 
-Request/response between elements and controllers:
+Bidirectional communication between elements and controllers:
 
 ```typescript
-// --- components/user-card.ts
-@element('user-card')
-class UserCard extends HTMLElement {
-  @channel('get-data')
-  async *fetchUserData() {
-    // Yield sends request, await waits for response
-    const user = await (yield { id: 123 });
+// Element sends request, controller responds
+@element('user-profile')
+class UserProfile extends HTMLElement {
+
+  @channel('fetch-user')
+  async *getUser() {
+    const user = await (yield { userId: 123 });
     return user;
   }
   
-  async loadUser() {
-    const user = await this.fetchUserData();
-    console.log(user);  // { name: 'Alice' }
+  async connectedCallback() {
+    const userData = await this.getUser();
+    this.displayUser(userData);
   }
+  
 }
 
-// --- controllers/user-controller.ts
 @controller('user-controller')
 class UserController {
-  element: HTMLElement | null = null;
-  
-  async attach(element: HTMLElement) {}
-  async detach(element: HTMLElement) {}
-  
-  @channel('get-data')
-  handleGetData(request) {
-    console.log(request);  // { id: 123 }
-    return { name: 'Alice' };
+
+  @channel('fetch-user')
+  async handleFetchUser(request: { userId: number }) {
+    const response = await fetch(`/api/users/${request.userId}`);
+    return response.json();
   }
+
 }
 ```
 
-## Complete Example
+## Router Context
 
-Here's how the pieces work together - a generic display component filled by a controller:
+Access router context in page components, nested elements, and controllers using the `@context` decorator.
 
-```typescript
-import { element, controller, query } from 'snice';
+### ⚠️ Important Warning About Global State
 
-// Generic card component - purely visual
-@element('info-card')
-class InfoCard extends HTMLElement {
-  @query('.title')
-  titleElement?: HTMLElement;
-  
-  @query('.content')
-  contentElement?: HTMLElement;
-  
-  @query('.footer')
-  footerElement?: HTMLElement;
+**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.
 
-  html() {
-    return `
-      <div class="card">
-        <h2 class="title">Loading...</h2>
-        <div class="content">
-          <div class="skeleton"></div>
-        </div>
-        <div class="footer"></div>
-      </div>
-    `;
-  }
+**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
 
-  css() {
-    return `
-      .card {
-        border: 1px solid #ddd;
-        border-radius: 8px;
-        padding: 20px;
-        max-width: 400px;
-      }
-      .title {
-        margin: 0 0 15px 0;
-        color: #333;
-      }
-      .content {
-        min-height: 60px;
-      }
-      .skeleton {
-        background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
-        height: 20px;
-        border-radius: 4px;
-        animation: loading 1.5s infinite;
-      }
-      .footer {
-        margin-top: 15px;
-        font-size: 0.9em;
-        color: #666;
-      }
-      @keyframes loading {
-        0% { background-position: -200px 0; }
-        100% { background-position: 200px 0; }
-      }
-    `;
-  }
+### Basic Usage in Pages
+
+```typescript
+// Define your context class with controlled mutations
+class AppContext {
+  private user: User | null = null;
   
-  // Methods the controller can call to update the display
-  setTitle(title: string) {
-    if (this.titleElement) {
-      this.titleElement.textContent = title;
-    }
-  }
+  // Controlled mutation through methods
+  setUser(user: User) {...}
   
-  setContent(html: string) {
-    if (this.contentElement) {
-      this.contentElement.innerHTML = html;
-    }
-  }
+  // Read-only access
+  getUser() {...}
   
-  setFooter(text: string) {
-    if (this.footerElement) {
-      this.footerElement.textContent = text;
-    }
-  }
+  isAuthenticated() {...}
 }
 
-// Controller that fetches and populates data
-@controller('weather-controller')
-class WeatherController {
-  element: HTMLElement | null = null;
-  
-  async attach(element: HTMLElement) {
-    
-    // Simulate fetching weather data
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    
-    const weatherData = {
-      location: 'San Francisco',
-      temp: '72°F',
-      conditions: 'Partly Cloudy',
-      humidity: '65%'
-    };
-    
-    // Update the generic card with specific data
-    (element as any).setTitle(weatherData.location);
-    (element as any).setContent(`
-      <p><strong>${weatherData.temp}</strong></p>
-      <p>${weatherData.conditions}</p>
-      <p>Humidity: ${weatherData.humidity}</p>
-    `);
-    (element as any).setFooter('Updated just now');
-  }
+// 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;
   
-  async detach(element: HTMLElement) {
-    // Cleanup if needed
+  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>
+    `;
   }
 }
 ```
 
-Use the same card with different controllers:
-```html
-<!-- Weather widget -->
-<info-card controller="weather-controller"></info-card>
-
-<!-- Stock widget - same card, different controller -->
-<info-card controller="stock-controller"></info-card>
-
-<!-- News widget - same card, different controller -->
-<info-card controller="news-controller"></info-card>
-```
-
-## Decorator Reference
+### Context in Nested Elements
 
-### Component Decorators
+Nested elements within pages can also access context through event bubbling:
 
-| Decorator | Purpose | Example |
-|-----------|---------|---------|
-| `@element(tagName)` | Defines a custom HTML element | `@element('my-button')` |
-| `@controller(name)` | Creates a data controller | `@controller('user-controller')` |
-| `@page(options)` | Defines a routable page component | `@page({ tag: 'home-page', routes: ['/'] })` |
-
-### Property Decorators
-
-| Decorator | Purpose | Example |
-|-----------|---------|---------|
-| `@property(options)` | Declares a property that can reflect to attributes | `@property({ type: Boolean, reflect: true })` |
-| `@query(selector)` | Queries a single element from shadow DOM | `@query('.button')` |
-| `@queryAll(selector)` | Queries multiple elements from shadow DOM | `@queryAll('input[type="checkbox"]')` |
-| `@watch(...propertyNames)` | Watches properties for changes and calls the method | `@watch('width', 'height')` or `@watch('*')` |
+```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>`;
+  }
+}
 
-### Event Decorators
+// 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 -->
+    `;
+  }
+}
+```
 
-| Decorator | Purpose | Example |
-|-----------|---------|---------|
-| `@on(event, selector?)` | Listens for DOM events | `@on('click', '.button')` |
-| `@dispatch(eventName, options?)` | Dispatches custom events after method execution | `@dispatch('data-updated')` |
-| `@channel(name, options?)` | Enables request/response communication | `@channel('fetch-data')` |
+### Context in Controllers
 
-### Property Options
+Controllers attached to page elements automatically acquire context:
 
 ```typescript
-interface PropertyOptions {
-  type?: typeof String | typeof Number | typeof Boolean | typeof Array | typeof Object;  // Type converter
-  reflect?: boolean;        // Reflect property to attribute
-  attribute?: string | boolean;  // Custom attribute name or false to disable
-  converter?: PropertyConverter;  // Custom converter
-  hasChanged?: (value: any, oldValue: any) => boolean;  // Custom change detector
+@controller('nav-controller')
+class NavController {
+  element: HTMLElement | null = null;
+  
+  @context()
+  ctx?: AppContext;
+  
+  attach(element: HTMLElement) {
+    // Context is available in controllers too
+    if (!this.ctx?.isAuthenticated()) {
+      window.location.hash = '#/login';
+    }
+  }
+  
+  detach(element: HTMLElement) {
+    // Cleanup if needed
+  }
 }
 
-interface PropertyConverter {
-  fromAttribute?(value: string | null, type?: any): any;
-  toAttribute?(value: any, type?: any): string | null;
+@page({ tag: 'admin-page', routes: ['/admin'] })
+class AdminPage extends HTMLElement {
+  html() {
+    return `<div controller="nav-controller">Admin Panel</div>`;
+  }
 }
 ```
 
-### Dispatch Options
+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
 
-```typescript
-interface DispatchOptions extends EventInit {
-  dispatchOnUndefined?: boolean;  // Whether to dispatch when method returns undefined
-}
-```
+**Remember:** With great power comes great responsibility. Global state is dangerous - use it wisely and sparingly.
 
 ## Documentation
 

package/bin/templates/base/global.d.ts

@@ -0,0 +1,14 @@
+declare module '*.css' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.css?inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.html' {
+  const content: string;
+  export default content;
+}

package/bin/templates/base/src/router.ts

@@ -2,7 +2,7 @@ import { Router } from 'snice';
 
 const { page, initialize, navigate } = Router({ 
   target: '#app', 
-  routing_type: 'hash',
+  type: 'hash',
   transition: {
     mode: 'simultaneous',
     outDuration: 200,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "A TypeScript library",
   "main": "src/index.ts",

package/src/channel.ts

@@ -59,7 +59,7 @@ export function channel(channelName: string, options?: ChannelOptions) {
         });
         
         // Dispatch event with promises
-        const eventName = `@channel:${channelName}`;
+        const eventName = `@channel/${channelName}`;
         const event = new CustomEvent(eventName, {
           bubbles: options?.bubbles !== undefined ? options.bubbles : true,
           cancelable: options?.cancelable || false,
@@ -135,7 +135,7 @@ export function setupChannelHandlers(instance: any, element: HTMLElement) {
   
   for (const handler of handlers) {
     const boundMethod = handler.method.bind(instance);
-    const eventName = `@channel:${handler.channelName}`;
+    const eventName = `@channel/${handler.channelName}`;
     
     // Setup channel handler
     const channelHandler = (event: CustomEvent) => {

package/src/controller.ts

@@ -1,6 +1,6 @@
 import { setupEventHandlers, cleanupEventHandlers } from './events';
 import { setupChannelHandlers, cleanupChannelHandlers } from './channel';
-import { IS_CONTROLLER_CLASS, CONTROLLER_KEY, CONTROLLER_NAME_KEY, CONTROLLER_ID, CONTROLLER_OPERATIONS, NATIVE_CONTROLLER, IS_ELEMENT_CLASS } from './symbols';
+import { IS_CONTROLLER_CLASS, CONTROLLER_KEY, CONTROLLER_NAME_KEY, CONTROLLER_ID, CONTROLLER_OPERATIONS, NATIVE_CONTROLLER, IS_ELEMENT_CLASS, ROUTER_CONTEXT } from './symbols';
 import { snice } from './global';
 
 type Maybe<T> = T | null | undefined;
@@ -110,6 +110,12 @@ export async function attachController(element: HTMLElement, controllerName: str
   (controllerInstance as any)[CONTROLLER_ID] = controllerId;
   controllerInstance.element = element;
   
+  // Pass router context from element to controller if it exists
+  const routerContext = (element as any)[ROUTER_CONTEXT];
+  if (routerContext !== undefined) {
+    (controllerInstance as any)[ROUTER_CONTEXT] = routerContext;
+  }
+  
   // Store references
   (element as any)[CONTROLLER_KEY] = controllerInstance;
   (element as any)[CONTROLLER_NAME_KEY] = controllerName;
@@ -169,6 +175,9 @@ export async function detachController(element: HTMLElement): Promise<void> {
     await scope.cleanup();
   }
   
+  // Clean up router context reference
+  delete (controllerInstance as any)[ROUTER_CONTEXT];
+  
   delete (element as any)[CONTROLLER_KEY];
   delete (element as any)[CONTROLLER_NAME_KEY];
   delete (element as any)[CONTROLLER_OPERATIONS];

package/src/element.ts

@@ -1,11 +1,14 @@
 import { attachController, detachController } from './controller';
 import { setupEventHandlers, cleanupEventHandlers } from './events';
-import { IS_ELEMENT_CLASS, READY_PROMISE, READY_RESOLVE, CONTROLLER, PROPERTIES, PROPERTY_VALUES, PROPERTIES_INITIALIZED, PROPERTY_WATCHERS, EXPLICITLY_SET_PROPERTIES } from './symbols';
+import { IS_ELEMENT_CLASS, READY_PROMISE, READY_RESOLVE, CONTROLLER, PROPERTIES, PROPERTY_VALUES, PROPERTIES_INITIALIZED, PROPERTY_WATCHERS, EXPLICITLY_SET_PROPERTIES, ROUTER_CONTEXT } from './symbols';
 
-export function element(tagName: string) {
-  return function (constructor: any) {
-    // Mark as element class for channel decorator detection
-    (constructor.prototype as any)[IS_ELEMENT_CLASS] = true;
+/**
+ * Applies core element functionality to a constructor
+ * This is shared between @element and @page decorators
+ */
+export function applyElementFunctionality(constructor: any) {
+  // Mark as element class for channel decorator detection
+  (constructor.prototype as any)[IS_ELEMENT_CLASS] = true;
     
     // Add controller property to all elements
     const originalConnectedCallback = constructor.prototype.connectedCallback;
@@ -179,7 +182,10 @@ export function element(tagName: string) {
           this.shadowRoot.innerHTML = shadowContent;
         }
         
-        originalConnectedCallback?.call(this);
+        // NOW call the original user-defined connectedCallback after shadow DOM is set up
+        if (originalConnectedCallback) {
+          originalConnectedCallback.call(this);
+        }
         
         const controllerName = this.getAttribute('controller');
         if (controllerName) {
@@ -197,7 +203,10 @@ export function element(tagName: string) {
     };
     
     constructor.prototype.disconnectedCallback = function() {
-      originalDisconnectedCallback?.call(this);
+      // Call original user-defined disconnectedCallback first
+      if (originalDisconnectedCallback) {
+        originalDisconnectedCallback.call(this);
+      }
       if (this[CONTROLLER]) {
         detachController(this).catch(error => {
           console.error(`Failed to detach controller:`, error);
@@ -254,7 +263,11 @@ export function element(tagName: string) {
         }
       }
     };
-    
+}
+
+export function element(tagName: string) {
+  return function (constructor: any) {
+    applyElementFunctionality(constructor);
     customElements.define(tagName, constructor);
   };
 }
@@ -428,4 +441,58 @@ export function watch(...propertyNames: string[]) {
     
     return descriptor;
   };
+}
+
+/**
+ * Decorator that injects router context into a property
+ * The context is automatically provided to page components by the router
+ */
+export function context() {
+  return function(target: any, propertyKey: string) {
+    // Define property getter that returns the context
+    Object.defineProperty(target, propertyKey, {
+      get() {
+        // First check if context is stored directly on this element
+        if (this[ROUTER_CONTEXT] !== undefined) {
+          return this[ROUTER_CONTEXT];
+        }
+        
+        // Otherwise, request context from parent page via event
+        const detail: any = { target: this };
+        const event = new CustomEvent('@context/request', {
+          bubbles: true,
+          cancelable: true,
+          detail
+        });
+        
+        // Dispatch event and wait for response
+        // For controllers, use their element. For elements, dispatch on the host
+        let targetElement = this.element || this;
+        
+        // If element is null (e.g., controller was detached), can't get context
+        if (!targetElement || !targetElement.dispatchEvent) {
+          return undefined;
+        }
+        
+        // If we're in shadow DOM, dispatch on the host element to ensure proper bubbling
+        if (targetElement.getRootNode && targetElement.getRootNode() instanceof ShadowRoot) {
+          const shadowRoot = targetElement.getRootNode() as ShadowRoot;
+          targetElement = shadowRoot.host as HTMLElement;
+        }
+        
+        targetElement.dispatchEvent(event);
+        
+        // Check if context was provided via the event
+        if (detail.context !== undefined) {
+          // Cache it for future use
+          this[ROUTER_CONTEXT] = detail.context;
+          return detail.context;
+        }
+        
+        return undefined;
+      },
+      enumerable: true,
+      configurable: true
+    });
+  };
 }

package/src/index.ts

@@ -1,10 +1,10 @@
-export { element, customElement, property, query, queryAll, watch } from './element';
+export { element, customElement, property, query, queryAll, watch, context, applyElementFunctionality } from './element';
 export { Router } from './router';
 export { controller, attachController, detachController, getController, useNativeElementControllers, cleanupNativeElementControllers } from './controller';
 export { on, dispatch } from './events';
 export { channel } from './channel';
 export type { PropertyOptions, PropertyConverter } from './element';
-export type { RouterOptions, PageOptions, PageTransition } from './router';
+export type { RouterOptions, PageOptions, PageTransition, Guard, RouteParams, RouterInstance } from './router';
 export type { IController, ControllerClass } from './controller';
 export type { DispatchOptions } from './events';
 export type { ChannelOptions } from './channel';

package/src/router.ts

@@ -1,5 +1,18 @@
 import Route from 'route-parser';
-import { setupEventHandlers, cleanupEventHandlers } from './events';
+import { applyElementFunctionality } from './element';
+import { ROUTER_CONTEXT, CONTEXT_REQUEST_HANDLER } from './symbols';
+
+/**
+ * Route parameters extracted from the URL
+ */
+export type RouteParams = Record<string, string>;
+
+/**
+ * Guard function that determines if navigation is allowed
+ * @param context The application context
+ * @param params The URL parameters from the route
+ */
+export type Guard<T = any> = (context: T, params: RouteParams) => boolean | Promise<boolean>;
 
 export interface RouterOptions {
   /**
@@ -11,7 +24,7 @@ export interface RouterOptions {
   /**
    * Whether to use hash routing or push state routing.
    */
-  routing_type: 'hash' | 'pushstate';
+  type: 'hash' | 'pushstate';
 
   /**
    * Override for the window object to use for routing, defaults to global.
@@ -27,6 +40,11 @@ export interface RouterOptions {
    * Global transition configuration for all pages
    */
   transition?: PageTransition;
+  
+  /**
+   * Optional context object passed to guard functions
+   */
+  context?: any;
 }
 
 export interface PageTransition {
@@ -79,6 +97,23 @@ export interface PageOptions {
    * Optional per-page transition override
    */
   transition?: PageTransition;
+  
+  /**
+   * Guard functions that must pass for navigation to proceed.
+   * Can be a single guard or an array of guards (all must pass).
+   */
+  guards?: Guard<any> | Guard<any>[];
+}
+
+/**
+ * Router return type
+ */
+export interface RouterInstance {
+  page: (pageOptions: PageOptions) => <C extends { new(...args: any[]): HTMLElement }>(constructor: C) => void;
+  initialize: () => void;
+  navigate: (path: string) => Promise<void>;
+  register: (route: string, tag: string, transition?: PageTransition, guards?: Guard<any> | Guard<any>[]) => void;
+  context: any;
 }
 
 /**
@@ -86,13 +121,15 @@ export interface PageOptions {
  * @param {RouterOptions} options - The router configuration options.
  * @returns An object containing the router's API methods.
  */
-export function Router(options: RouterOptions) {
-  const routes: { route: Route, tag: string, transition?: PageTransition }[] = [];
+export function Router(options: RouterOptions): RouterInstance {
+  const routes: { route: Route, tag: string, transition?: PageTransition, guards?: Guard<any> | Guard<any>[] }[] = [];
   let is_sorted = false;
 
   let _404: string; // the 404 page
+  let _403: string; // the 403 forbidden page
   let home: string; // the home page
   let currentPageElement: HTMLElement | null = null; // Track current page for transitions
+  const context = options.context || {}; // Store context for guards
 
   /**
    * Decorator function for defining a page with associated routes.
@@ -100,63 +137,55 @@ export function Router(options: RouterOptions) {
    * @returns A decorator function to apply to a custom element class.
    */
   function page(pageOptions: PageOptions) {
-    return function <T extends { new(...args: any[]): HTMLElement }>(constructor: T) {
+    return function <C extends { new(...args: any[]): HTMLElement }>(constructor: C) {
+      // Apply all element functionality (properties, queries, watchers, controllers, etc.)
+      applyElementFunctionality(constructor);
+      
       // Store transition config on constructor for later use
       (constructor as any).__transition = pageOptions.transition;
-      // Add event handler support
-      const originalConnectedCallback = constructor.prototype.connectedCallback;
-      const originalDisconnectedCallback = constructor.prototype.disconnectedCallback;
       
+      // Extend the connectedCallback to add router-specific functionality
+      const elementConnectedCallback = constructor.prototype.connectedCallback;
       constructor.prototype.connectedCallback = function() {
-        // Call original connectedCallback first to allow property initialization
-        originalConnectedCallback?.call(this);
-        
-        // Create shadow root if it doesn't exist
-        if (!this.shadowRoot) {
-          this.attachShadow({ mode: 'open' });
-        }
-        
-        // Build the shadow DOM content
-        let shadowContent = '';
+        // Call the element's connectedCallback first
+        elementConnectedCallback?.call(this);
         
-        // Add HTML first (maintaining original order)
-        if (this.html) {
-          const htmlContent = this.html();
-          if (htmlContent !== undefined) {
-            shadowContent += htmlContent;
+        // Setup context request handler for nested elements
+        const contextRequestHandler = (event: any) => {
+          // Only respond if this element has context
+          if (this[ROUTER_CONTEXT] !== undefined) {
+            event.detail.context = this[ROUTER_CONTEXT];
+            event.stopPropagation(); // Stop bubbling once context is provided
           }
-        }
+        };
+        this.addEventListener('@context/request', contextRequestHandler);
         
-        // Add CSS after HTML (maintaining original order)
-        if (this.css) {
-          const cssResult = this.css();
-          if (cssResult) {
-            // Handle both string and array of strings
-            const cssContent = Array.isArray(cssResult) ? cssResult.join('\n') : cssResult;
-            // No need for scoping with Shadow DOM, but add data attribute for compatibility
-            shadowContent += `<style data-component-css>${cssContent}</style>`;
-          }
-        }
-        
-        // Set shadow DOM content
-        if (shadowContent) {
-          this.shadowRoot.innerHTML = shadowContent;
-        }
-        // Setup @on event handlers - use element for host events, shadow root for delegated events
-        setupEventHandlers(this, this);
+        // Store handler for cleanup
+        (this as any)[CONTEXT_REQUEST_HANDLER] = contextRequestHandler;
       };
       
+      // Extend the disconnectedCallback to clean up router-specific stuff
+      const elementDisconnectedCallback = constructor.prototype.disconnectedCallback;
       constructor.prototype.disconnectedCallback = function() {
-        originalDisconnectedCallback?.call(this);
-        // Cleanup @on event handlers
-        cleanupEventHandlers(this);
+        // Call element's disconnectedCallback first
+        elementDisconnectedCallback?.call(this);
+        
+        // Clean up context request handler
+        const handler = (this as any)[CONTEXT_REQUEST_HANDLER];
+        if (handler) {
+          this.removeEventListener('@context/request', handler);
+          delete (this as any)[CONTEXT_REQUEST_HANDLER];
+        }
+        
+        // Clean up context reference
+        delete (this as any)[ROUTER_CONTEXT];
       };
       
       // Define the custom element
       customElements.define(pageOptions.tag, constructor);
 
-      // Register the routes
-      pageOptions.routes.forEach(route => register(route, pageOptions.tag));
+      // Register the routes with guards
+      pageOptions.routes.forEach(route => register(route, pageOptions.tag, pageOptions.transition, pageOptions.guards));
     }
   }
 
@@ -167,13 +196,17 @@ export function Router(options: RouterOptions) {
    * @example
    * register('/custom-route', 'custom-element');
    */
-  function register(route: string, tag: string, transition?: PageTransition): void {
-    routes.push({ route: new Route(route), tag, transition });
+  function register(route: string, tag: string, transition?: PageTransition, guards?: Guard<any> | Guard<any>[]): void {
+    routes.push({ route: new Route(route), tag, transition, guards });
     is_sorted = false;
 
     if (route === '/404') {
       _404 = tag;
     }
+    
+    if (route === '/403') {
+      _403 = tag;
+    }
 
     if (route === '/') {
       home = tag;
@@ -197,7 +230,7 @@ export function Router(options: RouterOptions) {
     }
 
     // Listen for navigation events
-    switch (options.routing_type) {
+    switch (options.type) {
       case 'hash':
         window.addEventListener('hashchange', () => {
           // Only navigate if target still exists
@@ -223,7 +256,7 @@ export function Router(options: RouterOptions) {
   }
   
   function get_path(): string {
-    switch (options.routing_type) {
+    switch (options.type) {
       case 'hash':
         return window.location.hash.slice(1);
       case 'pushstate':
@@ -245,10 +278,45 @@ export function Router(options: RouterOptions) {
 
     let newPageElement: HTMLElement | null = null;
     let transition: PageTransition | undefined;
+    let guards: Guard<any> | Guard<any>[] | undefined;
 
     // Home
     if ((path.trim() === '' || path === '/') && home) {
+      // Find home route to get guards
+      const homeRoute = routes.find(r => r.route.match('/'));
+      guards = homeRoute?.guards;
+      
+      // Check guards before creating element
+      if (guards) {
+        const guardsArray = Array.isArray(guards) ? guards : [guards];
+        for (const guard of guardsArray) {
+          const allowed = await guard(context, {});  // No params for home route
+          if (!allowed) {
+            // Render 403 page
+            if (_403) {
+              newPageElement = document.createElement(_403);
+              // Store context on 403 page too
+              (newPageElement as any)[ROUTER_CONTEXT] = context;
+            } else {
+              const div = document.createElement('div');
+              div.className = 'default-403';
+              div.innerHTML = '<h1>403</h1><p>Unauthorized</p>';
+              newPageElement = div;
+            }
+            // Don't perform transition for 403
+            target.innerHTML = '';
+            if (newPageElement) {
+              target.appendChild(newPageElement);
+            }
+            currentPageElement = newPageElement;
+            return;
+          }
+        }
+      }
+      
       newPageElement = document.createElement(home);
+      // Store context on the page element
+      (newPageElement as any)[ROUTER_CONTEXT] = context;
       const constructor = customElements.get(home);
       transition = (constructor as any)?.__transition;
     } else {
@@ -259,7 +327,37 @@ export function Router(options: RouterOptions) {
         const is_match = params !== false;
 
         if (is_match) {
+          // Check guards before creating element
+          if (route.guards) {
+            const guardsArray = Array.isArray(route.guards) ? route.guards : [route.guards];
+            for (const guard of guardsArray) {
+              const allowed = await guard(context, params as RouteParams);
+              if (!allowed) {
+                // Render 403 page
+                if (_403) {
+                  newPageElement = document.createElement(_403);
+                  // Store context on 403 page too
+                  (newPageElement as any)[ROUTER_CONTEXT] = context;
+                } else {
+                  const div = document.createElement('div');
+                  div.className = 'default-403';
+                  div.innerHTML = '<h1>403</h1><p>Unauthorized</p>';
+                  newPageElement = div;
+                }
+                // Don't perform transition for 403
+                target.innerHTML = '';
+                if (newPageElement) {
+                  target.appendChild(newPageElement);
+                }
+                currentPageElement = newPageElement;
+                return;
+              }
+            }
+          }
+          
           newPageElement = document.createElement(route.tag);
+          // Store context on the page element
+          (newPageElement as any)[ROUTER_CONTEXT] = context;
           Object.keys(params).forEach(key => newPageElement!.setAttribute(key, params[key]));
           transition = route.transition;
           break;
@@ -271,6 +369,8 @@ export function Router(options: RouterOptions) {
     if (!newPageElement) {
       if (_404) {
         newPageElement = document.createElement(_404);
+        // Store context on 404 page too
+        (newPageElement as any)[ROUTER_CONTEXT] = context;
         const constructor = customElements.get(_404);
         transition = (constructor as any)?.__transition;
       } else {
@@ -382,5 +482,11 @@ export function Router(options: RouterOptions) {
     containerStyle.position = originalPosition;
   }
 
-  return { page, initialize, navigate, register };
+  return { 
+    page, 
+    initialize, 
+    navigate, 
+    register,
+    context,
+  };
 }

package/src/symbols.ts

@@ -30,4 +30,8 @@ export const PROPERTIES = getSymbol('properties');
 export const PROPERTY_VALUES = getSymbol('property-values');
 export const PROPERTIES_INITIALIZED = getSymbol('properties-initialized');
 export const PROPERTY_WATCHERS = getSymbol('property-watchers');
-export const EXPLICITLY_SET_PROPERTIES = getSymbol('explicitly-set-properties');
+export const EXPLICITLY_SET_PROPERTIES = getSymbol('explicitly-set-properties');
+
+// Router context symbol
+export const ROUTER_CONTEXT = getSymbol('router-context');
+export const CONTEXT_REQUEST_HANDLER = getSymbol('context-request-handler');