snice 1.10.0 → 1.11.0

package/README.md

@@ -23,6 +23,68 @@ Snice takes an **imperative approach** to web components. Unlike reactive framew
 
 This approach gives you direct control over DOM updates without hidden complexity or automatic re-renders.
 
+## The Snice Way: Elements + Controllers
+
+Snice separates UI from data: **elements handle UI, controllers handle behavior and data**.
+
+```typescript
+import { element, controller, property, query } from 'snice';
+
+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;
+  }
+}
+
+// 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 */ }
+}
+```
+
+Connect them in HTML:
+```html
+<user-card user-id="123" controller="user-loader"></user-card>
+```
+
+That's it. Element renders UI, controller fetches data, they communicate through method calls, events, and request/response channels.
+
 ## Core Concepts
 
 Snice provides a clear separation of concerns through decorators:
@@ -80,10 +142,10 @@ class CounterDisplay extends HTMLElement {
   count = 0;
   
   @query('.count')
-  countElement?: HTMLElement;
+  countElement!: HTMLSpanElement;
   
   @query('.status')
-  statusElement?: HTMLElement;
+  statusElement!: HTMLSpanElement;
 
   html() {
     // Renders ONCE - no automatic re-rendering
@@ -98,15 +160,11 @@ class CounterDisplay extends HTMLElement {
   // Imperative update methods - YOU control when updates happen
   setCount(newCount: number) {
     this.count = newCount;
-    if (this.countElement) {
-      this.countElement.textContent = String(newCount);
-    }
+    this.countElement.textContent = String(newCount);
   }
   
   setStatus(status: string) {
-    if (this.statusElement) {
-      this.statusElement.textContent = status;
-    }
+    this.statusElement.textContent = status;
   }
   
   increment() {
@@ -191,7 +249,7 @@ class ThemeToggle extends HTMLElement {
   theme: 'light' | 'dark' = 'light';
   
   @query('.icon')
-  icon?: HTMLElement;
+  icon!: HTMLSpanElement;
   
   html() {
     return `
@@ -203,9 +261,7 @@ class ThemeToggle extends HTMLElement {
   
   @watch('theme')
   updateTheme(oldValue: string, newValue: string) {
-    if (this.icon) {
-      this.icon.textContent = newValue === 'dark' ? '🌙' : '🌞';
-    }
+    this.icon.textContent = newValue === 'dark' ? '🌙' : '🌞';
   }
   
   @on('click', 'button')
@@ -253,14 +309,14 @@ import { element, query } from 'snice';
 @element('my-form')
 class MyForm extends HTMLElement {
   @query('input')
-  input?: HTMLInputElement;
+  input!: HTMLInputElement;
 
   html() {
     return `<input type="text" />`;
   }
 
   getValue() {
-    return this.input?.value;
+    return this.input.value;
   }
 }
 ```
@@ -273,7 +329,7 @@ import { element, queryAll } from 'snice';
 @element('checkbox-group')
 class CheckboxGroup extends HTMLElement {
   @queryAll('input[type="checkbox"]')
-  checkboxes?: NodeListOf<HTMLInputElement>;
+  checkboxes!: NodeListOf<HTMLInputElement>;
 
   html() {
     return `
@@ -284,7 +340,6 @@ class CheckboxGroup extends HTMLElement {
   }
 
   getSelectedValues() {
-    if (!this.checkboxes) return [];
     return Array.from(this.checkboxes)
       .filter(cb => cb.checked)
       .map(cb => cb.value);
@@ -342,7 +397,7 @@ class ToggleSwitch extends HTMLElement {
   private isOn = false;
 
   @query('.toggle')
-  toggleButton?: HTMLElement;
+  toggleButton!: HTMLElement;
 
   html() {
     return `<button class="toggle">OFF</button>`;
@@ -352,9 +407,7 @@ class ToggleSwitch extends HTMLElement {
   @dispatch('toggled')
   toggle() {
     this.isOn = !this.isOn;
-    if (this.toggleButton) {
-      this.toggleButton.textContent = this.isOn ? 'ON' : 'OFF';
-    }
+    this.toggleButton.textContent = this.isOn ? 'ON' : 'OFF';
     return { on: this.isOn };
   }
 }
@@ -543,19 +596,21 @@ Controllers handle server communication separately from visual components:
 ```typescript
 import { controller, element } from 'snice';
 
+interface IUserElement extends HTMLElement {
+  setUsers(users: any[]): void;
+}
+
 @controller('user-controller')
 class UserController {
-  element: HTMLElement | null = null;
+  element!: IUserElement;
 
-  async attach(element: HTMLElement) {
+  async attach(element: IUserElement) {
     const response = await fetch('/api/users');
     const users = await response.json();
-    (element as any).setUsers(users);
+    element.setUsers(users);
   }
 
-  async detach(element: HTMLElement) {
-    // Cleanup
-  }
+  async detach(element: IUserElement) { /* Cleanup */ }
 }
 
 @element('user-list')
@@ -622,6 +677,70 @@ class UserController {
 }
 ```
 
+## Layouts
+
+Wrap your pages in shared layout components for consistent navigation, headers, and footers across your application.
+
+### Basic Layout Usage
+
+```typescript
+import { Router, layout, page } from 'snice';
+
+// 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>
+    `;
+  }
+}
+
+// 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>`;
+  }
+}
+
+// Override layout per page
+@page({ tag: 'full-page', routes: ['/fullscreen'], layout: false })
+class FullPage extends HTMLElement {
+  html() {
+    return `<div>No layout wrapper</div>`;
+  }
+}
+
+initialize();
+```
+
+### Layout Features
+
+- **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
+
 ## Router Context
 
 Access router context in page components, nested elements, and controllers using the `@context` decorator.
@@ -683,7 +802,7 @@ class ProfilePage extends HTMLElement {
 
 ### Context in Nested Elements
 
-Nested elements within pages can also access context through event bubbling:
+Nested elements within pages can also access context:
 
 ```typescript
 // This element can be used inside any page
@@ -720,7 +839,7 @@ Controllers attached to page elements automatically acquire context:
 ```typescript
 @controller('nav-controller')
 class NavController {
-  element: HTMLElement | null = null;
+  element!: HTMLElement;
   
   @context()
   ctx?: AppContext;
@@ -732,9 +851,7 @@ class NavController {
     }
   }
   
-  detach(element: HTMLElement) {
-    // Cleanup if needed
-  }
+  detach(element: HTMLElement) { /* Cleanup */ }
 }
 
 @page({ tag: 'admin-page', routes: ['/admin'] })
@@ -912,7 +1029,6 @@ The `@part` decorator is ideal when you have components with multiple independen
 - [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
-- [Migration Guide](./docs/migration-guide.md) - Migrating from React, Vue, Angular, and other frameworks
 
 ## License
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "snice",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "type": "module",
-  "description": "A TypeScript library",
+  "description": "Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.",
   "main": "src/index.ts",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -16,6 +16,40 @@
     "!src/**/*.test.ts",
     "!src/**/*.spec.ts"
   ],
+  "keywords": [
+    "web components",
+    "typescript",
+    "framework",
+    "decorators",
+    "custom elements",
+    "vanilla js",
+    "frontend",
+    "spa",
+    "routing",
+    "imperative",
+    "no virtual dom",
+    "lightweight",
+    "minimal",
+    "controllers",
+    "mvc",
+    "shadow dom",
+    "lit alternative",
+    "stencil alternative",
+    "web standards"
+  ],
+  "author": "hedzer",
+  "license": "MIT",
+  "homepage": "https://gitlab.com/Hedzer/snice#readme",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.com:Hedzer/snice.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/Hedzer/snice/-/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/element.ts

@@ -398,6 +398,13 @@ export function element(tagName: string) {
   };
 }
 
+export function layout(tagName: string) {
+  return function (constructor: any) {
+    applyElementFunctionality(constructor);
+    customElements.define(tagName, constructor);
+  };
+}
+
 export function property(options?: PropertyOptions) {
   return function (target: any, propertyKey: string) {
     const constructor = target.constructor;

package/src/index.ts

@@ -1,4 +1,4 @@
-export { element, property, query, queryAll, watch, context, applyElementFunctionality, ready, dispose, part, SimpleArray } from './element';
+export { element, layout, property, query, queryAll, watch, context, applyElementFunctionality, ready, dispose, part, SimpleArray } from './element';
 export { Router } from './router';
 export { controller, attachController, detachController, getController, useNativeElementControllers, cleanupNativeElementControllers } from './controller';
 export { on, dispatch } from './events';

package/src/router.ts

@@ -1,6 +1,6 @@
 import Route from 'route-parser';
 import { applyElementFunctionality } from './element';
-import { ROUTER_CONTEXT, CONTEXT_REQUEST_HANDLER, PAGE_TRANSITION } from './symbols';
+import { ROUTER_CONTEXT, CONTEXT_REQUEST_HANDLER, PAGE_TRANSITION, CREATED_AT } from './symbols';
 import { Transition, performTransition as performTransitionUtil } from './transitions';
 
 /**
@@ -8,6 +8,15 @@ import { Transition, performTransition as performTransitionUtil } from './transi
  */
 export type RouteParams = Record<string, string>;
 
+/**
+ * Possible outcomes from route resolution
+ */
+enum RouteResult {
+  SUCCESS = 'success',
+  GUARDS_FAILED = 'guards-failed',
+  NOT_FOUND = 'not-found'
+}
+
 /**
  * Guard function that determines if navigation is allowed
  * @param context The application context
@@ -46,6 +55,11 @@ export interface RouterOptions {
    * Optional context object passed to guard functions
    */
   context?: any;
+  
+  /**
+   * Default layout element tag name for all pages
+   */
+  layout?: string;
 }
 
 export interface PageOptions {
@@ -72,6 +86,12 @@ export interface PageOptions {
    * Can be a single guard or an array of guards (all must pass).
    */
   guards?: Guard<any> | Guard<any>[];
+  
+  /**
+   * Layout element tag name for this page.
+   * Use false to explicitly disable layout for this page.
+   */
+  layout?: string | false;
 }
 
 /**
@@ -91,15 +111,34 @@ export interface RouterInstance {
  * @returns An object containing the router's API methods.
  */
 export function Router(options: RouterOptions): RouterInstance {
-  const routes: { route: Route, tag: string, transition?: Transition, guards?: Guard<any> | Guard<any>[] }[] = [];
+  const routes: { route: Route, tag: string, transition?: Transition, guards?: Guard<any> | Guard<any>[], layout?: string | false }[] = [];
   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
+  let currentLayoutName: string | null = null; // Track current layout name
+  let currentLayoutTimestamp: number | null = null; // Track current layout timestamp
   const context = options.context || {}; // Store context for guards
 
+  function getCurrentLayoutElement(target: Element): HTMLElement | null {
+    const noCurrentLayout = !currentLayoutName || !currentLayoutTimestamp;
+    if (noCurrentLayout) {
+      return null;
+    }
+    
+    const layoutElements = target.querySelectorAll(currentLayoutName!) as NodeListOf<HTMLElement>;
+    
+    for (const element of layoutElements) {
+      const hasTimestamp = (element as any)[CREATED_AT] === currentLayoutTimestamp;
+      if (hasTimestamp) {
+        return element;
+      }
+    }
+    
+    return null;
+  }
+
   /**
    * Decorator function for defining a page with associated routes.
    * @param {PageOptions} pageOptions - The page configuration options.
@@ -153,8 +192,8 @@ export function Router(options: RouterOptions): RouterInstance {
       // Define the custom element
       customElements.define(pageOptions.tag, constructor);
 
-      // Register the routes with guards
-      pageOptions.routes.forEach(route => register(route, pageOptions.tag, pageOptions.transition, pageOptions.guards));
+      // Register the routes with guards and layout
+      pageOptions.routes.forEach(route => register(route, pageOptions.tag, pageOptions.transition, pageOptions.guards, pageOptions.layout));
     }
   }
 
@@ -165,8 +204,8 @@ export function Router(options: RouterOptions): RouterInstance {
    * @example
    * register('/custom-route', 'custom-element');
    */
-  function register(route: string, tag: string, transition?: Transition, guards?: Guard<any> | Guard<any>[]): void {
-    routes.push({ route: new Route(route), tag, transition, guards });
+  function register(route: string, tag: string, transition?: Transition, guards?: Guard<any> | Guard<any>[], layout?: string | false): void {
+    routes.push({ route: new Route(route), tag, transition, guards, layout });
     is_sorted = false;
 
     if (route === '/404') {
@@ -182,49 +221,59 @@ export function Router(options: RouterOptions): RouterInstance {
     }
   }
 
+  function setupEventListeners(): void {
+    const isHashType = options.type === 'hash';
+    const isPushStateType = options.type === 'pushstate';
+    
+    if (isHashType) {
+      window.addEventListener('hashchange', () => {
+        const targetExists = !!document.querySelector(options.target);
+        if (!targetExists) {
+          return;
+        }
+        
+        const path = getPath();
+        navigate(path);
+      });
+    }
+    
+    if (isPushStateType) {
+      window.addEventListener('popstate', () => {
+        const targetExists = !!document.querySelector(options.target);
+        if (!targetExists) {
+          return;
+        }
+        
+        const path = getPath();
+        navigate(path);
+      });
+    }
+  }
+
   /**
    * Initializes the router and sets up navigation event listeners.
    * @example
    * initialize();
    */
   function initialize(): void {
-    // Check if target exists before initializing
-    if (!document.querySelector(options.target)) {
+    const targetExists = !!document.querySelector(options.target);
+    if (!targetExists) {
       throw new Error(`Target element not found: ${options.target}`);
     }
     
-    if (!is_sorted) {
+    const needsSorting = !is_sorted;
+    if (needsSorting) {
       routes.sort((a: any, b: any) => b.route.spec.length - a.route.spec.length);
       is_sorted = true;
     }
 
-    // Listen for navigation events
-    switch (options.type) {
-      case 'hash':
-        window.addEventListener('hashchange', () => {
-          // Only navigate if target still exists
-          if (document.querySelector(options.target)) {
-            const path = get_path();
-            navigate(path);
-          }
-        });
-        break;
-      case 'pushstate':
-        window.addEventListener('popstate', () => {
-          // Only navigate if target still exists
-          if (document.querySelector(options.target)) {
-            const path = get_path();
-            navigate(path);
-          }
-        });
-        break;
-    }
+    setupEventListeners();
 
-    const path = get_path();
+    const path = getPath();
     navigate(path);
   }
   
-  function get_path(): string {
+  function getPath(): string {
     switch (options.type) {
       case 'hash':
         return window.location.hash.slice(1);
@@ -233,6 +282,181 @@ export function Router(options: RouterOptions): RouterInstance {
     }
   }
   
+  async function renderForbiddenPage(target: Element): Promise<void> {
+    let newPageElement: HTMLElement;
+    const has403Page = !!_403;
+    
+    if (has403Page) {
+      newPageElement = document.createElement(_403);
+      (newPageElement as any)[ROUTER_CONTEXT] = context;
+    }
+    if (!has403Page) {
+      const div = document.createElement('div');
+      div.className = 'default-403';
+      div.innerHTML = /*html*/`<h1>403</h1><p>Unauthorized</p>`;
+      newPageElement = div;
+    }
+    
+    target.innerHTML = '';
+    target.appendChild(newPageElement!);
+    currentLayoutName = null;
+    currentLayoutTimestamp = null;
+  }
+
+  async function checkGuards(guards: Guard<any> | Guard<any>[] | undefined, params: RouteParams, target: Element): Promise<boolean> {
+    const hasGuards = !!guards;
+    if (!hasGuards) {
+      return true;
+    }
+    
+    const guardsArray = Array.isArray(guards) ? guards : [guards];
+    for (const guard of guardsArray) {
+      const allowed = await guard(context, params);
+      if (!allowed) {
+        await renderForbiddenPage(target);
+        return false;
+      }
+    }
+    return true;
+  }
+
+  function createHomeElement(): { element: HTMLElement; transition?: Transition; layout?: string | false } {
+    const newPageElement = document.createElement(home);
+    (newPageElement as any)[ROUTER_CONTEXT] = context;
+    const constructor = customElements.get(home);
+    const transition = (constructor as any)?.[PAGE_TRANSITION];
+    
+    const homeRoute = routes.find(r => r.route.match('/'));
+    return { element: newPageElement, transition, layout: homeRoute?.layout };
+  }
+
+  function create404Element(): { element: HTMLElement; transition?: Transition; layout?: string | false } {
+    const has404Page = !!_404;
+    
+    if (has404Page) {
+      const newPageElement = document.createElement(_404);
+      (newPageElement as any)[ROUTER_CONTEXT] = context;
+      const constructor = customElements.get(_404);
+      const transition = (constructor as any)?.[PAGE_TRANSITION];
+      return { element: newPageElement, transition, layout: undefined };
+    }
+    
+    const div = document.createElement('div');
+    div.className = 'default-404';
+    div.innerHTML = /*html*/`<h1>404</h1><p>Page not found</p>`;
+    return { element: div, transition: undefined, layout: undefined };
+  }
+
+  async function resolveRoute(path: string, target: Element): Promise<{ result: RouteResult; element?: HTMLElement; transition?: Transition; layout?: string | false }> {
+    for (const route of routes) {
+      const params = route.route.match(path);
+      const isMatch = params !== false;
+      if (!isMatch) {
+        continue;
+      }
+      
+      const guardsAllowed = await checkGuards(route.guards, params as RouteParams, target);
+      if (!guardsAllowed) {
+        return { result: RouteResult.GUARDS_FAILED };
+      }
+      
+      const newPageElement = document.createElement(route.tag);
+      (newPageElement as any)[ROUTER_CONTEXT] = context;
+      const routeParams = params as RouteParams;
+      Object.keys(routeParams).forEach(key => newPageElement.setAttribute(key, routeParams[key]));
+      
+      return { result: RouteResult.SUCCESS, element: newPageElement, transition: route.transition, layout: route.layout };
+    }
+    
+    return { result: RouteResult.NOT_FOUND };
+  }
+
+  function determineLayout(pageLayout: string | false | undefined): string | null {
+    const isExplicitlyNoLayout = pageLayout === false;
+    if (isExplicitlyNoLayout) {
+      return null;
+    }
+    
+    const hasPageLayout = !!pageLayout;
+    if (hasPageLayout) {
+      return pageLayout;
+    }
+    
+    const hasRouterLayout = !!options.layout;
+    if (hasRouterLayout) {
+      return options.layout!;
+    }
+    
+    return null;
+  }
+
+  function setupLayout(layoutToUse: string | null): { element: HTMLElement | null; needsNewLayout: boolean } {
+    const needsNewLayout = layoutToUse !== currentLayoutName;
+    if (!needsNewLayout) {
+      return { element: null, needsNewLayout: false };
+    }
+    
+    currentLayoutName = layoutToUse;
+    
+    const shouldCreateLayout = !!layoutToUse;
+    if (shouldCreateLayout) {
+      const timestamp = Date.now();
+      currentLayoutTimestamp = timestamp;
+      
+      const layoutElement = document.createElement(layoutToUse);
+      (layoutElement as any)[ROUTER_CONTEXT] = context;
+      (layoutElement as any)[CREATED_AT] = timestamp;
+      
+      return { element: layoutElement, needsNewLayout: true };
+    }
+    
+    currentLayoutTimestamp = null;
+    return { element: null, needsNewLayout: true };
+  }
+
+  async function renderWithLayout(target: Element, pageElement: HTMLElement, transition: Transition | undefined, layoutElement: HTMLElement | null, needsNewLayout: boolean): Promise<void> {
+    const currentLayout = layoutElement || getCurrentLayoutElement(target);
+    if (!currentLayout) {
+      return;
+    }
+    
+    const oldPageInLayout = currentLayout.querySelector('[slot="page"]') as HTMLElement | null;
+    const shouldTransition = !!(transition && oldPageInLayout);
+    
+    if (shouldTransition) {
+      pageElement.setAttribute('slot', 'page');
+      await performTransition(currentLayout, oldPageInLayout!, pageElement, transition!);
+      if (needsNewLayout) {
+        target.innerHTML = '';
+        target.appendChild(currentLayout);
+      }
+      return;
+    }
+    
+    const existingPages = currentLayout.querySelectorAll('[slot="page"]');
+    existingPages.forEach(page => page.remove());
+    pageElement.setAttribute('slot', 'page');
+    currentLayout.appendChild(pageElement);
+    
+    if (needsNewLayout) {
+      target.innerHTML = '';
+      target.appendChild(currentLayout);
+    }
+  }
+
+  async function renderDirect(target: Element, pageElement: HTMLElement, transition: Transition | undefined): Promise<void> {
+    const currentElementInTarget = target.children[0] as HTMLElement | null;
+    const shouldTransition = !!(transition && currentElementInTarget);
+    
+    if (shouldTransition) {
+      await performTransition(target, currentElementInTarget!, pageElement, transition!);
+      return;
+    }
+    
+    target.innerHTML = '';
+    target.appendChild(pageElement);
+  }
+
   /**
    * Navigates to the specified path.
    * @param {string} path - The path to navigate to.
@@ -245,127 +469,68 @@ export function Router(options: RouterOptions): RouterInstance {
       throw new Error(`Target element not found: ${options.target}`);
     }
 
-    let newPageElement: HTMLElement | null = null;
-    let transition: Transition | undefined;
-    let guards: Guard<any> | Guard<any>[] | undefined;
+    window.scrollTo(0, 0);
 
-    // Home
-    if ((path.trim() === '' || path === '/') && home) {
-      // Find home route to get guards
+    const isHomePath = (path.trim() === '' || path === '/') && !!home;
+    
+    if (isHomePath) {
       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;
-          }
-        }
+      const guardsAllowed = await checkGuards(homeRoute?.guards, {}, target);
+      if (!guardsAllowed) {
+        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)?.[PAGE_TRANSITION];
-    } else {
-
-      // Get the current route
-      for (const route of routes) {
-        const params = route.route.match(path);
-        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;
-        }
+      const { element, transition, layout } = createHomeElement();
+      const layoutToUse = determineLayout(layout);
+      const { element: layoutElement, needsNewLayout } = setupLayout(layoutToUse);
+      const finalTransition = transition || options.transition;
+      
+      const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
+      if (hasLayout) {
+        await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout);
+        return;
       }
+      
+      await renderDirect(target, element, finalTransition);
+      return;
     }
-
-    // 404
-    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)?.[PAGE_TRANSITION];
-      } else {
-        // Provide a default 404 page
-        const div = document.createElement('div');
-        div.className = 'default-404';
-        div.innerHTML = '<h1>404</h1><p>Page not found</p>';
-        newPageElement = div;
-      }
+    
+    const routeResult = await resolveRoute(path, target);
+    
+    const isGuardsFailed = routeResult.result === RouteResult.GUARDS_FAILED;
+    if (isGuardsFailed) {
+      return;
     }
-
-    // Use page-specific or global transition
-    transition = transition || options.transition;
-
-    // Perform transition
-    if (transition && currentPageElement && currentPageElement.parentElement) {
-      await performTransition(target, currentPageElement, newPageElement!, transition);
-    } else {
-      // No transition, just swap
-      target.innerHTML = '';
-      if (newPageElement) {
-        target.appendChild(newPageElement);
+    
+    const isSuccess = routeResult.result === RouteResult.SUCCESS;
+    if (isSuccess) {
+      const { element, transition, layout } = routeResult;
+      const layoutToUse = determineLayout(layout);
+      const { element: layoutElement, needsNewLayout } = setupLayout(layoutToUse);
+      const finalTransition = transition || options.transition;
+      
+      const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
+      if (hasLayout) {
+        await renderWithLayout(target, element!, finalTransition, layoutElement, needsNewLayout);
+        return;
       }
+      
+      await renderDirect(target, element!, finalTransition);
+      return;
     }
-
-    currentPageElement = newPageElement;
+    
+    const { element, transition, layout } = create404Element();
+    const layoutToUse = determineLayout(layout);
+    const { element: layoutElement, needsNewLayout } = setupLayout(layoutToUse);
+    const finalTransition = transition || options.transition;
+    
+    const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
+    if (hasLayout) {
+      await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout);
+      return;
+    }
+    
+    await renderDirect(target, element, finalTransition);
   }
 
   async function performTransition(

package/src/symbols.ts

@@ -35,8 +35,10 @@ export const EXPLICITLY_SET_PROPERTIES = getSymbol('explicitly-set-properties');
 
 // Router context symbol
 export const ROUTER_CONTEXT = getSymbol('router-context');
+export const CURRENT_PAGE_MARKER = getSymbol('current-page-marker');
 export const CONTEXT_REQUEST_HANDLER = getSymbol('context-request-handler');
 export const PAGE_TRANSITION = getSymbol('page-transition');
+export const CREATED_AT = getSymbol('created-at');
 
 // Lifecycle symbols
 export const READY_HANDLERS = getSymbol('ready-handlers');

package/src/transitions.ts

@@ -71,22 +71,42 @@ export async function performTransition(
   const inEndStyles = transition.in ? parseStyles(transition.in) : { opacity: '1' };
 
   // Set container to relative positioning to allow absolute positioning
+  // Skip for layout elements to avoid jumpy transitions
   const containerStyle = (container as HTMLElement).style;
   const originalPosition = containerStyle.position;
-  containerStyle.position = 'relative';
-
-  // Style old element for transition
-  oldElement.style.position = 'absolute';
-  oldElement.style.top = '0';
-  oldElement.style.left = '0';
-  oldElement.style.width = '100%';
-  oldElement.style.transition = `all ${outDuration}ms ease-in-out`;
-
-  // Style new element with initial state
-  newElement.style.position = 'absolute';
-  newElement.style.top = '0';
-  newElement.style.left = '0';
-  newElement.style.width = '100%';
+  const isLayoutElement = container.tagName.includes('-') && container.shadowRoot;
+  
+  if (!isLayoutElement) {
+    containerStyle.position = 'relative';
+  }
+
+  // Check if elements are slotted (inside a layout)
+  const isSlottedTransition = oldElement.hasAttribute('slot') || newElement.hasAttribute('slot');
+  
+  if (isSlottedTransition) {
+    // For slotted elements, use absolute with width/height for crossfade
+    oldElement.style.position = 'absolute';
+    oldElement.style.width = '100%';
+    oldElement.style.height = '100%';
+    oldElement.style.transition = `opacity ${outDuration}ms ease-in-out`;
+    
+    newElement.style.position = 'absolute';
+    newElement.style.width = '100%';
+    newElement.style.height = '100%';
+    newElement.style.transition = `opacity ${inDuration}ms ease-in-out`;
+  } else {
+    // Original absolute positioning for non-slotted elements
+    oldElement.style.position = 'absolute';
+    oldElement.style.top = '0';
+    oldElement.style.left = '0';
+    oldElement.style.width = '100%';
+    oldElement.style.transition = `all ${outDuration}ms ease-in-out`;
+
+    newElement.style.position = 'absolute';
+    newElement.style.top = '0';
+    newElement.style.left = '0';
+    newElement.style.width = '100%';
+  }
   Object.assign(newElement.style, inStartStyles);
   newElement.style.transition = `all ${inDuration}ms ease-in-out`;
 
@@ -114,16 +134,29 @@ export async function performTransition(
 
   // Cleanup
   oldElement.remove();
-  newElement.style.position = '';
-  newElement.style.top = '';
-  newElement.style.left = '';
-  newElement.style.width = '';
-  newElement.style.transition = '';
+  
+  if (isSlottedTransition) {
+    // Cleanup for slotted elements
+    newElement.style.position = '';
+    newElement.style.width = '';
+    newElement.style.height = '';
+    newElement.style.transition = '';
+  } else {
+    // Cleanup for non-slotted elements
+    newElement.style.position = '';
+    newElement.style.top = '';
+    newElement.style.left = '';
+    newElement.style.width = '';
+    newElement.style.transition = '';
+  }
+  
   // Reset any transition styles
   Object.keys({...inStartStyles, ...inEndStyles}).forEach(prop => {
     newElement.style[prop as any] = '';
   });
-  containerStyle.position = originalPosition;
+  if (!isLayoutElement) {
+    containerStyle.position = originalPosition;
+  }
 }
 
 /**

package/bin/templates/base/src/styles/shared.ts

@@ -1,82 +0,0 @@
-export const containerStyles = `
-  .container {
-    max-width: 1200px;
-    margin: 0 auto;
-    padding: 2rem;
-  }
-  
-  .btn {
-    padding: 0.75rem 1.5rem;
-    border-radius: 6px;
-    text-decoration: none;
-    font-weight: 600;
-    transition: all 0.3s ease;
-    cursor: pointer;
-    border: none;
-    display: inline-block;
-  }
-  
-  .btn-primary {
-    background: var(--primary-color);
-    color: white;
-  }
-  
-  .btn-primary:hover {
-    background: var(--secondary-color);
-    transform: translateY(-2px);
-  }
-  
-  .btn-secondary {
-    background: transparent;
-    color: var(--primary-color);
-    border: 2px solid var(--primary-color);
-  }
-  
-  .btn-secondary:hover {
-    background: var(--primary-color);
-    color: white;
-  }
-`;
-
-export const navbarStyles = `
-  .navbar {
-    background: var(--white);
-    box-shadow: var(--shadow);
-    position: sticky;
-    top: 0;
-    z-index: 100;
-  }
-  
-  .nav-container {
-    max-width: 1200px;
-    margin: 0 auto;
-    padding: 1rem 2rem;
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-  }
-  
-  .nav-brand {
-    font-size: 1.5rem;
-    font-weight: 700;
-    color: var(--primary-color);
-  }
-  
-  .nav-menu {
-    display: flex;
-    list-style: none;
-    gap: 2rem;
-  }
-  
-  .nav-link {
-    color: var(--text-light);
-    text-decoration: none;
-    font-weight: 500;
-    transition: color 0.3s;
-  }
-  
-  .nav-link:hover,
-  .nav-link.active {
-    color: var(--primary-color);
-  }
-`;