safa-router 1.1.2 → 1.2.0

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "safa-router",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "A professional standalone frontend router inspired by Next.js App Router — works with any framework or vanilla JS",
   "type": "module",
   "main": "src/index.js",
+  "types": "safa-router.d.ts",
   "exports": {
-    ".": "./src/index.js",
+    ".": {
+      "import": "./src/index.js",
+      "types": "./safa-router.d.ts"
+    },
     "./*": "./src/*.js"
   },
   "files": [
-    "src/"
+    "src/",
+    "safa-router.d.ts"
   ],
   "scripts": {
     "start": "npx serve test-app -l 3000",
-    "test": "echo \"Tests coming soon\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "echo \"Add lint tool\"",
     "prepublishOnly": "npm test"
   },
@@ -39,5 +46,8 @@
   "bugs": {
     "url": "https://github.com/Karan-Safaie-Qadi/SafaRouter/issues"
   },
-  "homepage": "https://github.com/Karan-Safaie-Qadi/SafaRouter#readme"
+  "homepage": "https://github.com/Karan-Safaie-Qadi/SafaRouter#readme",
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  }
 }

package/safa-router.d.ts

@@ -0,0 +1,350 @@
+declare module 'safa-router' {
+  // ─── Core ─────────────────────────────────────────
+  export class SafaRouter {
+    static version: string
+    static VERSION: string
+
+    constructor(options?: SafaRouterOptions)
+    start(target?: string | Element): Promise<this>
+    isStarted(): boolean
+    destroy(): void
+
+    push(url: string, state?: Record<string, any>): Promise<void>
+    replace(url: string, state?: Record<string, any>): Promise<void>
+    pushRoute(routeName: string, params?: Record<string, any>, query?: Record<string, any>): Promise<void>
+    back(): void
+    forward(): void
+    reload(): void
+    navigate(url: string): Promise<void>
+
+    getConfig(): SafaRouterOptions
+    readonly pathname: string
+    readonly params: Record<string, any>
+    readonly query: Record<string, any>
+    readonly loading: boolean
+    readonly currentRoute: RouteMatch | null
+
+    on(event: string, fn: (data: any) => void): () => void
+    off(event: string, fn: (data: any) => void): void
+    use(fn: MiddlewareFn): this
+    useNamed(name: string, fn: MiddlewareFn, priority?: number): this
+    beforeEach(fn: MiddlewareFn): this
+    afterEach(fn: (data: { pathname: string }) => void): () => void
+    middleware(name: string): this
+    insertMiddlewareBefore(refName: string, fn: MiddlewareFn, priority?: number): this
+    insertMiddlewareAfter(refName: string, fn: MiddlewareFn, priority?: number): this
+
+    onError(fn: (data: { path: string; error: Error }) => void): () => void
+    onNotFound(fn: (data: { path: string }) => void): () => void
+    onRouteChange(fn: (data: { pathname: string; params: any; query: any }) => void): () => void
+    onBeforeNavigate(fn: (data: { path: string; method: string }) => void): () => void
+
+    createLink(config: LinkConfig): Link
+    prefetch(path: string): Promise<void>
+    clearCache(): void
+    getRoute(path: string): RouteMatch | null
+
+    plugin(plugin: SafaPlugin): this
+    ejectPlugin(name: string): boolean
+    getPlugin(name: string): any
+    readonly plugins: string[]
+  }
+
+  export interface SafaRouterOptions {
+    target?: string | Element
+    pageDir?: string
+    pagesDir?: string
+    layout?: LayoutComponent | string
+    routes?: RouteDefinition
+    notFound?: PageComponent | string
+    error?: PageComponent | string
+    basePath?: string
+    useHash?: boolean
+    scrollToTop?: boolean
+    prefetch?: boolean
+    cacheRoutes?: boolean
+    titleTemplate?: string
+    transitionDuration?: number
+    transitionEnterClass?: string
+    transitionExitClass?: string
+    transitionEnterActiveClass?: string
+    transitionExitActiveClass?: string
+    scrollRestoration?: 'auto' | 'manual'
+    plugins?: SafaPlugin[]
+  }
+
+  // ─── Route Tree ───────────────────────────────────
+  export interface RouteDefinition {
+    [key: string]: RouteEntry
+  }
+
+  export interface RouteEntry {
+    page?: PageComponent | string
+    layout?: LayoutComponent | string
+    loading?: PageComponent | string
+    error?: PageComponent | string
+    notFound?: PageComponent | string
+    children?: RouteDefinition
+    meta?: { title?: string; name?: string; [key: string]: any }
+  }
+
+  export interface RouteMatch {
+    node: RouteNodeData
+    params: Record<string, any>
+    layouts: LayoutComponent[]
+  }
+
+  export interface RouteNodeData {
+    page?: PageComponent | string
+    layout?: LayoutComponent | string
+    loading?: PageComponent | string
+    error?: PageComponent | string
+    notFound?: PageComponent | string
+    meta?: Record<string, any>
+    segment?: string
+    fullPath?: string
+  }
+
+  // ─── Components ───────────────────────────────────
+  export interface PageContext {
+    params: Record<string, any>
+    query: Record<string, any>
+    router: SafaRouter
+  }
+
+  export interface LayoutContext extends PageContext {
+    children: string
+  }
+
+  export type PageComponent = (ctx: PageContext) => string | Promise<string>
+  export type LayoutComponent = (ctx: LayoutContext) => string | Promise<string>
+
+  // ─── Middleware ────────────────────────────────────
+  export interface MiddlewareContext {
+    path: string
+    method: string
+    query: Record<string, any>
+    cancelled: boolean
+    redirect: string | null
+    [key: string]: any
+  }
+
+  export type MiddlewareFn = (ctx: MiddlewareContext, next: () => Promise<any>) => any
+
+  export class MiddlewareChain {
+    constructor()
+    use(fn: MiddlewareFn, priority?: number): this
+    useNamed(name: string, fn: MiddlewareFn, priority?: number): this
+    run(ctx: MiddlewareContext): Promise<any>
+    clear(): this
+    remove(fn: MiddlewareFn | string): this
+    insertBefore(refName: string, fn: MiddlewareFn, priority?: number): this
+    insertAfter(refName: string, fn: MiddlewareFn, priority?: number): this
+    clone(): MiddlewareChain
+    readonly length: number
+    readonly stack: { name: string; priority: number }[]
+  }
+
+  // ─── History ───────────────────────────────────────
+  export class HistoryManager {
+    constructor(opts?: { useHash?: boolean; basePath?: string })
+    init(): void
+    destroy(): void
+    isSupported(): boolean
+    readonly path: string
+    push(url: string, state?: Record<string, any>): void
+    replace(url: string, state?: Record<string, any>): void
+    back(): void
+    forward(): void
+    go(delta: number): void
+    readonly length: number
+    readonly state: any
+    clearState(): void
+    onChange(fn: (data: { path: string; action: string; state: any }) => void): () => void
+  }
+
+  // ─── Link ──────────────────────────────────────────
+  export interface LinkConfig {
+    href?: string
+    children?: string | Node | Node[]
+    className?: string
+    activeClass?: string
+    router?: SafaRouter
+    attrs?: Record<string, string>
+  }
+
+  export class Link {
+    constructor(config?: LinkConfig)
+    readonly href: string
+    readonly element: HTMLAnchorElement | null
+    render(container?: string | Node): HTMLAnchorElement
+    setHref(href: string): void
+    destroy(): void
+  }
+
+  // ─── Route Tree Core ───────────────────────────────
+  export class RouteTree {
+    constructor(routes: RouteDefinition)
+    static create(routes: RouteDefinition): RouteTree
+    resolve(pathname: string): RouteMatch | null
+    flatten(): { path: string; page: any; meta: any }[]
+    find(pathname: string): RouteMatch | null
+    getRoute(pathname: string): RouteMatch | null
+  }
+
+  // ─── Route Matcher ─────────────────────────────────
+  export class RouteMatcher {
+    constructor()
+    static create(patterns: string[]): RouteMatcher
+    add(pattern: string): this
+    addMultiple(patterns: string[]): this
+    match(url: string): { pattern: string; path: string; params: Record<string, any> } | null
+    build(pattern: string, params: Record<string, any>): string
+    clear(): this
+    readonly patterns: string[]
+  }
+
+  // ─── Plugin System ────────────────────────────────
+  export interface SafaPlugin {
+    name: string
+    version?: string
+    install?: (router: SafaRouter) => void | (() => void) | Promise<void | (() => void)>
+    middleware?: MiddlewareFn
+    onBeforeNavigate?: (data: { path: string; method: string }) => void
+    onAfterNavigate?: (data: { pathname: string }) => void
+    onRouteChange?: (data: { pathname: string; params: any; query: any }) => void
+    onError?: (data: { path: string; error: Error }) => void
+  }
+
+  export class PluginManager {
+    constructor(router: SafaRouter)
+    use(plugin: SafaPlugin): this
+    eject(name: string): boolean
+    get(name: string): SafaPlugin | null
+    list(): string[]
+    has(name: string): boolean
+    ejectAll(): void
+    readonly count: number
+  }
+
+  // ─── Transitions ──────────────────────────────────
+  export interface TransitionsConfig {
+    transitionDuration?: number
+    transitionEnterClass?: string
+    transitionExitClass?: string
+    transitionEnterActiveClass?: string
+    transitionExitActiveClass?: string
+  }
+
+  export class TransitionsManager {
+    constructor(config?: TransitionsConfig)
+    run(el: Element, renderFn: () => Promise<void> | void): Promise<void>
+    cancelExit(el: Element): void
+    cancelEnter(el: Element): void
+    setDuration(ms: number): void
+    readonly config: TransitionsConfig
+  }
+
+  // ─── Scroll ────────────────────────────────────────
+  export class ScrollManager {
+    constructor()
+    save(pathname: string): void
+    restore(pathname: string, scrollToTop?: boolean): void
+    trackScrollElement(el: HTMLElement): void
+    untrackScrollElement(el: HTMLElement): void
+    restoreElementScroll(pathname: string, container: HTMLElement): void
+    clear(): void
+    has(pathname: string): boolean
+    readonly size: number
+  }
+
+  // ─── SSR ───────────────────────────────────────────
+  export function matchRoute(path: string, routes?: RouteDefinition): {
+    path: string
+    params: Record<string, any>
+    query: Record<string, any>
+    node: RouteNodeData
+    layouts: LayoutComponent[]
+  } | null
+
+  export function matchPattern(path: string, patterns?: string[]): {
+    pattern: string
+    path: string
+    params: Record<string, any>
+  } | null
+
+  export function renderRoute(path: string, routes?: RouteDefinition, context?: { router?: SafaRouter }): Promise<string | null>
+
+  export function routeExists(path: string, routes?: RouteDefinition): boolean
+
+  export function listRoutes(routes?: RouteDefinition): { path: string; page: any; meta: any }[]
+
+  // ─── Utils ─────────────────────────────────────────
+  export function normalizePath(path: string): string
+  export function parseQuery(search: string): Record<string, string>
+  export function joinPaths(...parts: string[]): string
+  export function createURL(path: string, base?: string): URL | null
+  export function isExternalURL(url: string): boolean
+  export function isSamePath(a: string, b: string): boolean
+  export function isDynamicSegment(segment: string): boolean
+  export function isCatchAllSegment(segment: string): boolean
+  export function isOptionalCatchAll(segment: string): boolean
+  export function isRouteGroupSegment(segment: string): boolean
+  export function extractParamName(segment: string): string | null
+  export function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): T
+  export function useRouter(router: SafaRouter): {
+    readonly state: { pathname: string; params: any; query: any; loading: boolean }
+    subscribe(fn: (state: any) => void): () => void
+    push: SafaRouter['push']
+    replace: SafaRouter['replace']
+    back: SafaRouter['back']
+    forward: SafaRouter['forward']
+    navigate: SafaRouter['navigate']
+    unsubscribe: () => void
+  }
+
+  // ─── Helpers ────────────────────────────────────────
+  export function bindLinks(router: SafaRouter, scope?: Document | Element): void
+  export function prefetchOnHover(router: SafaRouter): void
+
+  // ─── Constants ──────────────────────────────────────
+  export const EVENTS: {
+    BEFORE_NAVIGATE: 'beforenavigate'
+    NAVIGATE: 'navigate'
+    ROUTE_CHANGE: 'routechange'
+    AFTER_NAVIGATE: 'afternavigate'
+    BEFORE_RENDER: 'beforerender'
+    AFTER_RENDER: 'afterrender'
+    ERROR: 'error'
+    NOT_FOUND: 'notfound'
+    LOADING: 'loading'
+    READY: 'ready'
+    DESTROY: 'destroy'
+    LINK_CLICK: 'linkclick'
+    PLUGIN_INSTALL: 'plugininstall'
+    PLUGIN_EJECT: 'plugineject'
+  }
+
+  export const DEFAULT_CONFIG: SafaRouterOptions
+
+  // ─── Errors ─────────────────────────────────────────
+  export class SafaError extends Error {
+    code: string
+    toJSON(): { name: string; message: string; code: string }
+  }
+
+  export class RouteNotFoundError extends SafaError {
+    pathname: string
+  }
+
+  export class NavigationError extends SafaError {
+    pathname: string
+  }
+
+  export class RouteLoadError extends SafaError {
+    pathname: string
+    original: Error
+  }
+
+  export class NavigationAbortError extends SafaError {}
+}

