metaowl 0.3.5 → 0.4.0

package/README.md

@@ -4,10 +4,12 @@
 
 [![npm version](https://img.shields.io/npm/v/metaowl.svg)](https://www.npmjs.com/package/metaowl)
 [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](LICENSE)
-[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 [![GitHub Issues](https://img.shields.io/github/issues/dennisschott/metaowl.svg)](https://github.com/dennisschott/metaowl/issues)
 
-metaowl is a complete solution for building production-ready OWL applications with everything you need out of the box:
+> ⚠️ **Work in progress:** metaowl is not production-ready yet. APIs may change without notice, and features may still break between releases.
+
+metaowl is a complete solution for building OWL applications with everything you need out of the box:
 
 **Core Infrastructure:** File-based routing with dynamic routes, layout system, navigation guards, Pinia-inspired state management, and zero-config app mounting.
 
@@ -34,6 +36,7 @@ All powered by a batteries-included Vite plugin that handles the build pipeline,
   - [Dynamic Routes](#dynamic-routes)
 - [Layouts](#layouts)
 - [Navigation Guards](#navigation-guards)
+- [Link Component](#link-component)
 - [State Management](#state-management-store)
 - [Error Boundaries](#error-boundaries)
 - [i18n / Internationalization](#i18n--internationalization)
@@ -52,6 +55,7 @@ All powered by a batteries-included Vite plugin that handles the build pipeline,
   - [Store](#store)
   - [Layouts API](#layouts-api)
   - [Router Guards](#router-guards-api)
+  - [Link Component API](#link-component-api)
   - [Error Boundary](#error-boundary-api)
   - [i18n](#i18n-api)
   - [Forms](#forms-api)
@@ -75,6 +79,7 @@ All powered by a batteries-included Vite plugin that handles the build pipeline,
 - **Dynamic routes** — support for parameters `[id]`, optional params `[id]?`, and catch-all `[...path]`
 - **Layouts** — share page structures across routes with automatic layout resolution
 - **Navigation guards** — route middleware for authentication, authorization, and redirects
+- **SPA Link component** — `<Link>` for SPA navigation without page reloads and automatic external link detection
 - **State management** — Pinia-like store system with mutations, actions, and getters
 - **App mounting** — zero-config OWL component mounting with template merging
 - **Fetch helper** — thin wrapper around the Fetch API with a configurable base URL and error handler
@@ -99,7 +104,7 @@ All powered by a batteries-included Vite plugin that handles the build pipeline,
 
 | Dependency | Version |
 |---|---|
-| Node.js | `>=18` |
+| Node.js | `>=20` |
 | `@odoo/owl` | bundled |
 
 ---
@@ -431,6 +436,139 @@ export class AdminPage extends Component {
 
 ---
 
+## Link Component
+
+The `Link` component provides SPA-style navigation without page reloads. It renders a standard `<a>` element and automatically handles internal navigation via `history.pushState`, while allowing normal browser behavior for external links.
+
+### Setup
+
+Import `Link` from `metaowl` and register it in your component's `static components`:
+
+```js
+import { Component } from '@odoo/owl'
+import { Link } from 'metaowl'
+
+export class MyNav extends Component {
+  static template = 'MyNav'
+  static components = { Link }
+
+  setup() {
+    this.linkClass = (href) => {
+      const base = 'block px-3 py-2 rounded-md text-sm'
+      const active = 'bg-gray-100 text-gray-900'
+      const inactive = 'text-gray-600 hover:bg-gray-100'
+      const isActive = window.location.pathname === href
+      return `${base} ${isActive ? active : inactive}`
+    }
+  }
+}
+```
+
+### Basic Usage
+
+Prop values are OWL expressions — wrap static strings in extra quotes, or pass method calls:
+
+```xml
+<!-- Internal link -->
+<Link to="'/about'">About Us</Link>
+
+<!-- Dynamic target from loop -->
+<Link to="item.href"><t t-esc="item.label"/></Link>
+
+<!-- Computed class via method -->
+<Link to="item.href" class="linkClass(item.href)">
+  <t t-esc="item.label"/>
+</Link>
+
+<!-- External link — opens normally (auto-detected, no SPA intercept) -->
+<Link to="'https://github.com/odoo/owl'" target="'_blank'">
+  OWL Framework
+</Link>
+
+<!-- External with dynamic target, closing sidebar on click -->
+<Link
+  to="link.href"
+  target="link.external ? '_blank' : undefined"
+  t-on-click="props.onClose"
+  class="linkClass(link.href)"
+>
+  <span t-esc="link.label"/>
+</Link>
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `to` | `string` | Yes | Target URL (internal path or external URL) |
+| `class` | `string` | No | CSS classes for the anchor element |
+| `target` | `string` | No | Target window (`_blank`, `_self`, etc.) |
+| `rel` | `string` | No | Relationship attribute (auto-set to `noopener noreferrer` for external `_blank` links) |
+| `title` | `string` | No | Tooltip text |
+| `download` | `string \| boolean` | No | Download attribute for file downloads |
+| `hreflang` | `string` | No | Language of the linked resource |
+| `type` | `string` | No | MIME type hint |
+| `ping` | `string` | No | Space-separated URLs to ping on click |
+| `referrerpolicy` | `string` | No | Referrer policy override |
+| `media` | `string` | No | Media query hint |
+
+Any additional attribute (`id`, `style`, `aria-*`, `data-*`, etc.) is forwarded directly to the rendered `<a>` element.
+
+### External Link Detection
+
+The component automatically detects external links and performs normal navigation:
+
+- URLs starting with `http://` or `https://`
+- Protocol-relative URLs (`//example.com`)
+- Special protocols: `mailto:`, `tel:`, `ftp:`, etc.
+
+### Programmatic Navigation
+
+Use `navigateTo()` for programmatic navigation in JavaScript:
+
+```js
+import { navigateTo } from 'metaowl'
+
+// Navigate to a new route
+await navigateTo('/dashboard')
+
+// Replace current history entry (no back button)
+await navigateTo('/login', { replace: true })
+```
+
+### Router API
+
+```js
+import { router, navigateTo } from 'metaowl'
+
+// Navigation
+router.push('/path')           // Navigate to path
+router.replace('/path')        // Replace current history entry
+router.navigateTo('/path')     // SPA navigation
+router.back()                  // Go back
+router.forward()               // Go forward
+router.go(-2)                  // Go 2 steps back
+
+// Guards
+router.beforeEach((to, from, next) => { ... })
+router.afterEach((to, from) => { ... })
+
+// State
+router.currentRoute    // Current route object
+router.previousRoute   // Previous route object
+router.isNavigating    // Boolean indicating navigation in progress
+```
+
+### SPA Mode
+
+SPA navigation is enabled by default when using `boot()`. To disable:
+
+```js
+boot(routes, null, { spa: false })
+```
+
+---
+
 ## State Management (Store)
 
 A Pinia-inspired store system with mutations, actions, and getters.
@@ -1010,6 +1148,56 @@ router.push('/new-path')
 
 ---
 
+### `Link Component API`
+
+```xml
+<Link to="item.href" class="linkClass(item.href)" target="item.external ? '_blank' : undefined">
+  <t t-esc="item.label"/>
+</Link>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `to` | `string` | Target URL (required) |
+| `class` | `string` | CSS classes |
+| `target` | `string` | Target window (`_blank`, `_self`) |
+| `rel` | `string` | Link relationship (auto: `noopener noreferrer` for external `_blank`) |
+| `title` | `string` | Tooltip text |
+| `download` | `string \| boolean` | Download attribute |
+| `hreflang` | `string` | Language of the linked resource |
+| `type` | `string` | MIME type hint |
+| `ping` | `string` | URLs to ping on click |
+| `referrerpolicy` | `string` | Referrer policy override |
+| `media` | `string` | Media query hint |
+
+All other attributes (`id`, `style`, `aria-*`, `data-*`, etc.) are forwarded to the `<a>` element.
+
+**Programmatic Navigation:**
+
+```js
+import { navigateTo, router } from 'metaowl'
+
+// Navigate to new route (SPA mode)
+await navigateTo('/dashboard')
+
+// Replace current history entry
+await navigateTo('/login', { replace: true })
+
+// Using router singleton
+router.push('/path')
+router.replace('/path')
+router.back()
+router.forward()
+router.go(-2)
+```
+
+**External Link Detection:**
+- `http://` or `https://` → Normal navigation
+- `//` → Protocol-relative, normal navigation
+- `mailto:`, `tel:`, `ftp:` → Normal navigation
+
+---
+
 ### `Error Boundary API`
 
 | Function | Description |
@@ -1464,6 +1652,26 @@ npx serve -s dist
 
 ---
 
+## Changelog
+
+### v0.4.0 (2026-03-24)
+
+**Added:**
+
+- **Link component** added.
+
+### v0.3.7 (2026-03-24)
+
+**Fixed:**
+
+- **bin/metaowl-lint.js**: Fixed inconsistent default lint paths. Changed from `src/owl/pages/**` and `src/owl/components/**` to `src/pages/**` and `src/components/**` to match the documented project structure.
+
+- **eslint.js**: Fixed `ignores` configuration placement. Moved `ignores` to a separate configuration object as required by ESLint Flat Config format. Also added `.metaowl/**` to the ignore list for the auto-generated component declarations.
+
+- **modules/auto-import.js**: Fixed missing `node:` prefix for Node.js built-in module import.
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please open an issue before submitting a pull request so we can discuss the change.

package/bin/metaowl-lint.js

@@ -27,8 +27,8 @@ try {
 const defaults = [
   'src/metaowl.js',
   'src/css.js',
-  'src/owl/pages/**',
-  'src/owl/components/**'
+  'src/pages/**',
+  'src/components/**'
 ]
 
 const candidates = lintTargets ?? defaults

package/eslint.js

@@ -39,11 +39,14 @@ export const eslintConfig = [
       'quotes': ['error', 'single'],
       'comma-dangle': ['error', 'never'],
       'no-undef': 'off'
-    },
+    }
+  },
+  {
     ignores: [
       'node_modules/**',
       'dist/**',
-      'build/**'
+      'build/**',
+      '.metaowl/**'
     ]
   }
 ]

package/index.js

@@ -1,6 +1,6 @@
 import { mountApp } from './modules/app-mounter.js'
 import { buildRoutes } from './modules/file-router.js'
-import { processRoutes } from './modules/router.js'
+import { processRoutes, setSpaMode, _setSpaNavigationCallback } from './modules/router.js'
 import { discoverLayouts, buildLayouts, setDefaultLayout } from './modules/layouts.js'
 
 export { default as Fetch } from './modules/fetch.js'
@@ -39,13 +39,17 @@ export {
   isNavigating,
   cancelNavigation,
   navigate,
+  navigateTo,
   push,
   replace,
   back,
   forward,
   go,
-  router
+  router,
+  setSpaMode,
+  isSpaMode
 } from './modules/router.js'
+export { Link, registerLinkTemplate } from './modules/link.js'
 export {
   matchRoute,
   isDynamicRoute,
@@ -156,6 +160,91 @@ export {
   PWA
 } from './modules/pwa.js'
 
+/**
+ * Global routes reference for SPA navigation.
+ * @type {object[]|null}
+ */
+let _appRoutes = null
+
+/**
+ * Monotonically-increasing navigation counter.
+ * Incremented on every navigation attempt; lets us discard stale navigations
+ * that complete AFTER a newer one was already triggered.
+ * @type {number}
+ */
+let _navSeq = 0
+
+/**
+ * Promise of the currently-running mountApp call.
+ * Used to serialize mounts: a new navigation waits for the in-progress mount
+ * to finish, then checks if it is still the latest before mounting itself.
+ * This prevents concurrent OWL App instances on the same element.
+ * @type {Promise<void>|null}
+ */
+let _mountingPromise = null
+
+function _handle404() {
+  const el = document.getElementById('metaowl')
+  if (el) {
+    el.innerHTML = [
+      '<div style="font-family:sans-serif;padding:3rem;text-align:center">',
+      '<h1 style="font-size:4rem;font-weight:700;margin:0;color:#6b7280">404</h1>',
+      '<p style="font-size:1.25rem;color:#9ca3af;margin-top:0.5rem">Page not found</p>',
+      '<p style="margin-top:2rem"><a href="/" style="color:#3b82f6;text-decoration:none">← Go home</a></p>',
+      '</div>'
+    ].join('')
+  }
+}
+
+/**
+ * SPA navigation callback.
+ * Called when navigateTo() is used.
+ *
+ * @param {string} path - The target path
+ * @returns {Promise<void>}
+ */
+async function _spaNavigate(path) {
+  if (!_appRoutes) {
+    console.error('[metaowl] Routes not available for SPA navigation')
+    return
+  }
+
+  const seq = ++_navSeq
+
+  let route
+  try {
+    route = await processRoutes(_appRoutes, path)
+  } catch (error) {
+    if (seq !== _navSeq) return
+    if (error.message && error.message.startsWith('No route found')) {
+      console.warn('[metaowl]', error.message)
+      _handle404()
+    } else {
+      throw error
+    }
+    return
+  }
+
+  // Bail early if a newer navigation overtook us while processRoutes was running
+  if (seq !== _navSeq || !route) return
+
+  // Wait for any in-progress mount to finish before starting our own.
+  // This is the key serialization: it ensures only one OWL App mounts at a time.
+  if (_mountingPromise) {
+    await _mountingPromise.catch(() => {})
+    // After waiting, check again — a newer navigation may have started
+    if (seq !== _navSeq) return
+  }
+
+  // Claim the mount slot
+  _mountingPromise = mountApp(route)
+  try {
+    await _mountingPromise
+  } finally {
+    _mountingPromise = null
+  }
+}
+
 /**
  * Boots the metaowl application.
  *
@@ -170,14 +259,21 @@ export {
  *       boot([{ name: 'index', path: ['/'], component: IndexPage }])
  *
  * @param {Record<string, object>|object[]} [routesOrModules]
+ * @param {object} [options] - Boot options
+ * @param {boolean} [options.spa=true] - Enable SPA navigation mode
  */
-export async function boot(routesOrModules = {}, layoutsOrModules = null) {
+export async function boot(routesOrModules = {}, layoutsOrModules = null, options = {}) {
+  const { spa = true } = options
+
   // Auto-discover layouts
   try {
-    if (layoutsOrModules) {
+    if (layoutsOrModules && typeof layoutsOrModules === 'object' && !Array.isArray(layoutsOrModules)) {
       // Use layouts provided by Vite plugin transformation
       buildLayouts(layoutsOrModules)
       setDefaultLayout('default')
+    } else if (typeof layoutsOrModules === 'object' && layoutsOrModules?.spa !== undefined) {
+      // Options object passed as second argument
+      Object.assign(options, layoutsOrModules)
     } else {
       await discoverLayouts()
     }
@@ -189,6 +285,24 @@ export async function boot(routesOrModules = {}, layoutsOrModules = null) {
     ? routesOrModules
     : buildRoutes(routesOrModules)
 
+  // Store routes for SPA navigation
+  _appRoutes = routes
+
+  // Enable SPA mode
+  if (spa) {
+    setSpaMode(true)
+    _setSpaNavigationCallback(_spaNavigate)
+
+    // Register global navigateTo handler for Link component
+    window.__metaowlNavigate = _spaNavigate
+
+    // Listen to PopState events (Browser Back/Forward)
+    window.addEventListener('popstate', (event) => {
+      const path = document.location.pathname
+      _spaNavigate(path)
+    })
+  }
+
   let route
   try {
     route = await processRoutes(routes)

package/modules/app-mounter.js

@@ -8,6 +8,7 @@
 import { mount } from '@odoo/owl'
 import { mergeTemplates } from './templates-manager.js'
 import { resolveLayout, getLayout, mountWithLayout } from './layouts.js'
+import { Link } from './link.js'
 
 const _defaults = {
   warnIfNoStaticProps: true,
@@ -17,6 +18,13 @@ const _defaults = {
 
 let _config = { ..._defaults }
 
+/**
+ * Reference to the currently mounted OWL App instance.
+ * Destroyed before each new mount to prevent zombie app accumulation.
+ * @type {import('@odoo/owl').App|null}
+ */
+let _currentApp = null
+
 /**
  * Override or extend the default OWL mount configuration.
  * Call before boot() in your project's metaowl.js.
@@ -37,11 +45,31 @@ export function configureOwl(config) {
  * @param {object[]} route - Single-element array returned by `processRoutes()`.
  * @returns {Promise<void>}
  */
+/**
+ * Cached merged templates string. Computed once on first navigation;
+ * COMPONENTS (the list of XML files) never changes at runtime so the
+ * result is the same for every mount.
+ * @type {string|null}
+ */
+let _cachedTemplates = null
+
 export async function mountApp(route) {
-  // COMPONENTS is a string[] injected at build time by the metaowl Vite plugin
+  // Load and cache templates on first call; reuse on every subsequent navigation.
+  // Without caching, every navigation re-fetches all XML template files.
   const components = typeof COMPONENTS !== 'undefined' ? COMPONENTS : []
-  const templates = await mergeTemplates(components)
+  if (!_cachedTemplates) {
+    _cachedTemplates = await mergeTemplates(components)
+  }
+  const templates = _cachedTemplates
   const mountElement = document.getElementById('metaowl')
+
+  // Destroy the previous OWL App before mounting a new one.
+  // Without this, every navigation leaves a zombie app running in the background
+  // (scheduler, reactive effects, event listeners) that accumulates and causes freezes.
+  if (_currentApp) {
+    try { _currentApp.destroy() } catch (_) {}
+    _currentApp = null
+  }
   mountElement.innerHTML = ''
 
   const pageComponent = route[0].component
@@ -51,11 +79,26 @@ export async function mountApp(route) {
   const layoutName = resolveLayout(pageComponent, pagePath)
   const LayoutClass = getLayout(layoutName)
 
+  // Base mount configuration with built-in components
+  const baseConfig = {
+    ..._config,
+    templates,
+    components: {
+      Link,
+      't-link': Link
+    }
+  }
+
+  let instance
   if (LayoutClass) {
     // Mount with layout
-    await mountWithLayout(pageComponent, mountElement, { routePath: pagePath, templates })
+    instance = await mountWithLayout(pageComponent, mountElement, { routePath: pagePath, ...baseConfig })
   } else {
     // Mount without layout
-    await mount(pageComponent, mountElement, { ..._config, templates })
+    instance = await mount(pageComponent, mountElement, baseConfig)
   }
+
+  // Store OWL App reference so we can destroy it before the next navigation.
+  // instance.__owl__.app is the underlying App object that owns the scheduler.
+  _currentApp = instance?.__owl__?.app ?? null
 }

package/modules/auto-import.js

@@ -23,7 +23,7 @@
  */
 
 import { globSync } from 'glob'
-import { resolve, relative, basename, extname, dirname } from 'path'
+import { resolve, relative, basename, extname, dirname } from 'node:path'
 
 /**
  * Registry of auto-discovered components.

package/modules/link.js

@@ -0,0 +1,255 @@
+/**
+ * @module Link
+ *
+ * SPA Link component for metaowl with automatic external link detection.
+ *
+ * This component renders a link that navigates via history.pushState
+ * for internal targets (without page reload) and navigates normally
+ * for external targets.
+ *
+ * Features:
+ * - Automatic detection of external links (http://, https://, //, mailto:, tel:, etc.)
+ * - SPA navigation for internal links (no page reload)
+ * - Support for active link styling
+ * - Respects modifier keys (Ctrl, Meta, Alt) for normal browser navigation
+ * - Accessible links with correct href attributes
+ *
+ * @example
+ * // Internal link
+ * <t-link to="/about">About Us</t-link>
+ *
+ * // With CSS classes
+ * <t-link to="/user/profile" class="btn btn-primary">Profile</t-link>
+ *
+ * // Active link styling
+ * <t-link to="/about" activeClass="active">About Us</t-link>
+ *
+ * // External link (automatically detected)
+ * <t-link to="https://example.com">External</t-link>
+ */
+
+import { Component, useState, onMounted, onWillUnmount } from '@odoo/owl'
+
+/**
+ * Regex for detecting external URLs.
+ * Matches: http://, https://, // (protocol-relative), mailto:, tel:, ftp:, etc.
+ * @type {RegExp}
+ */
+const EXTERNAL_URL_REGEX = /^(https?:|\/\/|mailto:|tel:|ftp:|file:|javascript:)/i
+
+/**
+ * Checks if a URL is external.
+ *
+ * @param {string} url - The URL to check
+ * @returns {boolean} True if external
+ */
+function isExternalUrl(url) {
+  if (!url || typeof url !== 'string') return false
+  return EXTERNAL_URL_REGEX.test(url)
+}
+
+/**
+ * Checks if a link is considered "active" (for styling).
+ *
+ * @param {string} linkPath - The link path
+ * @param {string} currentPath - The current path
+ * @returns {boolean} True if active
+ */
+function isActiveLink(linkPath, currentPath) {
+  if (!linkPath || !currentPath) return false
+  // Exact match or subpath
+  const normalizedLink = linkPath.replace(/\/$/, '') || '/'
+  const normalizedCurrent = currentPath.replace(/\/$/, '') || '/'
+  return normalizedCurrent === normalizedLink ||
+    (normalizedLink !== '/' && normalizedCurrent.startsWith(normalizedLink + '/'))
+}
+
+/**
+ * Link component for SPA navigation.
+ *
+ * Renders an <a> element that performs internal navigation
+ * without page reload.
+ */
+export class Link extends Component {
+  static template = 'Link'
+  static props = {
+    to: { type: String, optional: false },
+    class: { type: String, optional: true },
+    activeClass: { type: String, optional: true },
+    target: { type: String, optional: true },
+    rel: { type: String, optional: true },
+    title: { type: String, optional: true },
+    download: { type: [String, Boolean], optional: true },
+    hreflang: { type: String, optional: true },
+    type: { type: String, optional: true },
+    ping: { type: String, optional: true },
+    referrerpolicy: { type: String, optional: true },
+    media: { type: String, optional: true },
+    '*': true,
+  }
+
+  setup() {
+    this.state = useState({
+      isActive: false
+    })
+
+    // Reference to navigation function (injected from outside)
+    this._navigate = null
+
+    onMounted(() => {
+      this._updateActiveState()
+      // Listen to PopState events for updating active status
+      window.addEventListener('popstate', this._updateActiveState)
+    })
+
+    onWillUnmount(() => {
+      window.removeEventListener('popstate', this._updateActiveState)
+    })
+
+    this._updateActiveState = () => {
+      if (this.props.activeClass) {
+        this.state.isActive = isActiveLink(this.props.to, document.location.pathname)
+      }
+    }
+  }
+
+  /**
+   * Getter for combined CSS classes.
+   * @returns {string}
+   */
+  get linkClasses() {
+    const classes = []
+    if (this.props.class) {
+      classes.push(this.props.class)
+    }
+    if (this.state.isActive && this.props.activeClass) {
+      classes.push(this.props.activeClass)
+    }
+    return classes.join(' ')
+  }
+
+  /**
+   * Getter for the rel attribute.
+   * Automatically adds noopener noreferrer for external links with target="_blank".
+   * @returns {string|undefined}
+   */
+  get linkRel() {
+    if (this.props.rel) return this.props.rel
+    if (isExternalUrl(this.props.to) && this.props.target === '_blank') {
+      return 'noopener noreferrer'
+    }
+    return undefined
+  }
+
+  /**
+   * Forward unknown component props as native <a> attributes.
+   * This allows id/style/aria-* / data-* and similar anchor attributes.
+   * @returns {Record<string, any>}
+   */
+  get forwardedAttrs() {
+    const attrs = { ...this.props }
+    delete attrs.to
+    delete attrs.class
+    delete attrs.activeClass
+    delete attrs.target
+    delete attrs.rel
+    delete attrs.title
+    delete attrs.download
+    return attrs
+  }
+
+  /**
+   * Handler for click events.
+   * Checks if SPA navigation is possible or normal navigation should be used.
+   *
+   * @param {MouseEvent} ev - The click event
+   */
+  onClick(ev) {
+    const url = this.props.to
+
+    // External URLs: Normal navigation
+    if (isExternalUrl(url)) {
+      return // Let browser handle normal navigation
+    }
+
+    // Modifier keys: Normal navigation (new tab, download, etc.)
+    if (ev.ctrlKey || ev.metaKey || ev.altKey || ev.shiftKey) {
+      return
+    }
+
+    // Right click: Context menu
+    if (ev.button !== 0) {
+      return
+    }
+
+    // Download link: Normal navigation
+    if (this.props.download) {
+      return
+    }
+
+    // Internal SPA navigation
+    ev.preventDefault()
+
+    // Update URL immediately so components reading window.location.pathname
+    // (e.g. isActive in sidebar) already see the correct path when the new
+    // app mounts. The generation counter in _spaNavigate guarantees that only
+    // the last-triggered navigation actually calls mountApp.
+    window.history.pushState({ path: url }, '', url)
+
+    if (typeof window.__metaowlNavigate === 'function') {
+      window.__metaowlNavigate(url)
+    } else {
+      // Fallback: normal navigation (URL already updated above)
+      window.location.href = url
+    }
+  }
+}
+
+/**
+ * Template for the Link component.
+ * Must be registered in the app's templates file or loaded dynamically.
+ */
+export const LinkTemplate = /* xml */ `
+<templates>
+  <t t-name="Link">
+    <a
+      t-att="forwardedAttrs"
+      t-att-href="props.to"
+      t-att-class="linkClasses"
+      t-att-target="props.target"
+      t-att-rel="linkRel"
+      t-att-title="props.title"
+      t-att-download="props.download"
+      t-on-click="onClick"
+    >
+      <t t-slot="default"/>
+    </a>
+  </t>
+</templates>
+`
+
+/**
+ * Helper function to register the Link template.
+ * Called automatically on app startup.
+ *
+ * @param {object} templates - The app's templates object
+ * @returns {string|void} Modified templates if string was passed
+ */
+export function registerLinkTemplate(templates) {
+  if (typeof templates === 'string') {
+    // If templates is a string, add the Link template
+    // Remove outer <templates> tags from LinkTemplate
+    const linkContent = LinkTemplate
+      .replace('<templates>', '')
+      .replace('</templates>', '')
+      .trim()
+    // Insert before closing </templates> tag
+    return templates.replace('</templates>', linkContent + '\n</templates>')
+  }
+  // If templates is an object, register the template
+  if (templates && typeof templates === 'object') {
+    templates.Link = LinkTemplate
+  }
+}
+
+export default Link

package/modules/router.js

@@ -173,7 +173,7 @@ class Router {
     let pattern = routePath
       // Escape forward slashes
       .replace(/\//g, '\\/')
-      // Replace catch-all :name(.*) params — must come before required-param replacement
+      // Replace catch-all :name(.*) params - must come before required-param replacement
       .replace(/:([^/(]+)\(\.\*\)/g, '(.*)')
       // Replace optional params /:name?
       .replace(/\/:([^/(]+)\?/g, '(?:/([^/]+))?')
@@ -273,16 +273,28 @@ class Router {
  * @returns {Promise<object[]>} Resolved route or throws error
  * @throws {NavigationError} If navigation is aborted
  */
+// Tracks which routes arrays have already been augmented with SSG path variants.
+// Using a WeakSet means each distinct array is injected exactly once, even
+// across multiple processRoutes calls with the same array.
+const _injectedRouteSets = new WeakSet()
+
 export async function processRoutes(routes, customPath) {
   // Use custom path for testing if provided
   const targetPath = customPath || document.location.pathname
 
-  // Inject SSG-compatible path variants
-  for (const route of routes) {
-    const originalPaths = [...route.path]
-    for (const path of originalPaths) {
-      if (typeof path === 'string') {
-        injectSystemRoutes(route, path)
+  // Inject SSG-compatible path variants ONCE per routes array.
+  // injectSystemRoutes mutates route.path in-place. Calling it on every
+  // navigation causes the arrays to grow on every call (each injected path
+  // becomes a base for further injections), making route matching
+  // exponentially slower with every navigation.
+  if (!_injectedRouteSets.has(routes)) {
+    _injectedRouteSets.add(routes)
+    for (const route of routes) {
+      const originalPaths = [...route.path]
+      for (const path of originalPaths) {
+        if (typeof path === 'string') {
+          injectSystemRoutes(route, path)
+        }
       }
     }
   }
@@ -559,6 +571,96 @@ export function cancelNavigation() {
   }
 }
 
+/**
+ * Callback for SPA navigation.
+ * Set when the app is initialized.
+ * @type {Function|null}
+ */
+let _spaNavigationCallback = null
+
+/**
+ * Sets the SPA navigation callback.
+ * Called internally by boot().
+ *
+ * @param {Function} callback - Function called during SPA navigation
+ * @internal
+ */
+export function _setSpaNavigationCallback(callback) {
+  _spaNavigationCallback = callback
+}
+
+/**
+ * Flag indicating if SPA navigation is enabled.
+ * @type {boolean}
+ */
+let _spaEnabled = false
+
+/**
+ * Enables or disables SPA navigation.
+ *
+ * @param {boolean} enabled - True to enable SPA navigation
+ */
+export function setSpaMode(enabled) {
+  _spaEnabled = enabled
+}
+
+/**
+ * Checks if SPA navigation is enabled.
+ *
+ * @returns {boolean}
+ */
+export function isSpaMode() {
+  return _spaEnabled
+}
+
+/**
+ * Navigate to a path with SPA navigation (no page reload).
+ * Updates URL via history.pushState and renders the new route.
+ *
+ * @param {string} path - Target path (e.g., "/about")
+ * @param {object} [options] - Navigation options
+ * @param {boolean} [options.replace=false] - Replace current history entry instead of creating new one
+ * @returns {Promise<boolean>} True if navigation successful
+ *
+ * @example
+ * // Normal navigation
+ * await navigateTo('/about')
+ *
+ * // Replace current entry (no back possible)
+ * await navigateTo('/login', { replace: true })
+ */
+export async function navigateTo(path, options = {}) {
+  const { replace = false } = options
+
+  if (!_spaEnabled || !_spaNavigationCallback) {
+    // Fallback: Normal browser navigation
+    if (replace) {
+      window.location.replace(path)
+    } else {
+      window.location.href = path
+    }
+    return false
+  }
+
+  try {
+    // Update URL without page reload
+    if (replace) {
+      window.history.replaceState({ path }, '', path)
+    } else {
+      window.history.pushState({ path }, '', path)
+    }
+
+    // Perform SPA navigation
+    await _spaNavigationCallback(path)
+    return true
+  } catch (error) {
+    console.error('[metaowl] SPA navigation failed:', error)
+    // Fallback to normal navigation on error
+    window.location.href = path
+    return false
+  }
+}
+
 /**
  * Programmatically navigate to a path.
  *
@@ -566,14 +668,21 @@ export function cancelNavigation() {
  * @param {object} [options] - Navigation options
  * @param {boolean} [options.replace=false] - Replace current history entry
  * @param {boolean} [options.reload=true] - Reload the page
+ * @deprecated Use navigateTo() for SPA navigation
  */
 export function navigate(path, options = {}) {
   const { replace = false, reload = true } = options
 
-  if (replace) {
-    window.location.replace(path)
+  if (reload || !_spaEnabled) {
+    // Traditional navigation with page reload
+    if (replace) {
+      window.location.replace(path)
+    } else {
+      window.location.href = path
+    }
   } else {
-    window.location.href = path
+    // SPA navigation
+    navigateTo(path, { replace })
   }
 }
 
@@ -583,7 +692,7 @@ export function navigate(path, options = {}) {
  * @param {string} path - Target path
  */
 export function push(path) {
-  navigate(path, { replace: false })
+  navigateTo(path, { replace: false })
 }
 
 /**
@@ -592,7 +701,7 @@ export function push(path) {
  * @param {string} path - Target path
  */
 export function replace(path) {
-  navigate(path, { replace: true })
+  navigateTo(path, { replace: true })
 }
 
 /**
@@ -633,7 +742,10 @@ export const router = {
   back,
   forward,
   go,
-  navigate
+  navigate,
+  navigateTo,
+  setSpaMode,
+  isSpaMode
 }
 
 /**

package/modules/templates-manager.js

@@ -5,6 +5,36 @@
  */
 import { loadFile } from '@odoo/owl'
 
+/**
+ * Link component template.
+ * Automatically added to all templates.
+ * @type {string}
+ */
+const LINK_COMPONENT_TEMPLATE = /* xml */ `
+  <t t-name="Link">
+    <a
+      t-att="forwardedAttrs"
+      t-att-href="props.to"
+      t-att-class="linkClasses"
+      t-att-target="props.target"
+      t-att-rel="linkRel"
+      t-att-title="props.title"
+      t-att-download="props.download"
+      t-on-click="onClick"
+    >
+      <t t-slot="default"/>
+    </a>
+  </t>
+`
+
+/**
+ * Internal templates that are automatically added.
+ * @type {string[]}
+ */
+const INTERNAL_TEMPLATES = [
+  LINK_COMPONENT_TEMPLATE
+]
+
 /**
  * Loads OWL XML template(s) into a string ready to be passed to OWL's mount() options.
  *
@@ -22,15 +52,15 @@ export async function mergeTemplates(files) {
   if (fileArray.length === 1) {
     try {
       const content = await loadFile(fileArray[0])
-      // If already wrapped (merged templates.xml), return as-is
+      // If already wrapped (merged templates.xml), return as-is with internal templates
       if (content.trim().startsWith('<templates>')) {
-        return content
+        return content.replace('</templates>', INTERNAL_TEMPLATES.join('') + '</templates>')
       }
-      // Otherwise wrap it
-      return '<templates>' + content + '</templates>'
+      // Otherwise wrap it with internal templates
+      return '<templates>' + content + INTERNAL_TEMPLATES.join('') + '</templates>'
     } catch (e) {
       console.error(`[metaowl] Failed to load template: ${fileArray[0]}`, e)
-      return '<templates></templates>'
+      return '<templates>' + INTERNAL_TEMPLATES.join('') + '</templates>'
     }
   }
 
@@ -45,5 +75,15 @@ export async function mergeTemplates(files) {
       }
     })
   )
-  return '<templates>' + results.join('') + '</templates>'
+  return '<templates>' + results.join('') + INTERNAL_TEMPLATES.join('') + '</templates>'
+}
+
+/**
+ * Gibt die internen Templates zurück.
+ * Nützlich für Testing oder manuelle Template-Registrierung.
+ *
+ * @returns {string[]}
+ */
+export function getInternalTemplates() {
+  return [...INTERNAL_TEMPLATES]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metaowl",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Lightweight meta-framework for Odoo OWL — file-based routing, app mounting, Fetch helper, Cache, Meta tags, SSG generator, and a Vite plugin.",
   "type": "module",
   "main": "index.js",

package/test/link.test.js

@@ -0,0 +1,189 @@
+/**
+ * @module Link Tests
+ *
+ * Tests for the Link component and SPA navigation.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { Link, registerLinkTemplate } from '../modules/link.js'
+import {
+  navigateTo,
+  setSpaMode,
+  isSpaMode,
+  _setSpaNavigationCallback,
+  resetRouter
+} from '../modules/router.js'
+
+// Mock für window
+const mockPushState = vi.fn()
+const mockReplaceState = vi.fn()
+const mockHistoryBack = vi.fn()
+const mockHistoryForward = vi.fn()
+const mockHistoryGo = vi.fn()
+const mockAddEventListener = vi.fn()
+const mockRemoveEventListener = vi.fn()
+
+// Setup global mocks
+beforeEach(() => {
+  vi.resetAllMocks()
+  resetRouter()
+
+  // Mock window.location
+  Object.defineProperty(globalThis, 'window', {
+    value: {
+      location: {
+        pathname: '/',
+        href: 'http://localhost/',
+        replace: vi.fn()
+      },
+      history: {
+        pushState: mockPushState,
+        replaceState: mockReplaceState,
+        back: mockHistoryBack,
+        forward: mockHistoryForward,
+        go: mockHistoryGo
+      },
+      addEventListener: mockAddEventListener,
+      removeEventListener: mockRemoveEventListener
+    },
+    writable: true,
+    configurable: true
+  })
+
+  // Mock document.location
+  Object.defineProperty(globalThis, 'document', {
+    value: {
+      location: {
+        pathname: '/'
+      }
+    },
+    writable: true,
+    configurable: true
+  })
+})
+
+describe('Link Component', () => {
+  describe('isExternalUrl', () => {
+    it('should return false for internal paths', () => {
+      const internalPaths = ['/', '/about', '/user/123', '/blog/post-slug']
+
+      for (const path of internalPaths) {
+        // Test durch Instanziierung der Komponente und Prüfung des Verhaltens
+        const link = new Link()
+        expect(link).toBeDefined()
+      }
+    })
+
+    it('should return true for external URLs', () => {
+      const externalUrls = [
+        'http://example.com',
+        'https://example.com',
+        '//example.com',
+        'mailto:test@example.com',
+        'tel:+1234567890',
+        'ftp://ftp.example.com',
+        'javascript:void(0)'
+      ]
+
+      for (const url of externalUrls) {
+        const link = new Link()
+        expect(link).toBeDefined()
+      }
+    })
+  })
+
+  describe('Link props', () => {
+    it('should accept required "to" prop', () => {
+      const link = new Link()
+      expect(Link.props.to.optional).toBe(false)
+      expect(Link.props.to.type).toBe(String)
+    })
+
+    it('should accept optional props', () => {
+      expect(Link.props.class.optional).toBe(true)
+      expect(Link.props.activeClass.optional).toBe(true)
+      expect(Link.props.target.optional).toBe(true)
+      expect(Link.props.rel.optional).toBe(true)
+      expect(Link.props.title.optional).toBe(true)
+      expect(Link.props.download.optional).toBe(true)
+    })
+
+    it('should have correct static template', () => {
+      expect(Link.template).toBe('Link')
+    })
+  })
+
+  describe('registerLinkTemplate', () => {
+    it('should add Link template to string templates', () => {
+      const templates = '<templates><t t-name="Test"></t></templates>'
+      const result = registerLinkTemplate(templates)
+
+      expect(result).toContain('t-name="Link"')
+      expect(result).toContain('<a')
+      expect(result).toContain('</templates>')
+    })
+
+    it('should add Link template to object templates', () => {
+      const templates = { Test: '<t t-name="Test"></t>' }
+      registerLinkTemplate(templates)
+
+      expect(templates.Link).toBeDefined()
+      expect(templates.Link).toContain('t-name="Link"')
+    })
+  })
+})
+
+describe('SPA Navigation', () => {
+  describe('navigateTo', () => {
+    it('should use window.location when SPA mode is disabled', async () => {
+      setSpaMode(false)
+      const locationHrefSpy = vi.spyOn(window.location, 'href', 'set')
+
+      await navigateTo('/about')
+
+      expect(locationHrefSpy).toHaveBeenCalledWith('/about')
+    })
+
+    it('should use history.pushState when SPA mode is enabled', async () => {
+      setSpaMode(true)
+      const mockCallback = vi.fn().mockResolvedValue(undefined)
+      _setSpaNavigationCallback(mockCallback)
+
+      await navigateTo('/about')
+
+      expect(mockPushState).toHaveBeenCalledWith({ path: '/about' }, '', '/about')
+      expect(mockCallback).toHaveBeenCalledWith('/about')
+    })
+
+    it('should use history.replaceState when replace option is true', async () => {
+      setSpaMode(true)
+      const mockCallback = vi.fn().mockResolvedValue(undefined)
+      _setSpaNavigationCallback(mockCallback)
+
+      await navigateTo('/about', { replace: true })
+
+      expect(mockReplaceState).toHaveBeenCalledWith({ path: '/about' }, '', '/about')
+    })
+
+    it('should fallback to window.location on navigation error', async () => {
+      setSpaMode(true)
+      const mockCallback = vi.fn().mockRejectedValue(new Error('Navigation failed'))
+      _setSpaNavigationCallback(mockCallback)
+
+      const locationHrefSpy = vi.spyOn(window.location, 'href', 'set')
+
+      await navigateTo('/about')
+
+      expect(locationHrefSpy).toHaveBeenCalledWith('/about')
+    })
+  })
+
+  describe('setSpaMode / isSpaMode', () => {
+    it('should enable and disable SPA mode', () => {
+      setSpaMode(true)
+      expect(isSpaMode()).toBe(true)
+
+      setSpaMode(false)
+      expect(isSpaMode()).toBe(false)
+    })
+  })
+})

package/test/templates-manager.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { mergeTemplates } from '../modules/templates-manager.js'
+import { mergeTemplates, getInternalTemplates } from '../modules/templates-manager.js'
 
 vi.mock('@odoo/owl', () => ({
   loadFile: vi.fn(),
@@ -15,7 +15,10 @@ describe('mergeTemplates', () => {
   it('returns wrapped templates string from a single file', async () => {
     loadFile.mockResolvedValue('<t t-name="Comp"><div/></t>')
     const result = await mergeTemplates(['/components/Comp.xml'])
-    expect(result).toBe('<templates><t t-name="Comp"><div/></t></templates>')
+    expect(result).toContain('<templates>')
+    expect(result).toContain('<t t-name="Comp"><div/></t>')
+    expect(result).toContain('</templates>')
+    expect(result).toContain('t-name="Link"') // Internal Link template
   })
 
   it('concatenates multiple template files', async () => {
@@ -23,19 +26,27 @@ describe('mergeTemplates', () => {
       .mockResolvedValueOnce('<t t-name="A"><div/></t>')
       .mockResolvedValueOnce('<t t-name="B"><span/></t>')
     const result = await mergeTemplates(['/A.xml', '/B.xml'])
-    expect(result).toBe('<templates><t t-name="A"><div/></t><t t-name="B"><span/></t></templates>')
+    expect(result).toContain('<templates>')
+    expect(result).toContain('<t t-name="A"><div/></t>')
+    expect(result).toContain('<t t-name="B"><span/></t>')
+    expect(result).toContain('</templates>')
+    expect(result).toContain('t-name="Link"') // Internal Link template
   })
 
-  it('returns empty templates tag for empty array', async () => {
+  it('returns templates with internal components for empty array', async () => {
     const result = await mergeTemplates([])
-    expect(result).toBe('<templates></templates>')
+    expect(result).toContain('<templates>')
+    expect(result).toContain('</templates>')
+    expect(result).toContain('t-name="Link"') // Internal Link template
   })
 
   it('skips failed files and logs error', async () => {
     const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
     loadFile.mockRejectedValue(new Error('404'))
     const result = await mergeTemplates(['/missing.xml'])
-    expect(result).toBe('<templates></templates>')
+    expect(result).toContain('<templates>')
+    expect(result).toContain('</templates>')
+    expect(result).toContain('t-name="Link"') // Internal Link template despite error
     expect(consoleSpy).toHaveBeenCalledWith(
       expect.stringContaining('[metaowl] Failed to load template: /missing.xml'),
       expect.any(Error)
@@ -50,10 +61,20 @@ describe('mergeTemplates', () => {
       .mockRejectedValueOnce(new Error('404'))
       .mockResolvedValueOnce('<t t-name="Also"><span/></t>')
     const result = await mergeTemplates(['/good.xml', '/missing.xml', '/also.xml'])
-    expect(result).toBe('<templates><t t-name="Good"><div/></t><t t-name="Also"><span/></t></templates>')
+    expect(result).toContain('<t t-name="Good"><div/></t>')
+    expect(result).toContain('<t t-name="Also"><span/></t>')
+    expect(result).toContain('t-name="Link"') // Internal Link template
     consoleSpy.mockRestore()
   })
 
+  it('includes internal Link component template', async () => {
+    const templates = getInternalTemplates()
+    expect(templates.length).toBeGreaterThan(0)
+    expect(templates[0]).toContain('t-name="Link"')
+    expect(templates[0]).toContain('<a')
+    expect(templates[0]).toContain('t-att-href')
+  })
+
   it('calls loadFile once per path', async () => {
     loadFile.mockResolvedValue('<t/>')
     await mergeTemplates(['/a.xml', '/b.xml', '/c.xml'])