@iyulab/router 0.7.6 → 0.9.0

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
@@ -24,6 +24,14 @@ var NotFoundError = class extends RouteError {
 	}
 };
 /**
+* enter 가드가 false를 반환하여 접근이 거부되었을 때 발생하는 에러
+*/
+var AccessDeniedError = class extends RouteError {
+	constructor(path) {
+		super(403, `Access denied: ${path}`);
+	}
+};
+/**
 * u-outlet 요소를 찾을 수 없을 때 발생하는 에러
 */
 var OutletMissingError = class extends RouteError {
@@ -105,8 +113,12 @@ var RouteErrorEvent = class extends RouteEvent {
 };
 //#endregion
 //#region src/components/UErrorPage.ts
-var _ref;
+var _ref, _ref2;
 var UErrorPage = class UErrorPage extends LitElement {
+	constructor(error) {
+		super();
+		this.error = error;
+	}
 	render() {
 		const error = this.error || this.getDefaultError();
 		return html`
@@ -121,14 +133,13 @@ var UErrorPage = class UErrorPage extends LitElement {
 	}
 	/** 에러 코드에 따른 기본 아이콘 반환 */
 	getErrorIcon(code) {
-		const codeStr = String(code);
-		const numericCode = typeof code === "string" ? parseInt(code) : code;
-		switch (codeStr) {
+		switch (String(code)) {
 			case "OUTLET_MISSING": return "📦";
 			case "CONTENT_LOAD_FAILED": return "📡";
 			case "CONTENT_RENDER_FAILED": return "🎨";
+			case "ACCESS_DENIED": return "🚫";
 		}
-		switch (numericCode) {
+		switch (typeof code === "string" ? parseInt(code) : code) {
 			case 404: return "🔍";
 			case 403: return "🚫";
 			case 401: return "🔐";
@@ -194,8 +205,8 @@ var UErrorPage = class UErrorPage extends LitElement {
   `;
 	}
 };
-__decorate([property({ type: Object }), __decorateMetadata("design:type", typeof (_ref = typeof RouteError !== "undefined" && RouteError) === "function" ? _ref : Object)], UErrorPage.prototype, "error", void 0);
-UErrorPage = __decorate([customElement("u-error-page")], UErrorPage);
+__decorate([property({ type: Object }), __decorateMetadata("design:type", typeof (_ref2 = typeof RouteError !== "undefined" && RouteError) === "function" ? _ref2 : Object)], UErrorPage.prototype, "error", void 0);
+UErrorPage = __decorate([customElement("u-error-page"), __decorateMetadata("design:paramtypes", [typeof (_ref = typeof RouteError !== "undefined" && RouteError) === "function" ? _ref : Object])], UErrorPage);
 //#endregion
 //#region src/internals/crypto-helpers.ts
 /**
@@ -214,10 +225,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);
@@ -322,15 +334,55 @@ function getRoutes(routes, pathname) {
 	return [];
 }
 //#endregion
+//#region src/internals/RouteTracker.ts
+/**
+* 라우팅 체인 상태를 추적합니다.
+* - 방문한 href를 기록하여 리다이렉트 사이클을 감지합니다.
+* - 이미 실행된 route enter를 기록하여 중복 실행을 방지합니다.
+*/
+var RouteTracker = class {
+	constructor() {
+		this._history = /* @__PURE__ */ new Set();
+		this._processed = /* @__PURE__ */ new Set();
+	}
+	/** 새 네비게이션 시작 시 상태를 초기화합니다. */
+	reset() {
+		this._history.clear();
+		this._processed.clear();
+	}
+	/**
+	* href 방문을 기록하고 사이클 여부를 반환합니다.
+	* @returns 사이클이 감지되면 true
+	*/
+	visit(href) {
+		if (this._history.has(href)) {
+			console.error("Router: Redirect cycle detected:", [...this._history, href].join(" → "));
+			return true;
+		}
+		this._history.add(href);
+		return false;
+	}
+	/**
+	* route enter를 아직 실행하지 않았다면 키를 등록하고 true를 반환합니다.
+	* 이미 실행된 route라면 false를 반환합니다 (중첩 라우트 redirect 체인에서 중복 방지).
+	*/
+	enter(route) {
+		const key = route.id ?? (route.path instanceof URLPattern ? route.path.pathname : String(route.path));
+		if (this._processed.has(key)) return false;
+		this._processed.add(key);
+		return true;
+	}
+};
+//#endregion
 //#region src/Router.ts
 /**
 * `lit-element`, `react`를 지원하는 SPA 클라이언트 라우터 객체입니다.
 */
 var Router = class {
 	constructor(config) {
+		this._tracker = new RouteTracker();
 		this.handleWindowPopstate = async (_) => {
-			const href = window.location.href;
-			await this.go(href);
+			await this.go(window.location.href);
 		};
 		this.handleDocumentClick = async (e) => {
 			try {
@@ -353,6 +405,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(() => {
@@ -381,92 +434,100 @@ var Router = class {
 	/**
 	* 지정한 경로의 클라이언트 라우팅을 수행합니다. 상대경로일 경우 basepath와 조합되어 이동합니다.
 	* @param href 이동할 경로
+	* @param options 네비게이션 옵션
 	*/
-	async go(href) {
+	async go(href, options) {
+		if (!options?.isRedirect) this._tracker.reset();
 		const requestID = getRandomID();
 		this._requestID = requestID;
 		const context = parseUrl(href, this._basepath);
-		if (context.href !== window.location.href) window.history.pushState({ basepath: context.basepath }, "", context.href);
-		else window.history.replaceState({ basepath: context.basepath }, "", context.href);
-		const progressCallback = (value) => {
-			if (this._requestID !== requestID) return;
-			const progress = Math.max(0, Math.min(100, Math.round(value)));
-			window.dispatchEvent(new RouteProgressEvent(context, progress));
+		if (this._tracker.visit(context.href)) return;
+		const useReplace = options?.isRedirect || options?.replace || context.href === window.location.href;
+		const historyState = {
+			basepath: context.basepath,
+			...options?.state
 		};
-		context.progress = progressCallback;
+		if (useReplace) window.history.replaceState(historyState, "", context.href);
+		else window.history.pushState(historyState, "", context.href);
 		let outlet = void 0;
+		let title = void 0;
 		try {
-			if (this._requestID !== requestID) return;
-			window.dispatchEvent(new RouteBeginEvent(context));
+			outlet = findOutletOrThrow(this._rootElement);
 			const routes = getRoutes(this._routes, context.pathname);
+			if (routes.length === 0) throw new NotFoundError(context.href);
 			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;
+			if (lastRoute.path instanceof URLPattern) context.params = lastRoute.path.exec({ pathname: context.pathname })?.pathname.groups || {};
+			context.progress = (value) => {
+				if (this._requestID !== requestID) return;
+				const progress = Math.max(0, Math.min(100, Math.round(value)));
+				window.dispatchEvent(new RouteProgressEvent(context, progress));
+			};
+			if (this._enter && !options?.isRedirect) {
+				const result = await this._enter(context);
+				if (this._requestID !== requestID) return;
+				if (result === false) throw new AccessDeniedError(context.pathname);
+				if (typeof result === "string") return void this.go(result, { isRedirect: true });
+			}
 			this._context = context;
-			outlet = findOutletOrThrow(this._rootElement);
-			let title = void 0;
-			let content = null;
-			if (routes.length === 0) throw new NotFoundError(context.href);
+			window.dispatchEvent(new RouteBeginEvent(context));
 			for (const route of routes) {
 				if (this._requestID !== requestID) return;
+				context.metadata = {
+					...context.metadata,
+					...route.metadata
+				};
+				if (route.enter && this._tracker.enter(route)) {
+					const result = await route.enter(context);
+					if (this._requestID !== requestID) return;
+					if (result === false) throw new AccessDeniedError(context.pathname);
+					if (typeof result === "string") return void this.go(result, { isRedirect: true });
+				}
 				if (!route.render) continue;
+				let content;
 				try {
 					content = await route.render(context);
 					if (content === false || content === void 0 || content === null) throw new Error("Failed to load content for the route.");
-				} catch (LoadError) {
-					throw new ContentLoadError(LoadError);
+				} catch (e) {
+					throw new ContentLoadError(e);
 				}
 				try {
-					outlet.render({
+					outlet.render(content, {
 						id: route.id,
-						value: content,
 						force: route.force
 					});
-				} catch (renderError) {
-					throw new ContentRenderError(renderError);
+				} catch (e) {
+					throw new ContentRenderError(e);
 				}
-				outlet = findOutlet(outlet) || outlet;
+				outlet = findOutlet(outlet, true) || outlet;
 				title = route.title || title;
 			}
-			document.title = title || document.title;
 			window.dispatchEvent(new RouteDoneEvent(context));
 		} catch (error) {
 			const routeError = error instanceof RouteError ? error : new RouteError(error?.status || error?.code || "UNKNOWN_ERROR", error?.message || "An unexpected error occurred", error);
 			window.dispatchEvent(new RouteErrorEvent(context, routeError));
-			console.error("Routing error:", routeError.original);
+			console.error("Routing error:", routeError.original || routeError);
 			try {
-				if (this._fallback && this._fallback.render && outlet) {
-					const fallbackContent = await this._fallback.render({
-						...context,
-						error: routeError
-					});
-					outlet.render({
-						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({
-						id: "#error",
-						value: errorContent,
-						force: true
-					});
-					else {
-						document.body.innerHTML = "";
-						document.body.appendChild(errorContent);
-					}
+				const content = this._fallback?.render ? await this._fallback.render({
+					...context,
+					error: routeError
+				}) : new UErrorPage(routeError);
+				if (outlet) outlet.render(content, {
+					id: getRandomID(),
+					force: true
+				});
+				else {
+					document.body.innerHTML = "";
+					document.body.appendChild(content instanceof Node ? content : new UErrorPage(routeError));
 				}
+				title = this._fallback?.title || routeError.message || "Error";
 			} catch (pageError) {
 				console.error("Failed to render error component:", pageError);
 				console.error("Original error:", routeError.original || routeError);
 			}
+		} finally {
+			document.title = title || document.title;
 		}
 	}
 };
 //#endregion
-export { ContentLoadError, ContentRenderError, NotFoundError, OutletMissingError, RouteBeginEvent, RouteDoneEvent, RouteError, RouteErrorEvent, RouteProgressEvent, Router, ULink, UOutlet };
+export { AccessDeniedError, ContentLoadError, ContentRenderError, NotFoundError, OutletMissingError, RouteBeginEvent, RouteDoneEvent, RouteError, RouteErrorEvent, RouteProgressEvent, Router, ULink, UOutlet };

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.9.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.9.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();
+```