@iyulab/router 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.9.1] - 2026-04-08
+
+### Fixed
+- Redirect cycle detection no longer triggers false positives on initial navigation — `visit()` check is now skipped for the first `go()` call and only applied within redirect chains (`isRedirect: true`)
+
+## [0.9.0] - 2026-04-08
+
+### Added
+- `NavigateOptions` — new optional second parameter for `go()` with `isRedirect`, `replace`, and `state` fields
+- `replace` option — navigate without pushing a new browser history entry (`replaceState`)
+- `state` option — attach custom state object to `history.pushState` / `replaceState`
+- `AccessDeniedError` — new error class (HTTP 403) thrown when an `enter` guard returns `false`; renders an error page with `ACCESS_DENIED` code
+- Redirect cycle detection — logs an error and halts routing if the same URL is visited more than once within a single navigation chain
+- `UErrorPage` now accepts an optional `RouteError` in its constructor for direct instantiation
+
+### Changed
+- **Breaking:** `enter` returning `false` now throws `AccessDeniedError` and renders a 403 error page instead of silently aborting navigation
+- Redirect navigations (`isRedirect: true`) use `replaceState` — intermediate redirect URLs are no longer pushed onto the browser history stack
+- Global `enter` guard is skipped on redirect hops — runs only once per user-initiated navigation
+- Route-level `enter` hooks are deduplicated within a redirect chain — each route's `enter` executes at most once per navigation cycle
+- `document.title` is now updated in a `finally` block — title is set regardless of whether routing succeeds or fails
+
 ## [0.8.0] - 2026-04-08
 
 ### Added

package/dist/index.d.ts

@@ -3,6 +3,13 @@ import { LitElement } from 'lit';
 import { PropertyValues } from 'lit';
 import { TemplateResult } from 'lit-html';
 
+/**
+ * enter 가드가 false를 반환하여 접근이 거부되었을 때 발생하는 에러
+ */
+export declare class AccessDeniedError extends RouteError {
+    constructor(path: string);
+}
+
 /**
  * 공통 라우트 속성
  */
@@ -135,6 +142,32 @@ declare interface IndexRouteConfig extends BaseRouteConfig {
     index: true;
 }
 
+/**
+ * go() 메서드에 전달할 네비게이션 옵션
+ */
+export declare interface NavigateOptions {
+    /**
+     * 리다이렉트로 인한 네비게이션 여부.
+     * - `true`이면 히스토리에 새 항목을 추가하지 않고 현재 항목을 교체합니다(replaceState).
+     * - 뒤로가기 버튼이 리다이렉트 경유지를 건너뛰게 됩니다.
+     * - 리다이렉트 사이클 감지에 사용됩니다.
+     * @default false
+     */
+    isRedirect?: boolean;
+    /**
+     * 히스토리에 새 항목을 추가하지 않고 현재 항목을 교체합니다(replaceState).
+     * - `isRedirect`와 달리 리다이렉트 체인 추적에는 영향을 주지 않습니다.
+     * @default false
+     */
+    replace?: boolean;
+    /**
+     * pushState / replaceState 호출 시 함께 저장할 커스텀 상태 객체.
+     * - `history.state`로 다시 읽을 수 있습니다.
+     * @example { from: '/login', referrer: 'email-link' }
+     */
+    state?: Record<string, unknown>;
+}
+
 declare interface NonIndexRouteConfig extends BaseRouteConfig {
     /**
      * 인덱스 라우트가 아님을 나타냅니다.
@@ -326,6 +359,7 @@ export declare class Router {
     private readonly _routes;
     private readonly _fallback?;
     private readonly _enter?;
+    private readonly _tracker;
     /** 현재 라우팅 요청 ID */
     private _requestID?;
     /** 현재 라우팅 정보 */
@@ -342,8 +376,9 @@ export declare class Router {
     /**
      * 지정한 경로의 클라이언트 라우팅을 수행합니다. 상대경로일 경우 basepath와 조합되어 이동합니다.
      * @param href 이동할 경로
+     * @param options 네비게이션 옵션
      */
-    go(href: string): Promise<undefined>;
+    go(href: string, options?: NavigateOptions): Promise<undefined>;
     /** 브라우저 히스토리 이벤트가 발생시 라우팅 처리 */
     private handleWindowPopstate;
     /** 클릭 이벤트에서 라우터로 처리할 앵커를 찾아 클라이언트 라우팅 수행 */

package/dist/index.js

@@ -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
 /**
@@ -323,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 {
@@ -383,101 +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 (options?.isRedirect && 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._enter) {
+			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.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 (typeof result === "string") return void this.go(result);
-				if (result === false) return;
+				if (result === false) throw new AccessDeniedError(context.pathname);
+				if (typeof result === "string") return void this.go(result, { isRedirect: true });
 			}
-			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.metadata) Object.assign(mergedMeta, route.metadata);
-			context.metadata = mergedMeta;
 			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;
-				if (route.enter) {
+				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 (typeof result === "string") return void this.go(result);
-					if (result === false) 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(content, {
 						id: route.id,
 						force: route.force
 					});
-				} catch (renderError) {
-					throw new ContentRenderError(renderError);
+				} catch (e) {
+					throw new ContentRenderError(e);
 				}
 				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(fallbackContent, {
-						id: "#fallback",
-						force: true
-					});
-					document.title = this._fallback.title || document.title;
-				} else {
-					const errorContent = new UErrorPage();
-					errorContent.error = error;
-					if (outlet) outlet.render(errorContent, {
-						id: "#error",
-						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/package.json

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

package/skills/iyulab-router/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Browser environments only (requires URLPattern and History API)
 metadata:
   author: iyulab
-  version: "0.8.0"
+  version: "0.9.1"
 ---
 
 # @iyulab/router