@iyulab/router 0.7.6 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.8.0] - 2026-04-08
+
+### Added
+- Added navigation guards via `enter` hooks at both router level (`RouterConfig.enter`) and route level (`RouteConfig.enter`) with redirect/cancel flow support
+- Added `rel` attribute support to `<u-link>` for secure external navigation patterns (for example `noopener noreferrer`)
+
+### Changed
+- **Breaking:** Renamed route metadata fields from `meta` to `metadata` (`RouteConfig.metadata`, `RouteContext.metadata`)
+- Updated nested outlet resolution to prefer child outlet discovery inside the current outlet, improving deep nested route rendering behavior
+
 ## [0.7.6] - 2026-04-02
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # @iyulab/router
 
-A modern, lightweight client-side router for web applications with support for both Lit and React components.
+Client-side SPA router for Lit and React with URLPattern matching, nested routes, and route lifecycle events.
 
 ## Installation
 
@@ -10,270 +10,136 @@ npm install @iyulab/router
 
 ## Quick Start
 
-### Basic Setup
-
 ```typescript
 import { Router } from '@iyulab/router';
 import { html } from 'lit';
 
 const router = new Router({
+  root: document.body,
   basepath: '/',
   routes: [
-    {
-      index: true,
-      render: () => html`<home-page></home-page>`
-    },
-    {
-      path: '/user/:id', // URLPattern route
-      render: (routeInfo) => html`<user-page .userId=${routeInfo.params.id}></user-page>`
-    }
+    { index: true, render: () => html`<home-page></home-page>` },
+    { path: '/users/:id', render: (ctx) => html`<user-page .id=${ctx.params.id}></user-page>` },
   ],
-});
-```
-
-### Mixed Framework Support
-
-```typescript
-import React from 'react';
-
-const routes = [
-  // Lit component
-  {
-    path: '/lit-page',
-    render: (routeInfo) => {
-      return html`<my-lit-component .routeInfo=${routeInfo}></my-lit-component>`
-    }
-  },
-  // React component
-  {
-    path: '/react-page',
-    render: (routeInfo) => {
-      return ( <MyComponent></MyComponent> )
-    }
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`,
   },
-  // HTML element
-  {
-    path: '/element-page',
-    render: (routeInfo) => {
-      const element = document.createElement('my-element');
-      element.data = routeInfo.params;
-      return element;
-    }
-  }
-];
-```
-
-### Nested Routes
-
-```typescript
-import { RouteConfig } from '@iyulab/router';
+});
 
-const routes: RouteConfig[] = [
-  {
-    path: '/dashboard',
-    render: () => html`<dashboard-layout><u-outlet></u-outlet></dashboard-layout>`,
-    children: [
-      {
-        index: true, // Matches '/dashboard'
-        render: () => html`<dashboard-home></dashboard-home>`
-      },
-      {
-        path: 'settings', // Matches '/dashboard/settings'
-        render: () => html`<dashboard-settings></dashboard-settings>`
-      }
-    ]
-  }
-];
+router.go('/users/1');
 ```
 
 ## Skills Usage
 
-Install the `iyulab-router` skill to give your AI agent knowledge of this package's API and patterns.
-
-**Using GitHub shorthand:**
+Install the `iyulab-router` skill for agent-friendly package guidance.
 
 ```bash
 npx skills add iyulab/node-router
 ```
 
-**Using local path (after `npm install`):**
-
 ```bash
 npx skills add ./node_modules/@iyulab/router
 ```
 
-## Usage Examples
+## Route Guards
 
-### Using with Lit Elements
-
-```typescript
-import { LitElement, html } from 'lit';
-import { customElement } from 'lit/decorators.js';
-
-import "@iyulab/router";
-
-@customElement('app-root')
-export class AppRoot extends LitElement {
-  render() {
-    return html`
-      <nav>
-        <u-link href="/">Home</u-link>
-        <u-link href="/about">About</u-link>
-        <u-link href="/user/123">User Profile</u-link>
-      </nav>
-      <main>
-        <u-outlet></u-outlet>
-      </main>
-    `;
-  }
-}
-```
-
-### Using with React Components
-
-```tsx
-import React from 'react';
-import { UOutlet, ULink } from '@iyulab/router/react';
-
-export function AppRoot() {
-  return (
-    <div>
-      <nav>
-        <ULink href="/">Home</ULink>
-        <ULink href="/about">About</ULink>
-        <ULink href="/user/123">User Profile</ULink>
-      </nav>
-      <main>
-        <UOutlet />
-      </main>
-    </div>
-  );
-}
-```
-
-## Error Handling
-
-The router provides comprehensive error handling through `FallbackRouteContext`. When a routing error occurs, the fallback render function receives a context with full error information:
+Use `enter` to run guard logic before rendering.
 
 ```typescript
 const router = new Router({
   root: document.body,
-  basepath: '/',
-  routes: [...],
-  fallback: {
-    title: 'Error',
-    render: (ctx) => {
-      // ctx.error contains RouteError with code, message, and original error
-      const { code, message, original } = ctx.error;
-
-      if (code === 'NOT_FOUND') {
-        return html`<not-found-page .path=${ctx.pathname}></not-found-page>`;
-      }
-      if (code === 'CONTENT_LOAD_ERROR') {
-        return html`<error-page .message=${message}></error-page>`;
-      }
-      return html`<error-page .error=${ctx.error}></error-page>`;
-    }
-  }
+  enter: (ctx) => {
+    if (!isAuthenticated() && ctx.pathname !== '/login') return '/login';
+    return true;
+  },
+  routes: [
+    { path: '/login', render: () => html`<login-page></login-page>` },
+    {
+      path: '/admin',
+      enter: () => hasRole('admin') || '/forbidden',
+      render: () => html`<admin-page></admin-page>`,
+    },
+  ],
 });
 ```
 
-Error types:
-- `NotFoundError` — No matching route found (code: `NOT_FOUND`)
-- `ContentLoadError` — Route render function threw an error (code: `CONTENT_LOAD_ERROR`)
-- `ContentRenderError` — Outlet rendering failed (code: `CONTENT_RENDER_ERROR`)
+`enter` return values:
+- `true` (or `undefined`): continue
+- `false`: cancel navigation
+- `string`: redirect to that path
 
 ## Route Metadata
 
-Routes can carry arbitrary metadata via the `meta` field. When a route matches, metadata from the entire matched route chain is merged (parent → child order, child overrides parent):
+Attach metadata to routes using `metadata`. The router merges metadata from parent to child and exposes it on `ctx.metadata`.
 
 ```typescript
