soseki 0.0.4 → 0.0.6

package/src/engines/navigation-api-engine.ts

@@ -1,96 +1,92 @@
-import actionIdRegistry from "../core/_action-id-registry.js";
-import createHtmlFormElementFormFormData from "../core/_create-html-form-element-form-form-data.js";
+import unreachable from "../core/_unreachable.js";
 import * as v from "../core/_valibot.js";
-import { ACTION_ID_FORM_DATA_NAME } from "../core/constants.js";
 import { NavigationApiNotSupportedError } from "../core/errors.js";
 import expectHistoryEntry from "../core/expect-history-entry.js";
-import HistoryEntryIdSchema, { type HistoryEntryId } from "../core/history-entry-id-schema.js";
+import createHtmlFormElementFormFormData from "../core/form-data-to-html-form-element.js";
+import type { HistoryEntryId } from "../core/history-entry-id-schema.js";
+import HistoryEntryIdSchema from "../core/history-entry-id-schema.js";
 import HistoryEntryUrlSchema from "../core/history-entry-url-schema.js";
 import initLoaders from "../core/init-loaders.js";
 import matchRoutes from "../core/match-routes.js";
-import type { IAction } from "../core/route.types.js";
-import startActions from "../core/start-actions.js";
+import RoutePath from "../core/route-path.js";
+import startAction from "../core/start-action.js";
 import startLoaders from "../core/start-loaders.js";
