interface State<P extends Params = Params> {
  name: string;
  params: P;
  path: string;
  transition: TransitionMeta;
  context: StateContext & Record<string, unknown>;
}

// Empty at baseline — extended by plugins
interface StateContext {}

// In @real-router/navigation-plugin
declare module "@real-router/types" {
  interface StateContext {
    navigation?: NavigationMeta;
  }
}

// In @real-router/browser-plugin
declare module "@real-router/types" {
  interface StateContext {
    browser?: BrowserContext;
  }
}

// In @real-router/memory-plugin
declare module "@real-router/types" {
  interface StateContext {
    memory?: MemoryContext;
  }
}

// In @real-router/persistent-params-plugin
declare module "@real-router/types" {
  interface StateContext {
    persistentParams?: Params;
  }
}

// In @real-router/ssr-data-plugin
declare module "@real-router/types" {
  interface StateContext {
    data?: unknown;
  }
}

import "@real-router/navigation-plugin";
import "@real-router/memory-plugin";

router.subscribe((state) => {
  state.context.navigation?.direction; // "forward" | "back" | "unknown" -- typed
  state.context.memory?.historyIndex;  // number -- typed
});

// React example
import { useRoute } from "@real-router/react";
import "@real-router/navigation-plugin"; // activate type augmentation

function TransitionInfo() {
  const { route } = useRoute();

  const navContext = route?.context.navigation;
  if (!navContext) return null;

  return (
    <div>
      <p>Navigation type: {navContext.navigationType}</p>
      <p>Direction: {navContext.direction}</p>
      <p>User initiated: {navContext.userInitiated ? "yes" : "no"}</p>
    </div>
  );
}

interface Params {
  [key: string]:
    | string
    | string[]
    | number
    | number[]
    | boolean
    | boolean[]
    | Params
    | Params[]
    | Record<string, string | number | boolean>
    | null
    | undefined;
}

interface TransitionMeta {
  phase: TransitionPhase; // "deactivating" | "activating"
  reason: TransitionReason; // "success" | "blocked" | "cancelled" | "error"
  reload?: boolean; // true after navigate(..., { reload: true })
  redirected?: boolean; // true if navigation was redirected via forwardTo
  from?: string; // Previous route name (undefined on first navigation)
  blocker?: string; // Reserved — not yet populated by core
  segments: {
    deactivated: string[]; // Route segments that were deactivated (frozen)
    activated: string[]; // Route segments that were activated (frozen)
    intersection: string; // Common ancestor segment
  };
}

const state = await router.navigate("users.profile", { id: "123" });
console.log(state.transition);
// {
//   phase: "activating",
//   from: "home",
//   reason: "success",
//   segments: {
//     deactivated: ["home"],
//     activated: ["users", "users.profile"],
//     intersection: ""
//   }
// }

router.subscribe((state) => {
  const { transition } = state;

  if (transition.from !== state.name) {
    // Route entry — user came from a different route (or this is the first navigation)
    // Full initialization: reset scroll, fetch initial data
  } else {
    // Parameter change — same route, different params
    // Incremental update: re-fetch with new filters/sorting
  }
});

const routes = [
  { name: "services.catalog", path: "/catalog?q&sort&dir" },
];

router.subscribe((state) => {
  if (state.name !== "services.catalog") return;

  if (state.transition.from !== "services.catalog") {
    // Entered from another route — full page setup
    initScrollPosition();
    loadServices(state.params);
  } else {
    // Filters or sorting changed — just update the table
    loadServices(state.params);
  }
});

interface SimpleState<P extends Params = Params> {
  name: string;
  params: P;
}

import { createRouter } from "@real-router/core";

const router = createRouter(routes);
await router.start("/users/123");

const state = router.getState();
console.log(state.name); // "users.profile"
console.log(state.params); // { id: "123" }
console.log(state.path); // "/users/123"

import { useRoute } from "@real-router/react";

function CurrentPage() {
  const { route } = useRoute();

  if (!route) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>Current Route: {route.name}</h1>
      <p>Path: {route.path}</p>
      <pre>{JSON.stringify(route.params, null, 2)}</pre>
    </div>
  );
}

import type { State } from "@real-router/core";

interface UserParams {
  id: string;
  tab?: string;
}

// State objects are created by the router, not manually.
// Use the generic parameter for type-safe access:
router.subscribe((state: State<UserParams>) => {
  state.params.id;  // string
  state.params.tab; // string | undefined
});

import { UNKNOWN_ROUTE } from "@real-router/core";

const state = router.getState();
if (state?.name === UNKNOWN_ROUTE) {
  console.log(state.path); // "/items/10000" — the URL that failed
  console.log(state.params); // {} — always empty
  console.log(state.transition.from); // "items.view" — where the user was
}