-const router = new Router({
-  root: document.body,
-  basepath: '/',
-  routes: [
-    {
-      path: '/admin',
-      meta: { requiresAuth: true, layout: 'admin' },
-      render: (ctx) => {
-        // ctx.meta === { requiresAuth: true, layout: 'admin' }
-        return html`<admin-layout><u-outlet></u-outlet></admin-layout>`;
+const routes = [
+  {
+    path: '/dashboard',
+    metadata: { requiresAuth: true, section: 'dashboard' },
+    render: () => html`<dashboard-layout><u-outlet></u-outlet></dashboard-layout>`,
+    children: [
+      {
+        path: 'settings',
+        metadata: { tab: 'settings' },
+        render: (ctx) => html`<settings-page .metadata=${ctx.metadata}></settings-page>`,
       },
-      children: [
-        {
-          path: 'settings',
-          meta: { requiresAuth: true, role: 'superadmin' },
-          render: (ctx) => {
-            // ctx.meta === { requiresAuth: true, layout: 'admin', role: 'superadmin' }
-            return html`<admin-settings></admin-settings>`;
-          }
-        }
-      ]
-    }
-  ]
-});
+    ],
+  },
+];
 ```
 
-Use cases: authentication guards, SEO tags, analytics tracking, layout selection, and more.
+## Nested Routes
 
-## Route Events
+Parent routes must render `<u-outlet>` to host child route content.
 
-The router dispatches events on the `window` object during navigation:
+```typescript
+const routes = [
+  {
+    path: '/nested',
+    render: () => html`<nested-layout><u-outlet></u-outlet></nested-layout>`,
+    children: [
+      { index: true, render: () => html`<nested-home></nested-home>` },
+      { path: 'lit', render: () => html`<nested-lit></nested-lit>` },
+      { path: 'react', render: () => <NestedReact /> },
+    ],
+  },
+];
+```
 
-| Event | Type | Description |
-|-------|------|-------------|
-| `route-begin` | `RouteBeginEvent` | Fired when navigation starts |
-| `route-progress` | `RouteProgressEvent` | Fired during async loading (0–100) |
-| `route-done` | `RouteDoneEvent` | Fired when navigation completes successfully |
-| `route-error` | `RouteErrorEvent` | Fired when a routing error occurs |
+## Link and Outlet Components
 
-```typescript
-// Track navigation progress
-window.addEventListener('route-progress', (e: RouteProgressEvent) => {
-  progressBar.value = e.progress;
-});
+- `<u-link>`: SPA-aware anchor element
+- `<u-outlet>`: render target for matched route output
 
-// Log navigation events
-window.addEventListener('route-begin', (e: RouteBeginEvent) => {
-  console.log('Navigating to:', e.context.pathname);
-});
+`<u-link>` supports `href`, `target`, and `rel`.
 
-window.addEventListener('route-done', (e: RouteDoneEvent) => {
-  analytics.trackPageView(e.context.pathname);
-});
+```html
+<u-link href="/docs">Docs</u-link>
+<u-link href="https://example.com" target="_blank" rel="noopener noreferrer">External</u-link>
+```
 
-window.addEventListener('route-error', (e: RouteErrorEvent) => {
-  errorTracker.report(e.error);
-});
+React wrappers:
+
+```tsx
+import { ULink, UOutlet } from '@iyulab/router/react';
 ```
 
-## URL Parameters
+## Route Events
+
+The router dispatches events on `window`:
 
-The router supports URLPattern-based parameter matching:
+- `route-begin`
+- `route-progress`
+- `route-done`
+- `route-error`
 
 ```typescript
-const routes: RouteConfig[] = [
-  // Required parameter
-  { path: '/user/:id', render: (ctx) => html`<user-page .id=${ctx.params.id}></user-page>` },
-
-  // Optional parameter
-  { path: '/posts/:category?', render: (ctx) => {
-    const category = ctx.params.category || 'all';
-    return html`<posts-page .category=${category}></posts-page>`;
-  }},
-
-  // Wildcard (catch-all)
-  { path: '/docs/:path*', render: (ctx) => html`<docs-page .path=${ctx.params.path}></docs-page>` },
-
-  // Multiple parameters
-  { path: '/org/:orgId/repo/:repoId', render: (ctx) => {
-    return html`<repo-page .orgId=${ctx.params.orgId} .repoId=${ctx.params.repoId}></repo-page>`;
-  }}
-];
+window.addEventListener('route-progress', (e) => {
+  console.log(e.progress);
+});
 ```
 
-When URL parameters change (e.g., navigating from `/user/1` to `/user/2`), leaf routes (without children) automatically re-render since `force` defaults to `true`. For parent routes with children, set `force: true` explicitly if re-rendering is needed on parameter changes.
-
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License. See [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -47,6 +47,17 @@ declare interface BaseRouteConfig {
      * ```
      */
     render?: (ctx: RouteContext) => Promise<unknown> | unknown;
+    /**
+     * 이 라우트 진입 전에 호출되는 enter 함수입니다.
+     * - `string` 반환: 해당 경로로 redirect
+     * - `false` 반환: 네비게이션 취소
+     * - `true` 반환: 통과
+     * @example
+     * ```typescript
+     * { path: '/admin', enter: (ctx) => ctx.metadata.role === 'admin' || '/forbidden' }
+     * ```
+     */
+    enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
     /**
      * 라우터 URL 변경시 렌더링을 강제할지 여부
      * - 기본값으로 children을 가질때 false로 설정되며, children이 없을 경우 true로 설정됩니다.
@@ -63,10 +74,10 @@ declare interface BaseRouteConfig {
      * - 인증, SEO, 분석 등의 용도로 사용할 수 있습니다.
      * @example
      * ```typescript
-     * { path: '/admin', meta: { requiresAuth: true, role: 'admin' } }
+     * { path: '/admin', metadata: { requiresAuth: true, role: 'admin' } }
      * ```
      */
-    meta?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
 }
 
 /**
@@ -156,8 +167,6 @@ declare interface RenderOption {
     id?: string;
     /** 강제 렌더링 여부 */
     force?: boolean;
-    /** 렌더링할 값 */
-    value: unknown;
 }
 
 /**
@@ -244,7 +253,7 @@ export declare interface RouteContext {
      * 매칭된 라우트 체인의 병합된 메타데이터
      * - 부모 라우트에서 자식 라우트 순서로 병합됩니다.
      */
-    meta: Record<string, unknown>;
+    metadata: Record<string, unknown>;
 }
 
 /**
@@ -316,6 +325,7 @@ export declare class Router {
     private readonly _basepath;
     private readonly _routes;
     private readonly _fallback?;
+    private readonly _enter?;
     /** 현재 라우팅 요청 ID */
     private _requestID?;
     /** 현재 라우팅 정보 */
@@ -333,7 +343,7 @@ export declare class Router {
      * 지정한 경로의 클라이언트 라우팅을 수행합니다. 상대경로일 경우 basepath와 조합되어 이동합니다.
      * @param href 이동할 경로
      */
-    go(href: string): Promise<void>;
+    go(href: string): Promise<undefined>;
     /** 브라우저 히스토리 이벤트가 발생시 라우팅 처리 */
     private handleWindowPopstate;
     /** 클릭 이벤트에서 라우터로 처리할 앵커를 찾아 클라이언트 라우팅 수행 */
@@ -361,6 +371,19 @@ export declare interface RouterConfig {
      * - 라우트는 렌더링할 엘리먼트 또는 컴포넌트를 지정합니다.
      */
     routes?: RouteConfig[];
+    /**
+     * 모든 라우트 전환 전에 호출되는 글로벌 enter 함수입니다.
+     * - `string` 반환: 해당 경로로 redirect
+     * - `false` 반환: 네비게이션 취소
+     * - `true` 반환: 통과
+     * @example
+     * ```typescript
+     * enter: async (ctx) => {
+     *   if (!isAuthenticated() && ctx.pathname !== '/login') return '/login';
+     * }
+     * ```
+     */
+    enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
     /**
      * 라우트 매칭 실패 또는 오류 발생 시 대체 라우트 설정
      * - 지정된 설정이 없을 경우, 기본 오류 페이지가 렌더링됩니다.
@@ -395,6 +418,16 @@ export declare class ULink extends LitElement {
      * - `_top`: 최상위 프레임에서 링크 열기
      */
     target?: string;
+    /**
+     * 링크 관계 rel 속성
+     *
+     * - `noopener`: target이 _blank인 경우 보안 강화 (window.opener 차단)
+     * - `noreferrer`: target이 _blank인 경우 보안 강화 + Referer 헤더 제거
+     * - `external`: 외부 링크임을 명시 (SEO/접근성에 도움)
+     * - `nofollow`: 검색 엔진이 링크를 따라가지 않도록 지시 (SEO에 영향)
+     * - 그 외 rel 값도 그대로 전달됩니다.
+     */
+    rel?: string;
     /**
      * 링크 대상 URL, 다음 사항에 따라 SPA 라우팅 또는 브라우저 네비게이션이 결정됩니다.
      *
@@ -436,7 +469,7 @@ export declare class UOutlet extends HTMLElement {
     /**
      * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
      */
-    render({ id, value, force }: RenderOption): Promise<void>;
+    render(value: unknown, options?: RenderOption): Promise<void>;
     /**
      * 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
      */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as isExternalUrl, i as absolutePath, n as __decorate, o as parseUrl, r as __decorateMetadata, s as UOutlet, t as ULink } from "./share-sbAElOI7.js";
+import { a as isExternalUrl, i as absolutePath, n as __decorate, o as parseUrl, r as __decorateMetadata, s as UOutlet, t as ULink } from "./share-CUGwxZKa.js";
 import { LitElement, css, html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 //#region src/types/RouteError.ts
@@ -214,10 +214,11 @@ function getRandomID() {
 * `u-outlet` 엘리먼트를 찾아 반환합니다. 
 * 
 * @param element 검색을 시작할 HTMLElement
+* @param skip element 자신을 검사에서 제외할지 여부 (기본값: false)
 * @returns 찾은 UOutlet 엘리먼트 또는 undefined
 */
-function findOutlet(element) {
-	if (element.tagName === "U-OUTLET") return element;
+function findOutlet(element, skip = false) {
+	if (!skip && element instanceof UOutlet) return element;
 	const roots = element.shadowRoot ? [element.shadowRoot, element] : [element];
 	for (const root of roots) for (const child of Array.from(root.children)) {
 		const result = findOutlet(child);
@@ -353,6 +354,7 @@ var Router = class {
 		this._basepath = absolutePath(config.basepath || "/");
 		this._routes = setRoutes(config.routes || [], this._basepath);
 		this._fallback = config.fallback;
+		this._enter = config.enter;
 		window.addEventListener("popstate", this.handleWindowPopstate);
 		if (config.useIntercept !== false) document.addEventListener("click", this.handleDocumentClick);
 		if (config.initialLoad !== false) waitOutlet(this._rootElement).then(() => {
@@ -396,14 +398,20 @@ var Router = class {
 		context.progress = progressCallback;
 		let outlet = void 0;
 		try {
+			if (this._enter) {
+				const result = await this._enter(context);
+				if (this._requestID !== requestID) return;
+				if (typeof result === "string") return void this.go(result);
+				if (result === false) return;
+			}
 			if (this._requestID !== requestID) return;
 			window.dispatchEvent(new RouteBeginEvent(context));
 			const routes = getRoutes(this._routes, context.pathname);
 			const lastRoute = routes[routes.length - 1];
 			if (lastRoute && lastRoute.path instanceof URLPattern) context.params = lastRoute.path.exec({ pathname: context.pathname })?.pathname.groups || {};
 			const mergedMeta = {};
-			for (const route of routes) if (route.meta) Object.assign(mergedMeta, route.meta);
-			context.meta = mergedMeta;
+			for (const route of routes) if (route.metadata) Object.assign(mergedMeta, route.metadata);
+			context.metadata = mergedMeta;
 			this._context = context;
 			outlet = findOutletOrThrow(this._rootElement);
 			let title = void 0;
@@ -411,6 +419,12 @@ var Router = class {
 			if (routes.length === 0) throw new NotFoundError(context.href);
 			for (const route of routes) {
 				if (this._requestID !== requestID) return;
+				if (route.enter) {
+					const result = await route.enter(context);
+					if (this._requestID !== requestID) return;
+					if (typeof result === "string") return void this.go(result);
+					if (result === false) return;
+				}
 				if (!route.render) continue;
 				try {
 					content = await route.render(context);
@@ -419,15 +433,14 @@ var Router = class {
 					throw new ContentLoadError(LoadError);
 				}
 				try {
-					outlet.render({
+					outlet.render(content, {
 						id: route.id,
-						value: content,
 						force: route.force
 					});
 				} catch (renderError) {
 					throw new ContentRenderError(renderError);
 				}
-				outlet = findOutlet(outlet) || outlet;
+				outlet = findOutlet(outlet, true) || outlet;
 				title = route.title || title;
 			}
 			document.title = title || document.title;
@@ -442,18 +455,16 @@ var Router = class {
 						...context,
 						error: routeError
 					});
-					outlet.render({
+					outlet.render(fallbackContent, {
 						id: "#fallback",
-						value: fallbackContent,
 						force: true
 					});
 					document.title = this._fallback.title || document.title;
 				} else {
 					const errorContent = new UErrorPage();
 					errorContent.error = error;
-					if (outlet) outlet.render({
+					if (outlet) outlet.render(errorContent, {
 						id: "#error",
-						value: errorContent,
 						force: true
 					});
 					else {

package/dist/react.d.ts

@@ -10,8 +10,6 @@ declare interface RenderOption {
     id?: string;
     /** 강제 렌더링 여부 */
     force?: boolean;
-    /** 렌더링할 값 */
-    value: unknown;
 }
 
 /**
@@ -36,6 +34,16 @@ declare class ULink_2 extends LitElement {
      * - `_top`: 최상위 프레임에서 링크 열기
      */
     target?: string;
+    /**
+     * 링크 관계 rel 속성
+     *
+     * - `noopener`: target이 _blank인 경우 보안 강화 (window.opener 차단)
+     * - `noreferrer`: target이 _blank인 경우 보안 강화 + Referer 헤더 제거
+     * - `external`: 외부 링크임을 명시 (SEO/접근성에 도움)
+     * - `nofollow`: 검색 엔진이 링크를 따라가지 않도록 지시 (SEO에 영향)
+     * - 그 외 rel 값도 그대로 전달됩니다.
+     */
+    rel?: string;
     /**
      * 링크 대상 URL, 다음 사항에 따라 SPA 라우팅 또는 브라우저 네비게이션이 결정됩니다.
      *
@@ -82,7 +90,7 @@ declare class UOutlet_2 extends HTMLElement {
     /**
      * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
      */
-    render({ id, value, force }: RenderOption): Promise<void>;
+    render(value: unknown, options?: RenderOption): Promise<void>;
     /**
      * 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
      */

package/dist/react.js

@@ -1,4 +1,4 @@
-import { s as UOutlet$1, t as ULink$1 } from "./share-sbAElOI7.js";
+import { s as UOutlet$1, t as ULink$1 } from "./share-CUGwxZKa.js";
 import React from "react";
 import { createComponent } from "@lit/react";
 //#region src/react.ts

package/dist/{share-sbAElOI7.js → share-CUGwxZKa.js}

@@ -9,9 +9,9 @@ var UOutlet = class extends HTMLElement {
 	/**
 	* 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
 	*/
-	async render({ id, value, force }) {
-		if (this.routeId === id && force === false) return;
-		this.routeId = id;
+	async render(value, options) {
+		if (this.routeId === options?.id && options?.force === false) return;
+		this.routeId = options?.id;
 		this.reset();
 		if (value === null) throw new Error("Content is null and cannot be rendered.");
 		if (typeof value !== "object") throw new Error("Content is not a valid renderable object.");
@@ -88,7 +88,7 @@ function parseUrl(url, basepath) {
 		hash: urlObj.hash,
 		params: {},
 		progress: () => {},
-		meta: {}
+		metadata: {}
 	};
 }
 /**
@@ -126,12 +126,12 @@ function catchBasepath(basepath) {
 	return basepath;
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.122.0/helpers/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.123.0/helpers/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.122.0/helpers/decorate.js
+//#region \0@oxc-project+runtime@0.123.0/helpers/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -189,7 +189,11 @@ var ULink = class ULink extends LitElement {
 	}
 	render() {
 		return html`
-      <a target=${ifDefined(this.target)} href=${this.compute(this.href)}>
+      <a
+        href=${this.compute(this.href)}
+        target=${ifDefined(this.target)}
+        rel=${ifDefined(this.rel)}
+      >
         <slot></slot>
       </a>
     `;
@@ -231,6 +235,7 @@ var ULink = class ULink extends LitElement {
 	}
 };
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], ULink.prototype, "target", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], ULink.prototype, "rel", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], ULink.prototype, "href", void 0);
 ULink = __decorate([customElement("u-link")], ULink);
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/router",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "A modern client-side router for web applications with support for Lit and React components",
   "keywords": [
     "lit",

package/skills/iyulab-router/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: iyulab-router
-description: Client-side SPA router for Lit and React with URLPattern-based matching, nested routes, fallback handling, and route events. Use when working with @iyulab/router — setting up routing, defining routes, handling navigation, nested layouts with <u-outlet>, or listening to route lifecycle events.
+description: Client-side SPA router for Lit and React with URLPattern matching, nested routes, route guards, metadata merging, fallback handling, and route events. Use when working with @iyulab/router to define routes, add guards, handle navigation, or integrate <u-outlet>/<u-link>.
 license: MIT
 compatibility: Browser environments only (requires URLPattern and History API)
 metadata:
   author: iyulab
-  version: "0.7.4"
+  version: "0.8.0"
 ---
 
 # @iyulab/router
 
-Client-side router supporting Lit and React renders, nested routes, and URLPattern-based matching.
+Client-side router supporting Lit and React renders, nested routes, route guards, and URLPattern-based matching.
 
 ## Install
 
@@ -40,9 +40,19 @@ import { html } from 'lit';
 const router = new Router({
   root: document.body,       // required — mount element containing <u-outlet>
   basepath: '/',             // optional
+  enter: (ctx) => {
+    if (!isAuthenticated() && ctx.pathname !== '/login') return '/login';
+    return true;
+  },
   routes: [
     { index: true, render: () => html`<home-page></home-page>` },
     { path: '/user/:id', render: (ctx) => html`<user-page .id=${ctx.params.id}></user-page>` },
+    {
+      path: '/admin',
+      metadata: { role: 'admin' },
+      enter: (ctx) => ctx.metadata.role === 'admin' || '/forbidden',
+      render: () => html`<admin-page></admin-page>`,
+    },
   ],
   fallback: {
     render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`
@@ -57,9 +67,10 @@ const router = new Router({
 | `path` | `string \| URLPattern` | URLPattern path; omit when `index: true` |
 | `index` | `true` | Marks route as index of its parent path |
 | `render` | `(ctx) => unknown` | Returns Lit `TemplateResult`, React element, or `HTMLElement` |
+| `enter` | `(ctx) => string \| boolean \| Promise<string \| boolean>` | Guard before route render (`false` cancel, `string` redirect) |
 | `children` | `RouteConfig[]` | Nested routes; parent must render `<u-outlet>` |
 | `title` | `string` | Sets `document.title` on match |
-| `meta` | `Record<string, unknown>` | Arbitrary metadata (auth, layout, analytics) |
+| `metadata` | `Record<string, unknown>` | Arbitrary metadata (auth, layout, analytics) |
 | `force` | `boolean` | Force re-render on URL change (default `true` for leaf routes) |
 
 ## RouteContext Fields
@@ -69,7 +80,7 @@ ctx.params     // URLPattern captured params
 ctx.pathname   // path without query/hash
 ctx.path       // full path including query + hash
 ctx.query      // URLSearchParams
-ctx.meta       // merged meta from matched route chain
+ctx.metadata   // merged metadata from matched route chain
 ctx.progress   // (value: number) => void — report 0–100 loading progress
 ```
 
@@ -103,6 +114,12 @@ import { ULink } from '@iyulab/router/react';
 <ULink href="/about">About</ULink>
 ```
 
+`<u-link>` supports `href`, `target`, and `rel`.
+
+```html
+<u-link href="https://example.com" target="_blank" rel="noopener noreferrer">External</u-link>
+```
+
 ## Route Events (window)
 
 | Event | Fired when |
@@ -120,4 +137,9 @@ import { ULink } from '@iyulab/router/react';
 | `CONTENT_LOAD_ERROR` | `ContentLoadError` |
 | `CONTENT_RENDER_ERROR` | `ContentRenderError` |
 
-See [references/REFERENCE.md](references/REFERENCE.md) for URL parameter patterns, React usage, and advanced examples.
+References:
+- [references/routing-basics.md](references/routing-basics.md)
+- [references/url-pattern.md](references/url-pattern.md)
+- [references/guards-and-metadata.md](references/guards-and-metadata.md)
+- [references/components.md](references/components.md)
+- [references/events-and-errors.md](references/events-and-errors.md)

package/skills/iyulab-router/references/components.md

@@ -0,0 +1,43 @@
+# Components
+
+## Lit Usage
+
+```ts
+import '@iyulab/router';
+import { html } from 'lit';
+
+html`
+  <nav>
+    <u-link href="/">Home</u-link>
+    <u-link href="/docs">Docs</u-link>
+    <u-link href="https://example.com" target="_blank" rel="noopener noreferrer">External</u-link>
+  </nav>
+  <main>
+    <u-outlet></u-outlet>
+  </main>
+`;
+```
+
+## React Wrappers
+
+```tsx
+import { ULink, UOutlet } from '@iyulab/router/react';
+
+export function AppRoot() {
+  return (
+    <div>
+      <nav>
+        <ULink href="/">Home</ULink>
+        <ULink href="/about">About</ULink>
+      </nav>
+      <main>
+        <UOutlet />
+      </main>
+    </div>
+  );
+}
+```
+
+## Nested Outlet Rule
+
+A parent route must render `<u-outlet>` to host child route content.

package/skills/iyulab-router/references/events-and-errors.md

@@ -0,0 +1,39 @@
+# Events and Errors
+
+## Route Events
+
+```ts
+window.addEventListener('route-begin', (e) => {
+  console.log(e.context.pathname);
+});
+
+window.addEventListener('route-progress', (e) => {
+  progressBar.value = e.progress;
+});
+
+window.addEventListener('route-done', (e) => {
+  analytics.track(e.context.pathname);
+});
+
+window.addEventListener('route-error', (e) => {
+  errorTracker.report(e.error);
+});
+```
+
+## Fallback
+
+```ts
+fallback: {
+  render: (ctx) => {
+    const { code, message } = ctx.error;
+    if (code === 'NOT_FOUND') return html`<not-found-page></not-found-page>`;
+    return html`<error-page .message=${message}></error-page>`;
+  }
+}
+```
+
+## Error Codes
+
+- `NOT_FOUND`
+- `CONTENT_LOAD_ERROR`
+- `CONTENT_RENDER_ERROR`

package/skills/iyulab-router/references/guards-and-metadata.md

@@ -0,0 +1,50 @@
+# Guards and Metadata
+
+## Global Guard
+
+```ts
+const router = new Router({
+  root: document.body,
+  enter: (ctx) => {
+    if (!isAuthenticated() && ctx.pathname !== '/login') return '/login';
+    return true;
+  },
+  routes: [...],
+});
+```
+
+## Route Guard
+
+```ts
+{
+  path: '/admin',
+  enter: () => hasRole('admin') || '/forbidden',
+  render: () => html`<admin-page></admin-page>`
+}
+```
+
+Guard return values:
+- `true` or `undefined`: continue
+- `false`: cancel navigation
+- `string`: redirect
+
+## Route Metadata
+
+```ts
+{
+  path: '/admin',
+  metadata: { requiresAuth: true, section: 'admin' },
+  render: (ctx) => {
+    // merged metadata from matched chain
+    console.log(ctx.metadata);
+    return html`<admin-layout><u-outlet></u-outlet></admin-layout>`;
+  },
+  children: [
+    {
+      path: 'settings',
+      metadata: { tab: 'settings' },
+      render: (ctx) => html`<settings-page .metadata=${ctx.metadata}></settings-page>`
+    }
+  ]
+}
+```

package/skills/iyulab-router/references/routing-basics.md

@@ -0,0 +1,40 @@
+# Routing Basics
+
+## Minimal Setup
+
+```ts
+import { Router } from '@iyulab/router';
+import { html } from 'lit';
+
+const router = new Router({
+  root: document.body,
+  basepath: '/',
+  routes: [
+    { index: true, render: () => html`<home-page></home-page>` },
+    { path: '/users/:id', render: (ctx) => html`<user-page .id=${ctx.params.id}></user-page>` },
+  ],
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`,
+  },
+});
+```
+
+## RouterConfig Options
+
+| Option | Default | Description |
+|---|---|---|
+| `root` | - | Mount element (required) |
+| `basepath` | `'/'` | URL base path |
+| `routes` | `[]` | Route definitions |
+| `enter` | - | Global guard before navigation |
+| `fallback` | built-in error page | Error/404 handler |
+| `useIntercept` | `true` | Intercept `<a>` clicks for client routing |
+| `initialLoad` | `true` | Auto-navigate on initialization |
+
+## Navigation
+
+```ts
+router.go('/dashboard');
+router.go('settings');
+router.destroy();
+```

package/skills/iyulab-router/references/url-pattern.md

@@ -0,0 +1,32 @@
+# URL Pattern
+
+## Supported Patterns
+
+```ts
+// Required
+{ path: '/user/:id' }
+
+// Optional
+{ path: '/posts/:category?' }
+
+// Wildcard
+{ path: '/docs/:path*' }
+
+// Multiple params
+{ path: '/org/:orgId/repo/:repoId' }
+```
+
+Access params via `ctx.params`.
+
+```ts
+ctx.params.id;
+ctx.params.category;
+```
+
+## Query and Hash
+
+```ts
+ctx.query.get('q');
+ctx.query.get('page');
+ctx.hash;
+```

package/skills/iyulab-router/references/REFERENCE.md

@@ -1,175 +0,0 @@
-# @iyulab/router — Reference
-
-## URL Parameter Patterns
-
-```ts
-// Required
-{ path: '/user/:id' }
-
-// Optional
-{ path: '/posts/:category?' }
-
-// Wildcard (catch-all)
-{ path: '/docs/:path*' }
-
-// Multiple
-{ path: '/org/:orgId/repo/:repoId' }
-```
-
-Access via `ctx.params.id`, `ctx.params.category`, etc.
-
-## Query String
-
-```ts
-// URL: /search?q=hello&page=2
-ctx.query.get('q')     // 'hello'
-ctx.query.get('page')  // '2'
-```
-
-## Route Meta
-
-Meta from the full matched chain is merged (parent → child, child overrides):
-
-```ts
-{
-  path: '/admin',
-  meta: { requiresAuth: true, layout: 'admin' },
-  render: (ctx) => {
-    // ctx.meta === { requiresAuth: true, layout: 'admin' }
-    return html`<admin-layout><u-outlet></u-outlet></admin-layout>`;
-  },
-  children: [
-    {
-      path: 'settings',
-      meta: { role: 'superadmin' },
-      render: (ctx) => {
-        // ctx.meta === { requiresAuth: true, layout: 'admin', role: 'superadmin' }
-        return html`<admin-settings></admin-settings>`;
-      }
-    }
-  ]
-}
-```
-
-## Async Render with Progress
-
-```ts
-{
-  path: '/user/:id',
-  render: async (ctx) => {
-    ctx.progress(20);
-    const user = await fetchUser(ctx.params.id);
-    ctx.progress(80);
-    return html`<user-profile .data=${user}></user-profile>`;
-  }
-}
-```
-
-## Route Events
-
-```ts
-window.addEventListener('route-begin', (e) => {
-  console.log('navigating to:', e.context.pathname);
-});
-
-window.addEventListener('route-progress', (e) => {
-  progressBar.value = e.progress; // 0–100
-});
-
-window.addEventListener('route-done', (e) => {
-  analytics.track(e.context.pathname);
-});
-
-window.addEventListener('route-error', (e) => {
-  errorTracker.report(e.error);
-});
-```
-
-## Error Fallback
-
-```ts
-fallback: {
-  render: (ctx) => {
-    const { code, message } = ctx.error;
-    if (code === 'NOT_FOUND') return html`<not-found-page></not-found-page>`;
-    return html`<error-page .message=${message}></error-page>`;
-  }
-}
-```
-
-## React Usage
-
-```tsx
-import { UOutlet, ULink } from '@iyulab/router/react';
-
-export function AppRoot() {
-  return (
-    <div>
-      <nav>
-        <ULink href="/">Home</ULink>
-        <ULink href="/about">About</ULink>
-      </nav>
-      <main>
-        <UOutlet />
-      </main>
-    </div>
-  );
-}
-```
-
-Mixed Lit + React routes:
-
-```ts
-const routes = [
-  {
-    path: '/lit-page',
-    render: () => html`<my-lit-component></my-lit-component>`
-  },
-  {
-    path: '/react-page',
-    render: () => <MyReactComponent />
-  },
-  {
-    path: '/raw-element',
-    render: (ctx) => {
-      const el = document.createElement('my-element');
-      el.data = ctx.params;
-      return el;
-    }
-  }
-];
-```
-
-## RouterConfig Options
-
-| Option | Default | Description |
-|---|---|---|
-| `root` | — | Mount element (required) |
-| `basepath` | `'/'` | URL base path |
-| `routes` | `[]` | Route definitions |
-| `fallback` | built-in error page | Error/404 handler |
-| `useIntercept` | `true` | Intercept `<a>` clicks for client routing |
-| `initialLoad` | `true` | Auto-navigate to current URL on init |
-
-## Lit Element Integration
-
-```ts
-import "@iyulab/router"; // registers <u-outlet> and <u-link>
-import { LitElement, html } from 'lit';
-import { customElement } from 'lit/decorators.js';
-
-@customElement('app-root')
-export class AppRoot extends LitElement {
-  render() {
-    return html`
-      <nav>
-        <u-link href="/">Home</u-link>
-        <u-link href="/about">About</u-link>
-      </nav>
-      <main>
-        <u-outlet></u-outlet>
-      </main>
-    `;
-  }
-}
-```