package/src/MiddlewareChain.js

@@ -3,14 +3,22 @@ export class MiddlewareChain {
     this._stack = []
   }
 
-  use(fn) {
+  use(fn, priority = 0) {
     if (typeof fn !== 'function') {
       throw new Error('Middleware must be a function')
     }
+    fn._priority = priority
+    fn._name = fn.name || ''
     this._stack.push(fn)
+    this._stack.sort((a, b) => (b._priority || 0) - (a._priority || 0))
     return this
   }
 
+  useNamed(name, fn, priority = 0) {
+    fn._name = name
+    return this.use(fn, priority)
+  }
+
   async run(ctx) {
     let i = 0
     const next = async () => {
@@ -31,17 +39,43 @@ export class MiddlewareChain {
   }
 
   remove(fn) {
-    this._stack = this._stack.filter(f => f !== fn)
+    if (typeof fn === 'string') {
+      this._stack = this._stack.filter(f => f._name !== fn)
+    } else {
+      this._stack = this._stack.filter(f => f !== fn)
+    }
+    return this
+  }
+
+  insertBefore(refName, fn, priority = 0) {
+    const idx = this._stack.findIndex(f => f._name === refName)
+    if (idx === -1) { this.use(fn, priority); return this }
+    fn._priority = priority
+    fn._name = fn.name || ''
+    this._stack.splice(idx, 0, fn)
+    return this
+  }
+
+  insertAfter(refName, fn, priority = 0) {
+    const idx = this._stack.findIndex(f => f._name === refName)
+    if (idx === -1) { this.use(fn, priority); return this }
+    fn._priority = priority
+    fn._name = fn.name || ''
+    this._stack.splice(idx + 1, 0, fn)
     return this
   }
 
   clone() {
     const chain = new MiddlewareChain()
-    chain._stack = [...this._stack]
+    chain._stack = this._stack.map(f => f)
     return chain
   }
 
   get length() {
     return this._stack.length
   }
+
+  get stack() {
+    return this._stack.map(f => ({ name: f._name, priority: f._priority || 0 }))
+  }
 }

package/src/PluginManager.js

@@ -0,0 +1,87 @@
+export class PluginManager {
+  constructor(router) {
+    this._router = router
+    this._plugins = new Map()
+  }
+
+  use(plugin) {
+    if (!plugin || typeof plugin !== 'object') {
+      throw new Error('Plugin must be an object with a name property')
+    }
+    if (!plugin.name) {
+      throw new Error('Plugin must have a name')
+    }
+    if (this._plugins.has(plugin.name)) {
+      console.warn(`[SafaRouter] Plugin "${plugin.name}" already registered, skipping`)
+      return this
+    }
+
+    const wrapped = { ...plugin, _cleanup: [] }
+
+    if (typeof plugin.install === 'function') {
+      const result = plugin.install(this._router)
+      if (result && typeof result.then === 'function') {
+        result.then(cleanup => {
+          if (typeof cleanup === 'function') wrapped._cleanup.push(cleanup)
+        })
+      } else if (typeof result === 'function') {
+        wrapped._cleanup.push(result)
+      }
+    }
+
+    if (typeof plugin.onBeforeNavigate === 'function') {
+      const unsub = this._router.onBeforeNavigate(plugin.onBeforeNavigate)
+      wrapped._cleanup.push(unsub)
+    }
+    if (typeof plugin.onAfterNavigate === 'function') {
+      const unsub = this._router.afterEach(plugin.onAfterNavigate)
+      wrapped._cleanup.push(unsub)
+    }
+    if (typeof plugin.onRouteChange === 'function') {
+      const unsub = this._router.onRouteChange(plugin.onRouteChange)
+      wrapped._cleanup.push(unsub)
+    }
+    if (typeof plugin.onError === 'function') {
+      const unsub = this._router.onError(plugin.onError)
+      wrapped._cleanup.push(unsub)
+    }
+    if (typeof plugin.middleware === 'function') {
+      this._router.use(plugin.middleware)
+    }
+
+    this._plugins.set(plugin.name, wrapped)
+    return this
+  }
+
+  eject(name) {
+    const plugin = this._plugins.get(name)
+    if (!plugin) return false
+    for (const cleanup of plugin._cleanup) {
+      try { cleanup() } catch {}
+    }
+    this._plugins.delete(name)
+    return true
+  }
+
+  get(name) {
+    return this._plugins.get(name) || null
+  }
+
+  list() {
+    return Array.from(this._plugins.keys())
+  }
+
+  has(name) {
+    return this._plugins.has(name)
+  }
+
+  ejectAll() {
+    for (const name of this._plugins.keys()) {
+      this.eject(name)
+    }
+  }
+
+  get count() {
+    return this._plugins.size
+  }
+}

package/src/RouteTree.js

@@ -80,8 +80,7 @@ export class RouteTree {
 
     for (const [key, val] of Object.entries(routes)) {
       const isGroup = isRouteGroup(key)
-      const fp = isGroup ? normalizePath(base) : normalizePath(`${base}/${key}`)
-      const isRoot = fp === '/' || key === '/'
+      const isRoot = key === '/' || key === ''
 
       if (isRoot) {
         if (typeof val === 'object' && val !== null) {
@@ -91,29 +90,45 @@ export class RouteTree {
           if (val.loading) parent.loading = val.loading
           if (val.error) parent.error = val.error
           if (val.notFound) parent.notFound = val.notFound
-          if (val.children) this._build(parent, val.children, fp)
+          if (val.children) this._build(parent, val.children, base)
         } else if (typeof val === 'function') {
           parent.page = val
         }
         continue
       }
 
-      const seg = isGroup ? key : key.replace(/^\//, '')
-      const node = new RouteNode({ segment: seg, fullPath: fp })
-
-      if (typeof val === 'object' && val !== null) {
-        if (val.meta) node.meta = val.meta
-        if (val.layout) node.layout = val.layout
-        if (val.page) node.page = val.page
-        if (val.loading) node.loading = val.loading
-        if (val.error) node.error = val.error
-        if (val.notFound) node.notFound = val.notFound
-        if (val.children) this._build(node, val.children, fp)
-      } else if (typeof val === 'function') {
-        node.page = val
-      }
+      const segs = (isGroup ? key : key.replace(/^\//, '')).split('/')
+      let cursor = parent
+      let currentBase = base
+
+      for (let si = 0; si < segs.length; si++) {
+        const seg = segs[si]
+        const isLast = si === segs.length - 1
+        const childBase = isGroup ? currentBase : normalizePath(`${currentBase}/${seg}`)
+
+        let child = cursor._findChild(seg)
+        if (!child) {
+          child = new RouteNode({ segment: seg, fullPath: childBase })
+          cursor.addChild(child)
+        }
 
-      parent.addChild(node)
+        if (isLast) {
+          if (typeof val === 'object' && val !== null) {
+            if (val.meta) child.meta = val.meta
+            if (val.layout) child.layout = val.layout
+            if (val.page) child.page = val.page
+            if (val.loading) child.loading = val.loading
+            if (val.error) child.error = val.error
+            if (val.notFound) child.notFound = val.notFound
+            if (val.children) this._build(child, val.children, childBase)
+          } else if (typeof val === 'function') {
+            child.page = val
+          }
+        }
+
+        cursor = child
+        currentBase = childBase
+      }
     }
   }
 

package/src/SafaRouter.js

@@ -2,13 +2,16 @@ import { RouteTree } from './RouteTree.js'
 import { HistoryManager } from './HistoryManager.js'
 import { MiddlewareChain } from './MiddlewareChain.js'
 import { Link } from './Link.js'
-import { normalizePath, parseQuery, emit, createURL, isExternalURL, isDynamicSegment } from './utils.js'
+import { PluginManager } from './PluginManager.js'
+import { TransitionsManager } from './TransitionsManager.js'
+import { ScrollManager } from './ScrollManager.js'
+import { normalizePath, parseQuery, emit, createURL, isExternalURL } from './utils.js'
 import { EVENTS, DEFAULT_CONFIG } from './constants.js'
 import { RouteLoadError, SafaError } from './errors.js'
 
 export class SafaRouter {
-  static version = '1.1.2'
-  static VERSION = '1.1.2'
+  static version = '1.2.0'
+  static VERSION = '1.2.0'
 
   constructor(options = {}) {
     this.config = { ...DEFAULT_CONFIG, ...options }
@@ -25,7 +28,7 @@ export class SafaRouter {
     })
     this._middleware = new MiddlewareChain()
     this._cache = new Map()
-    this._scrollMemory = new Map()
+    this._scrollManager = new ScrollManager()
 
     this._pathname = '/'
     this._params = {}
@@ -41,6 +44,15 @@ export class SafaRouter {
     this._globalLayout = this.config.layout || null
     this._customTitle = null
 
+    this._transitions = new TransitionsManager({
+      transitionDuration: this.config.transitionDuration,
+      transitionEnterClass: this.config.transitionEnterClass,
+      transitionExitClass: this.config.transitionExitClass,
+      transitionEnterActiveClass: this.config.transitionEnterActiveClass,
+      transitionExitActiveClass: this.config.transitionExitActiveClass,
+    })
+    this._plugins = new PluginManager(this)
+
     this._boundNav = this._onHistoryChange.bind(this)
   }
 
@@ -63,6 +75,13 @@ export class SafaRouter {
     this._routeTree = new RouteTree(this.config.routes || {})
     this._history.init()
     this._unsubHistory = this._history.onChange(this._boundNav)
+
+    if (Array.isArray(this.config.plugins)) {
+      for (const plugin of this.config.plugins) {
+        this._plugins.use(plugin)
+      }
+    }
+
     await this._resolve(this._history.path, 'replace')
     emit(this._events, EVENTS.READY, { pathname: this._pathname })
     this._started = true
@@ -73,6 +92,7 @@ export class SafaRouter {
 
   destroy() {
     this._started = false
+    this._plugins.ejectAll()
     if (this._unsubHistory) {
       this._unsubHistory()
       this._unsubHistory = null
@@ -80,6 +100,7 @@ export class SafaRouter {
     this._history.destroy()
     for (const k of Object.keys(this._events)) this._events[k] = []
     this._cache.clear()
+    this._scrollManager.clear()
     this._targetEl = null
     emit(this._events, EVENTS.DESTROY, {})
   }
@@ -96,6 +117,15 @@ export class SafaRouter {
     await this._navigate(normalizePath(u.pathname), 'replace', parseQuery(u.search), state)
   }
 
+  async pushRoute(routeName, params = {}, query = {}) {
+    const routes = this.config.routes || {}
+    const flat = this._routeTree.flatten()
+    const matched = flat.find(r => r.meta?.name === routeName || r.path === routeName)
+    if (!matched) throw new SafaError(`Route "${routeName}" not found`, 'ROUTE_NOT_FOUND')
+    const qs = Object.keys(query).length ? '?' + new URLSearchParams(query).toString() : ''
+    return this.push(matched.path + qs)
+  }
+
   back() { this._history.back() }
   forward() { this._history.forward() }
 
@@ -132,6 +162,33 @@ export class SafaRouter {
 
   createLink(config) { return new Link({ ...config, router: this }) }
 
+  plugin(plugin) { return this._plugins.use(plugin) }
+
+  ejectPlugin(name) { return this._plugins.eject(name) }
+
+  getPlugin(name) { return this._plugins.get(name) }
+
+  get plugins() { return this._plugins.list() }
+
+  useNamed(name, fn, priority = 0) {
+    this._middleware.useNamed(name, fn, priority)
+    return this
+  }
+
+  middleware(name) {
+    return this._middleware.remove(name)
+  }
+
+  insertMiddlewareBefore(refName, fn, priority = 0) {
+    this._middleware.insertBefore(refName, fn, priority)
+    return this
+  }
+
+  insertMiddlewareAfter(refName, fn, priority = 0) {
+    this._middleware.insertAfter(refName, fn, priority)
+    return this
+  }
+
   async prefetch(path) {
     const normalized = normalizePath(path)
     if (this._cache.has(normalized)) return
@@ -301,7 +358,7 @@ export class SafaRouter {
 
       if (this._navId !== navId) return
 
-      this._saveScroll()
+      this._scrollManager.save(this._pathname)
 
       if (method === 'push') this._history.push(path, state)
       else if (method === 'replace') this._history.replace(path, state)
@@ -311,9 +368,11 @@ export class SafaRouter {
       this._query = query
       this._isLoading = false
 
-      this._render(pageContent, layoutFns)
+      emit(this._events, EVENTS.BEFORE_RENDER, { pathname: path })
+      await this._render(pageContent, layoutFns)
+      emit(this._events, EVENTS.AFTER_RENDER, { pathname: path })
 
-      this._restoreScroll()
+      this._scrollManager.restore(this._pathname, this.config.scrollToTop)
       this._updateTitle()
       this._focus()
 
@@ -336,15 +395,14 @@ export class SafaRouter {
           ? pageContent({ params: this._params, query: this._query, router: this })
           : (pageContent || ''))
 
-    const duration = this.config.transitionDuration
-    if (duration > 0) {
-      this._targetEl.style.opacity = '0'
-      this._targetEl.style.transition = `opacity ${duration}ms ease`
-    }
-    this._targetEl.innerHTML = html
-    this._bindLinks()
-    if (duration > 0) {
-      requestAnimationFrame(() => { this._targetEl.style.opacity = '1' })
+    if (this.config.transitionDuration > 0) {
+      await this._transitions.run(this._targetEl, async () => {
+        this._targetEl.innerHTML = html
+        this._bindLinks()
+      })
+    } else {
+      this._targetEl.innerHTML = html
+      this._bindLinks()
     }
   }
 
@@ -360,21 +418,6 @@ export class SafaRouter {
     return layoutFn({ children: content, params: this._params, router: this })
   }
 
-  _saveScroll() {
-    this._scrollMemory.set(this._pathname, window.scrollY)
-  }
-
-  _restoreScroll() {
-    if (this.config.scrollToTop) {
-      window.scrollTo({ top: 0 })
-      return
-    }
-    const saved = this._scrollMemory.get(this._pathname)
-    if (saved !== undefined) {
-      window.scrollTo(0, saved)
-    }
-  }
-
   _updateTitle() {
     const template = this.config.titleTemplate
     if (!template) return
@@ -415,11 +458,20 @@ export class SafaRouter {
     if (!mod) return null
     try {
       if (typeof mod === 'string') {
+        if (mod.endsWith('.js') || mod.endsWith('.mjs')) {
+          try {
+            const resolved = await import(mod)
+            const page = resolved.default || resolved
+            return page
+          } catch {
+            // fall through to fetch
+          }
+        }
         let url = mod
         if (this._params && Object.keys(this._params).length > 0) {
           for (const [k, v] of Object.entries(this._params)) {
             const val = Array.isArray(v) ? v.join('/') : String(v)
-            url = url.replace(`[${k}]`, val)
+            url = url.replaceAll(`[${k}]`, val)
           }
         }
         const res = await fetch(url)
@@ -523,7 +575,7 @@ export class SafaRouter {
     if (action === 'popstate') {
       this._resolve(path, 'replace')
       if (state && state._scrollY !== undefined && !this.config.scrollToTop) {
-        window.scrollTo(0, state._scrollY)
+        requestAnimationFrame(() => window.scrollTo(0, state._scrollY))
       }
     }
   }

package/src/ScrollManager.js

@@ -0,0 +1,76 @@
+export class ScrollManager {
+  constructor() {
+    this._memory = new Map()
+    this._observers = new Map()
+    this._elementScroll = new Map()
+  }
+
+  save(pathname) {
+    this._memory.set(pathname, window.scrollY)
+    for (const [el, rect] of this._elementScroll) {
+      const key = `${pathname}::${el}`
+      this._memory.set(key, rect)
+    }
+  }
+
+  restore(pathname, scrollToTop = false) {
+    if (scrollToTop) {
+      window.scrollTo({ top: 0, behavior: 'instant' })
+      return
+    }
+    const saved = this._memory.get(pathname)
+    if (saved !== undefined && typeof saved === 'number') {
+      requestAnimationFrame(() => window.scrollTo(0, saved))
+    }
+  }
+
+  trackScrollElement(el) {
+    if (this._observers.has(el)) return
+    let ticking = false
+    const handler = () => {
+      if (!ticking) {
+        requestAnimationFrame(() => {
+          this._elementScroll.set(el, el.scrollTop)
+          ticking = false
+        })
+        ticking = true
+      }
+    }
+    el.addEventListener('scroll', handler, { passive: true })
+    this._observers.set(el, handler)
+  }
+
+  untrackScrollElement(el) {
+    const handler = this._observers.get(el)
+    if (handler) {
+      el.removeEventListener('scroll', handler)
+      this._observers.delete(el)
+      this._elementScroll.delete(el)
+    }
+  }
+
+  restoreElementScroll(pathname, container) {
+    const key = `${pathname}::${container}`
+    const saved = this._memory.get(key)
+    if (saved !== undefined) {
+      container.scrollTop = saved
+    }
+  }
+
+  clear() {
+    this._memory.clear()
+    this._elementScroll.clear()
+    for (const [el, handler] of this._observers) {
+      el.removeEventListener('scroll', handler)
+    }
+    this._observers.clear()
+  }
+
+  has(pathname) {
+    return this._memory.has(pathname)
+  }
+
+  get size() {
+    return this._memory.size
+  }
+}

package/src/TransitionsManager.js

@@ -0,0 +1,80 @@
+export class TransitionsManager {
+  constructor(config = {}) {
+    this._duration = config.transitionDuration || 0
+    this._enterClass = config.transitionEnterClass || 'page-enter'
+    this._exitClass = config.transitionExitClass || 'page-exit'
+    this._enterActiveClass = config.transitionEnterActiveClass || 'page-enter-active'
+    this._exitActiveClass = config.transitionExitActiveClass || 'page-exit-active'
+    this._custom = config.transitionCustom || null
+  }
+
+  async run(el, renderFn) {
+    if (this._duration <= 0 && !this._custom) {
+      return renderFn()
+    }
+
+    await this._exit(el)
+    await renderFn()
+    await this._enter(el)
+  }
+
+  async _exit(el) {
+    if (!el || this._duration <= 0) return
+    const { promise, resolve } = this._createDeferred()
+    el.classList.add(this._exitClass)
+    el.classList.add(this._exitActiveClass)
+    const timer = setTimeout(() => {
+      el.classList.remove(this._exitClass)
+      el.classList.remove(this._exitActiveClass)
+      resolve()
+    }, this._duration)
+    promise._timer = timer
+    return promise
+  }
+
+  async _enter(el) {
+    if (!el || this._duration <= 0) return
+    const { promise, resolve } = this._createDeferred()
+    el.classList.add(this._enterClass)
+    requestAnimationFrame(() => {
+      el.classList.add(this._enterActiveClass)
+      el.classList.remove(this._enterClass)
+    })
+    const timer = setTimeout(() => {
+      el.classList.remove(this._enterActiveClass)
+      resolve()
+    }, this._duration)
+    promise._timer = timer
+    return promise
+  }
+
+  cancelExit(el) {
+    if (!el) return
+    el.classList.remove(this._exitClass, this._exitActiveClass)
+  }
+
+  cancelEnter(el) {
+    if (!el) return
+    el.classList.remove(this._enterClass, this._enterActiveClass)
+  }
+
+  _createDeferred() {
+    let resolve
+    const promise = new Promise(r => { resolve = r })
+    return { promise, resolve }
+  }
+
+  setDuration(ms) {
+    this._duration = ms
+  }
+
+  get config() {
+    return {
+      duration: this._duration,
+      enterClass: this._enterClass,
+      exitClass: this._exitClass,
+      enterActiveClass: this._enterActiveClass,
+      exitActiveClass: this._exitActiveClass,
+    }
+  }
+}

package/src/constants.js

@@ -4,12 +4,16 @@ export const EVENTS = {
   NAVIGATE: 'navigate',
   ROUTE_CHANGE: 'routechange',
   AFTER_NAVIGATE: 'afternavigate',
+  BEFORE_RENDER: 'beforerender',
+  AFTER_RENDER: 'afterrender',
   ERROR: 'error',
   NOT_FOUND: 'notfound',
   LOADING: 'loading',
   READY: 'ready',
   DESTROY: 'destroy',
   LINK_CLICK: 'linkclick',
+  PLUGIN_INSTALL: 'plugininstall',
+  PLUGIN_EJECT: 'plugineject',
 }
 
 export const SEGMENT_TYPES = {
@@ -44,4 +48,10 @@ export const DEFAULT_CONFIG = {
   cacheRoutes: true,
   titleTemplate: '%s — SafaRouter',
   transitionDuration: 0,
+  transitionEnterClass: 'page-enter',
+  transitionExitClass: 'page-exit',
+  transitionEnterActiveClass: 'page-enter-active',
+  transitionExitActiveClass: 'page-exit-active',
+  scrollRestoration: 'auto',
+  plugins: [],
 }

package/src/index.js

@@ -4,6 +4,9 @@ export { RouteMatcher } from './RouteMatcher.js'
 export { HistoryManager } from './HistoryManager.js'
 export { MiddlewareChain } from './MiddlewareChain.js'
 export { Link } from './Link.js'
+export { PluginManager } from './PluginManager.js'
+export { TransitionsManager } from './TransitionsManager.js'
+export { ScrollManager } from './ScrollManager.js'
 export {
   SafaError,
   RouteNotFoundError,
@@ -11,6 +14,7 @@ export {
   RouteLoadError,
   NavigationAbortError,
 } from './errors.js'
-export { normalizePath, parseQuery, joinPaths, createURL, isExternalURL, isSamePath, isDynamicSegment, isCatchAllSegment, isOptionalCatchAll, isRouteGroupSegment, useRouter } from './utils.js'
+export { normalizePath, parseQuery, joinPaths, createURL, isExternalURL, isSamePath, isDynamicSegment, isCatchAllSegment, isOptionalCatchAll, isRouteGroupSegment, useRouter, debounce } from './utils.js'
 export { bindLinks, prefetchOnHover } from './link-helper.js'
 export { EVENTS, DEFAULT_CONFIG } from './constants.js'
+export { matchRoute, matchPattern, renderRoute, routeExists, listRoutes } from './ssr.js'

package/src/ssr.js

@@ -0,0 +1,61 @@
+import { RouteTree } from './RouteTree.js'
+import { RouteMatcher } from './RouteMatcher.js'
+import { normalizePath, parseQuery } from './utils.js'
+
+export function matchRoute(path, routes = {}) {
+  const tree = new RouteTree(routes)
+  const normalized = normalizePath(path)
+  const [pathname, search] = normalized.split('?')
+  const match = tree.resolve(pathname)
+  if (!match) return null
+  return {
+    path: pathname,
+    params: match.params,
+    query: parseQuery(search ? `?${search}` : ''),
+    node: match.node,
+    layouts: match.layouts,
+  }
+}
+
+export function matchPattern(path, patterns = []) {
+  const matcher = RouteMatcher.create(patterns)
+  return matcher.match(normalizePath(path))
+}
+
+export function renderRoute(path, routes = {}, context = {}) {
+  const match = matchRoute(path, routes)
+  if (!match) return null
+
+  async function renderComponent(mod) {
+    if (!mod) return ''
+    if (typeof mod === 'function') {
+      const result = mod({ params: match.params, router: context.router })
+      if (result && typeof result.then === 'function') return result
+      return result
+    }
+    return String(mod)
+  }
+
+  async function renderWithLayouts(pageContent, layoutFns, idx) {
+    if (idx >= layoutFns.length) {
+      return renderComponent(pageContent)
+    }
+    const content = await renderWithLayouts(pageContent, layoutFns, idx + 1)
+    const layoutFn = layoutFns[idx]
+    if (typeof layoutFn === 'function') {
+      return layoutFn({ children: content, params: match.params, router: context.router })
+    }
+    return String(layoutFn).replace(/\{\s*children\s*\}/gi, content)
+  }
+
+  return renderWithLayouts(match.node.page, match.layouts, 0)
+}
+
+export function routeExists(path, routes = {}) {
+  return matchRoute(path, routes) !== null
+}
+
+export function listRoutes(routes = {}) {
+  const tree = new RouteTree(routes)
+  return tree.flatten()
+}

package/src/utils.js

@@ -13,7 +13,8 @@ export function parseQuery(search) {
 }
 
 export function joinPaths(...parts) {
-  return normalizePath(parts.filter(Boolean).join('/'))
+  const joined = parts.filter(Boolean).join('/')
+  return joined.startsWith('/') ? normalizePath(joined) : '/' + normalizePath(joined)
 }
 
 export function isDynamicSegment(segment) {