-import type {
-  IEngine,
-  InitEngineArgs,
-  NavigateArgs,
-  RouterState,
-  StartEngineArgs,
-  SubmitArgs,
-} from "./engine.types.js";
+import type { IEngine } from "./engine.types.js";
 
 /**
- * Navigation API を利用してルーティングの基幹処理を行うエンジンクラスです。
+ * モダンブラウザーに搭載されている標準の `Navigation API` を活用し、クライアントサイドにおける高度な SPA ルーティングを制御するエンジンクラスです。
  */
 export default class NavigationApiEngine implements IEngine {
   /**
-   * Navigation API の実体です。
+   * ブラウザー標準の `navigation` オブジェクトへの参照を保持します。
    */
-  private nav: Navigation;
+  private navigation: Navigation;
 
   /**
-   * すでにイベントリスナーを登録済みのエントリー ID を管理するセットです。
+   * メモリーリークを防ぐため、すでに dispose リスナーを登録済みの履歴エントリー ID を追跡するセットです。
    */
   private subscribedEntryIds: Set<HistoryEntryId>;
 
   /**
-   * 実行中のナビゲーションをキャンセルするためのコントローラーです。
+   * 連続して発生した画面遷移を適切にキャンセルするための、最新ナビゲーション用の中断コントローラーです。
    */
   private navAbortController: AbortController | null;
 
   /**
-   * NavigationApiEngine クラスの新しいインスタンスを初期化します。
+   * `NavigationApiEngine` クラスのインスタンスを初期化します。
+   *
+   * 実行環境が `Navigation API` をサポートしていない場合はエラーを投げます。
    */
   public constructor() {
-    let nav: Navigation | undefined;
-    try {
-      nav = navigation;
-    } catch {
+    let navigation_: Navigation | undefined;
+
+    // グローバル環境または window オブジェクトから navigation インスタンスの回収を試みます。
+    for (const getNav of [() => navigation, () => window.navigation]) {
       try {
-        nav = window.navigation;
+        navigation_ = getNav();
+        if (typeof navigation_ !== "undefined") {
+          break;
+        }
       } catch {}
     }
-    // オブジェクトの存在確認を行い、非対応環境なら例外を投げます。
-    if (!(nav && typeof nav === "object")) {
+
+    // オブジェクトとして存在しない場合はサポート外の環境とみなします。
+    if (typeof navigation_ !== "object") {
       throw new NavigationApiNotSupportedError();
     }
 
-    this.nav = nav;
+    this.navigation = navigation_;
     this.subscribedEntryIds = new Set();
     this.navAbortController = null;
   }
 
   /**
-   * 現在のロケーションに基づいた初期のルーター状態を生成します。
+   * 現在のページ URL に基づき、ルーターの初期状態を構築・登録します。
    *
-   * @param args 状態生成に必要なルート定義やデータ保持用のマップです。
-   * @returns 生成されたルーター状態、またはマッチしなかった場合は `null` を返します。
+   * @param args ルート定義配列、共通データストア、初期化用のアボートシグナルを含むオブジェクトです。
+   * @returns 構築された初期の `RouterState`。適合するルートがないか、履歴が無い場合は `null` を返します。
    */
-  public init(args: InitEngineArgs): RouterState | null {
-    const currentEntry = expectHistoryEntry(this.nav.currentEntry);
+  init(args: IEngine.InitArgs): IEngine.InitReturn {
+    const currentEntry = expectHistoryEntry(this.navigation.currentEntry);
     if (!currentEntry) {
       return null;
     }
 
-    const {
-      routes,
-      getSignal,
-      loaderDataStore,
-    } = args;
-    const currentRoutes = matchRoutes(routes, currentEntry.url.pathname);
+    const { routes, getSignal, loaderDataStore } = args;
+    const currentRoutes = matchRoutes(routes, currentEntry.url);
     if (!currentRoutes) {
       return null;
     }
 
-    // 非同期でローダーの初期化を開始します。
-    initLoaders({
-      entry: currentEntry,
-      routes: currentRoutes,
+    // 初期表示に必要なすべてのローダーを一斉に並行起動します。
+    const dataMap = initLoaders(currentRoutes, {
+      url: currentEntry.url,
       signal: getSignal(),
-      dataStore: loaderDataStore,
     });
 
+    // 起動したローダーの結果（NinjaPromise）のマップを、現在の履歴 ID をキーとしてキャッシュします。
+    loaderDataStore.set(currentEntry.id, dataMap);
+
     return {
       entry: currentEntry,
       routes: currentRoutes,
@@ -98,169 +94,244 @@ export default class NavigationApiEngine implements IEngine {
   }
 
   /**
-   * エンジンの動作を開始し、ナビゲーションイベントの監視を行います。
+   * ブラウザーの継続的なナビゲーションイベント（リンククリック、フォーム送信、履歴移動）の監視を開始します。
    *
-   * @param args エンジンの開始に必要な設定とデータ管理用のオブジェクトです。
+   * @param args ルート配列、UI側への状態反映関数、各種ストア、シグナル取得関数を含むオブジェクトです。
    */
-  public start(args: StartEngineArgs): void {
-    const {
-      routes,
-      update,
-      getSignal,
-      actionDataStore,
-      loaderDataStore,
-    } = args;
+  start(args: IEngine.StartArgs): IEngine.StartReturn {
+    const { routes, update, getSignal, actionDataStore, loaderDataStore } = args;
 
     /**
-     * ナビゲーションが発生した際のハンドラーです。
-     *
-     * @param event ナビゲーションイベントです。
+     * ユーザーのアクションによって発生したすべての遷移要求をインターセプトして処理する、ルーティングの中枢ハンドラーです。
      */
     const handleNavigate = (event: NavigateEvent): void => {
-      // インターセプトできない場合や、ハッシュ変更、ダウンロードリクエストの場合は処理をスキップします。
+      // 処理すべきでない通常のブラウザー固有のナビゲーション（ハッシュ変更、ファイルのダウンロードなど）は、
+      // 標準の挙動を妨げないようにインターセプトせず即座にスルーします。
       // 参照: https://developer.mozilla.org/docs/Web/API/Navigation_API#handling_a_navigation_using_intercept
       if (
-        !event.isTrusted
-        || !event.canIntercept
-        || event.hashChange
-        || event.downloadRequest !== null
+        !event.isTrusted ||
+        !event.canIntercept ||
+        event.hashChange ||
+        event.downloadRequest !== null
       ) {
         return;
       }
 
-      const currentEntry = expectHistoryEntry(this.nav.currentEntry);
+      const currentEntry = expectHistoryEntry(this.navigation.currentEntry);
       if (!currentEntry) {
+        // 現在のエントリーが存在しない場合は、ルーターを未マッチ状態（null）にリセットして制御をブラウザーに返します。
         event.intercept({
           async handler() {
             update(null);
           },
         });
+
         return;
       }
 
+      // 移動先の URL を検証し、適合するルート定義があるかを探索します。
       const destUrl = v.expect(HistoryEntryUrlSchema(), event.destination.url);
-      const destRoutes = matchRoutes(routes, destUrl.pathname);
+      const destRoutes = matchRoutes(routes, destUrl);
       if (!destRoutes) {
+        // 移動先のルート定義が見つからない場合は、ルーターを未マッチ状態（null）にリセットして制御をブラウザーに返します。
         event.intercept({
           async handler() {
             update(null);
           },
         });
+
         return;
       }
 
-      // 進行中の古い処理をキャンセルし、新しいコントローラーを生成します。
+      // 前回の遷移から短時間で遷移する場合を考慮し、進行中だった以前の古い非同期処理をすべて安全に中断します。
       this.navAbortController?.abort();
-      const { signal } = this.navAbortController = new AbortController();
+      this.navAbortController = new AbortController();
+      const { signal } = this.navAbortController;
       const { formData } = event;
       const prevEntryInHandler = currentEntry;
+
+      // 分岐 A: フォームデータが伴う場合 ＝ データ変更要求（HTTP POST / Action 契機）
       if (formData) {
         const { sourceElement } = event;
+
+        // submit メソッドによってプログラムから動的生成されたフォーム要素であれば、用済みのため DOM から削除します。
         if (sourceElement?.hasAttribute("data-sosekisubmit")) {
           document.body.removeChild(sourceElement);
         }
 
-        let redirectUrl = new URL(currentEntry.url.href);
-        let actionResultMap: ReadonlyMap<IAction, unknown> | undefined;
-        event.intercept({
-          precommitHandler: async controller => {
-            const entry = {
-              id: currentEntry.id,
-              url: destUrl,
-            };
-            const waitForComplete = startActions({
-              entry,
-              routes: destRoutes,
-              signal,
-              formData,
-              dataStore: actionDataStore,
-            });
-            if (!waitForComplete) {
-              return;
+        /**
+         * A-1: URL が書き換わる直前の段階で割り込んでアクション関数を実行するハンドラーです。
+         */
+        const precommitHandler = async (controller: NavigationPrecommitController) => {
+          const action = startAction(destRoutes, {
+            url: destUrl,
+            signal,
+            formData,
+          });
+          if (!action) {
+            return;
+          }
+
+          // アクションの実行状態を現在の履歴 ID に紐づけてストアへ保存します。
+          actionDataStore
+            .getOrInsertComputed(currentEntry.id, () => new Map())
+            .set(action.func, action.data);
+
+          // アクションの開始に伴い、UI 層へローディング状態などの再描画を伝播します。
+          update();
+
+          // 全アクションの処理が完了するまで待機します。
+          const actionResponse = await action.idle();
+          const redirectUrl = new URL(currentEntry.url.href);
+
+          switch (action.data.status) {
+            case "rejected": {
+              // アクションがエラーで失敗した場合は、URL を変更せず現在の元のページに強制リダイレクトさせます。
+              const { pathname, search, hash } = currentEntry.url;
+              controller.redirect(pathname + search + hash);
+
+              break;
             }
 
-            update();
-            const {
-              redirect = currentEntry.url.pathname,
-              resultMap,
-            } = await waitForComplete();
-            actionResultMap = resultMap;
-            redirectUrl.pathname = redirect;
-            controller.redirect(redirect);
-          },
-          handler: async () => {
-            if (!actionResultMap) {
-              return;
-            }
+            case "fulfilled": {
+              // アクションが正常終了した場合、返り値にリダイレクト指示が含まれていればその目的地へ遷移させます。
+              // リダイレクトがなければそのまま本来の目的地へとブラウザーのコミット先を書き換えます。
+              const { redirectTo = currentEntry.url } = actionResponse;
+              const { pathname, search, hash } = redirectTo;
+              controller.redirect(pathname + search + hash);
 
-            const currentEntry = expectHistoryEntry(this.nav.currentEntry);
-            if (!currentEntry) {
-              update(null);
-              return;
-            }
-            if (currentEntry.url.href !== redirectUrl.href) {
-              return;
-            }
+              redirectUrl.pathname = pathname;
+              redirectUrl.search = search;
+              redirectUrl.hash = hash;
 
-            const currentRoutes = matchRoutes(routes, currentEntry.url.pathname);
-            if (!currentRoutes) {
-              update(null);
-              return;
+              break;
             }
 
-            const prevEntry = prevEntryInHandler;
-            const prevRoutes = matchRoutes(routes, prevEntry.url.pathname);
-            const waitForComplete = startLoaders({
+            default:
+              unreachable(action.data.status as never);
+          }
+
+          // 次の描画確定フェーズへコンテキスト情報を引き継ぎます。
+          return {
+            action: action.func,
+            actionData: action.data,
+            redirectUrl,
+          };
+        };
+
+        /**
+         * A-2: アクションが完了し、ブラウザーの URL コミットが確定した後に画面表示を同期させるハンドラーです。
+         */
+        const handler = async (args: Awaited<ReturnType<typeof precommitHandler>>) => {
+          if (!args) {
+            return;
+          }
+
+          const { action, actionData, redirectUrl } = args;
+
+          // 履歴エントリーを再度取得します。
+          const currentEntry = expectHistoryEntry(this.navigation.currentEntry);
+          if (!currentEntry) {
+            // 現在のエントリーが存在しない場合は、ルーターを未マッチ状態（null）にリセットして制御をブラウザーに返します。
+            update(null);
+            return;
+          }
+
+          // コミットされた実際のブラウザー URL が、想定しているリダイレクト先と一致しない場合は処理を中断します。
+          if (currentEntry.url.href !== redirectUrl.href) {
+            return;
+          }
+
+          // 確定した新しい履歴 ID に改めてアクション結果をキャッシュします。
+          actionDataStore
+            .getOrInsertComputed(currentEntry.id, () => new Map())
+            .set(action, actionData);
+
+          const currentRoutes = matchRoutes(routes, currentEntry.url);
+          if (!currentRoutes) {
+            // 現在のルート定義が見つからない場合は、ルーターを未マッチ状態（null）にリセットして制御をブラウザーに返します。
+            update(null);
+            return;
+          }
+
+          // アクションの処理結果を反映させるために、該当するルートのローダーを実行します。
+          const prevEntry = prevEntryInHandler;
+          const prevRoutes = matchRoutes(routes, prevEntry.url);
+          const startedLoaders = startLoaders(
+            {
               signal,
-              formData,
               prevEntry,
               prevRoutes,
               currentEntry,
               currentRoutes,
-              actionResultMap,
-              actionDataStore,
               loaderDataStore,
-            });
-            update({
-              entry: currentEntry,
-              routes: currentRoutes,
-            });
-            if (!waitForComplete) {
-              return;
-            }
-
-            await waitForComplete();
+            },
+            {
+              formData,
+              actionData,
+            },
+          );
+
+          // 最新の確定状態を UI に通知して画面を再描画します。ローダーの結果の中には実行中のものもありますが、それらの待機処理（描画）は各コンポーネントに任せます。
+          update({
+            entry: currentEntry,
+            routes: currentRoutes,
+          });
+
+          // 全ローダーの完了を待機します。ここで待機することで、全ローダーの実行が完了するまでブラウザーのタブにはローディングスピーナーが表示されます。
+          await startedLoaders?.idle();
+        };
+
+        // Navigation API のインターセプト機構に、二段階の処理をバインドします。
+        let precommitResult: Awaited<ReturnType<typeof precommitHandler>>;
+        event.intercept({
+          async precommitHandler(controller) {
+            precommitResult = await precommitHandler(controller);
+          },
+          async handler() {
+            await handler(precommitResult);
           },
         });
       } else {
-        event.intercept({
-          handler: async () => {
-            const currentEntry = expectHistoryEntry(this.nav.currentEntry);
-            if (!currentEntry) {
-              update(null);
-              return;
-            }
-            if (currentEntry.url.href !== destUrl.href) {
-              return;
-            }
+        // 分岐 B: フォームデータがない場合 ＝ 通常の画面遷移（HTTP GET / リンククリック・戻る進む契機）
+        const handler = async () => {
+          const currentEntry = expectHistoryEntry(this.navigation.currentEntry);
+          if (!currentEntry) {
+            update(null);
+            return;
+          }
+          // 同期がズレている場合はガードします。
+          if (currentEntry.url.href !== destUrl.href) {
+            return;
+          }
+
+          const prevEntry = prevEntryInHandler;
+          const prevRoutes = matchRoutes(routes, prevEntry.url);
+          const currentRoutes = destRoutes;
+
+          // キャッシュの再利用判定を含めて、移動先のローダー関数群を精査・起動します。
+          const startedLoaders = startLoaders({
+            signal,
+            prevEntry,
+            prevRoutes,
+            currentEntry,
+            currentRoutes,
+            loaderDataStore,
+          });
+
+          // 最新の確定状態を UI に通知して画面を再描画します。ローダーの結果の中には実行中のものもありますが、それらの待機処理（描画）は各コンポーネントに任せます。
+          update({
+            entry: currentEntry,
+            routes: currentRoutes,
+          });
+
+          // 全ローダーの完了を待機します。ここで待機することで、全ローダーの実行が完了するまでブラウザーのタブにはローディングスピーナーが表示されます。
+          await startedLoaders?.idle();
+        };
 
-            const prevEntry = prevEntryInHandler;
-            const prevRoutes = matchRoutes(routes, prevEntry.url.pathname);
-            const currentRoutes = destRoutes;
-            const waitForComplete = startLoaders({
-              signal,
-              prevEntry,
-              prevRoutes,
-              currentEntry,
-              currentRoutes,
-              actionDataStore,
-              loaderDataStore,
-            });
-            update({
-              entry: currentEntry,
-              routes: currentRoutes,
-            });
-            await waitForComplete?.();
+        event.intercept({
+          async handler() {
+            await handler();
           },
         });
       }
@@ -268,23 +339,24 @@ export default class NavigationApiEngine implements IEngine {
 
     const signal = getSignal();
 
-    const handleAbort = () => {
+    // 外部からルーター全体の監視終了シグナルを受け取った際、中断処理を連動させます。
+    const handleAbort = (): void => {
       this.navAbortController?.abort();
       this.navAbortController = null;
     };
     signal.addEventListener("abort", handleAbort, { once: true });
 
-    this.nav.addEventListener("navigate", handleNavigate, { signal });
-    // this.nav.addEventListener("navigateerror", console.error, { signal });
+    // Navigation API の navigate イベントの購読を開始します。
+    this.navigation.addEventListener("navigate", handleNavigate, { signal });
 
-    // 既存のエントリーに対して dispose リスナーを登録し、メモリーを解放します。
-    for (const entry of this.nav.entries()) {
+    // セッション履歴から溢れて破棄された古い履歴エントリーのデータ（アクション・ローダーのキャッシュ）を自動削除します。
+    for (const entry of this.navigation.entries()) {
       const entryId = v.expect(HistoryEntryIdSchema(), entry.id);
       if (this.subscribedEntryIds.has(entryId)) {
         continue;
       }
 
-      const handleDispose = () => {
+      const handleDispose = (): void => {
         this.subscribedEntryIds.delete(entryId);
         actionDataStore.delete(entryId);
         loaderDataStore.delete(entryId);
@@ -293,11 +365,9 @@ export default class NavigationApiEngine implements IEngine {
       this.subscribedEntryIds.add(entryId);
     }
 
-    /**
-     * 現在のエントリーが変更された際のハンドラーです。
-     */
-    const handleCurrentEntryChange = () => {
-      const currentEntry = expectHistoryEntry(this.nav.currentEntry);
+    // ナビゲーションの進行に伴い、新しく生成される履歴エントリーに対しても、動的に破棄イベントの監視網を広げます。
+    const handleCurrentEntryChange = (): void => {
+      const currentEntry = expectHistoryEntry(this.navigation.currentEntry);
       if (!currentEntry) {
         return;
       }
@@ -305,102 +375,131 @@ export default class NavigationApiEngine implements IEngine {
         return;
       }
 
-      const handleDispose = () => {
+      const handleDispose = (): void => {
         this.subscribedEntryIds.delete(currentEntry.id);
         actionDataStore.delete(currentEntry.id);
         loaderDataStore.delete(currentEntry.id);
       };
-      this.nav.currentEntry!.addEventListener("dispose", handleDispose, { signal });
+      this.navigation.currentEntry!.addEventListener("dispose", handleDispose, { signal });
       this.subscribedEntryIds.add(currentEntry.id);
     };
-    this.nav.addEventListener("currententrychange", handleCurrentEntryChange, { signal });
+    this.navigation.addEventListener("currententrychange", handleCurrentEntryChange, { signal });
   }
 
   /**
-   * フォームデータやクエリーパラメーターを送信します。
+   * フォームデータまたはクエリーパラメータを、ブラウザーの Navigation API のライフサイクルに載せて命令的に送信します。
    *
-   * @param args 送信内容と送信先を含む引数です。
+   * @param args 送信データの種類に応じたサブミット引数です。
    */
-  public submit(args: SubmitArgs): void {
-    if ("actionId" in args) {
-      const {
-        target,
-        action,
-        actionId: actionFunction,
-      } = args;
-      const form = createHtmlFormElementFormFormData(target);
-      const actionId = actionFunction && actionIdRegistry.set(actionFunction);
-      if (actionId !== undefined) {
-        const input = document.createElement("input");
-        input.type = "hidden";
-        input.name = ACTION_ID_FORM_DATA_NAME;
-        input.value = actionId;
+  submit(args: IEngine.SubmitArgs): void {
+    switch (args.type) {
+      case "FORM_DATA": {
+        const { action, target } = args;
+        const form = createHtmlFormElementFormFormData(target);
+        form.method = "POST";
+        form.action = action;
+        form.enctype = "multipart/form-data";
+        form.dataset["sosekisubmit"] = ""; // 後で削除できるように目印を付与します。
+
+        // 実際のフォーム送信を行うために DOM へ一時配置して実行します。
+        // ハンドラーがこの要素を使用した後に DOM から削除します。
+        document.body.appendChild(form);
+        form.submit();
+
+        break;
       }
 
-      form.method = "POST";
-      form.action = action;
-      form.enctype = "multipart/form-data";
-      form.dataset["sosekisubmit"] = "";
-      document.body.appendChild(form);
-      form.submit();
-    } else {
-      const {
-        target,
-        action,
-        history,
-      } = args;
-      const u = new URL("x://y" + action);
-      u.search = target.toString();
-      this.navigate({
-        to: u.href.slice("x://y".length),
-        history,
-      });
+      case "URL_SEARCH_PARAMS": {
+        const { action, target, history } = args;
+        const path = new RoutePath(action);
+        path.search = target.toString();
+
+        // Navigation API を用いて、クエリーが上書きされた新しいアドレスへ遷移させます。
+        this.navigation.navigate(path.toString(), { history });
+
+        break;
+      }
+
+      default:
+        unreachable(args);
     }
   }
 
   /**
-   * 指定されたパスへナビゲートします。
+   * 命令的なページ遷移を処理します。
    *
-   * @param args 遷移先と遷移オプションを含む引数です。
+   * @param args 遷移タイプに応じたナビゲーション引数です。
    */
-  public navigate(args: NavigateArgs): void {
-    if ("delta" in args) {
-      const currentEntry = expectHistoryEntry(this.nav.currentEntry);
-      if (!currentEntry) {
-        return;
-      }
+  navigate(args: IEngine.NavigateArgs): void {
+    switch (args.type) {
+      case "LINK": {
+        const { to, history } = args;
+        switch (to.type) {
+          case "PATH": {
+            // 完全なパス文字列の余分なスラッシュなどをエンコードして直接遷移します。
+
+            const path = RoutePath.encode(to.path);
+            this.navigation.navigate(path, { history });
+
+            break;
+          }
+
+          case "PARTIAL": {
+            // 現在のロケーション情報をベースに、指定されたパーツ（パス名、クエリー、ハッシュのみなど）を部分的にパッチ（上書き）したマージ URL を算出します。
+
+            const currentPath = new RoutePath(window.location);
+            const nextPath = new RoutePath(window.location);
+            if (typeof to.pathname === "string") {
+              nextPath.pathname = to.pathname;
+            }
+            if (typeof to.search === "string") {
+              nextPath.search = to.search;
+            }
+            if (typeof to.hash === "string") {
+              nextPath.hash = to.hash;
+            }
 
-      const { delta } = args;
-      const index = currentEntry.index + delta;
-      const entry = this.nav.entries().find(e => e.index === index);
-      if (!entry) {
-        return;
-      }
+            const nextPathString = nextPath.toString();
 
-      this.nav.traverseTo(entry.key);
-    } else {
-      const {
-        to,
-        history,
-      } = args;
-      if (typeof to === "string") {
-        this.nav.navigate(to, { history });
-      } else {
-        const { href } = location;
-        const u = new URL(href);
-        if (to.pathname !== undefined) {
-          u.pathname = to.pathname;
-        }
-        if (to.search !== undefined) {
-          u.search = to.search;
+            // 無駄な遷移履歴を作らないように、URL に実際の変化がある場合のみ navigate を実行します。
+            if (nextPathString !== currentPath.toString()) {
+              this.navigation.navigate(nextPathString, { history });
+            }
+
+            break;
+          }
+
+          default:
+            unreachable(to);
         }
-        if (to.hash !== undefined) {
-          u.hash = to.hash;
+
+        break;
+      }
+
+      case "MOVE": {
+        const currentEntry = expectHistoryEntry(this.navigation.currentEntry);
+        if (!currentEntry) {
+          return;
         }
-        if (u.href !== href) {
-          this.nav.navigate(u.href, { history });
+
+        const { delta } = args;
+
+        // 現在のインデックスから相対位置（例: -1 なら 1 つ戻る）を計算し、履歴スタックに該当するインデックスが存在するか探索します。
+        const index = currentEntry.index + delta;
+        const entry = this.navigation.entries().find((e) => e.index === index);
+        if (!entry) {
+          // スタックの限界を超える移動要求の場合は何もしません。
+          return;
         }
+
+        // Navigation API の traverseTo メソッドを使用し、一意の識別キーを指定して目的地へジャンプします。
+        this.navigation.traverseTo(entry.key);
+
+        break;
       }
+
+      default:
+        unreachable(args);
     }
   }
 }