@vkma.dev/router 0.0.0-stage → 0.1.1

package/src/core/hash-params.ts

@@ -0,0 +1,73 @@
+/**
+ * Hash payload helpers for the VK history.
+ *
+ * Two URL modes:
+ * - `hash` (default): the hash IS the location (`#/item/7?tab=x`),
+ *   TanStack-style — parity with the old `createHashRouter`.
+ * - `hash-param`: the whole router location rides in ONE hash query param
+ *   (`#?path=%2Fitem%2F7`), foreign hash params (launch params, UTM) are
+ *   preserved next to it and never leak into the router's search. The real
+ *   `location.search` — where VK puts launch params on the web platform —
+ *   is never touched. Parity with the old `createHashParamRouter`.
+ *
+ * Both read paths tolerate LEGACY deep links written by the other mode
+ * (`#/path` resolves in hash-param mode, `#?path=…` resolves in hash
+ * mode); writes always use the active mode's canonical format.
+ */
+
+export function readHashParams(win: Window): URLSearchParams {
+	return new URLSearchParams(win.location.hash.replace(/^#\?/, ""));
+}
+
+/**
+ * Router href from the document hash, tolerant to both modes:
+ * `#?path=%2Flist&x=1` → `/list` (hash-param), `#/list?x=1` → `/list?x=1`
+ * (hash), empty or foreign hash → `/`.
+ */
+export function readHrefFromHash(win: Window, pathParam: string): string {
+	const hash = win.location.hash;
+	if (hash.startsWith("#?")) {
+		return new URLSearchParams(hash.slice(2)).get(pathParam) ?? "/";
+	}
+	if (hash.startsWith("#/")) {
+		return hash.slice(1);
+	}
+	return "/";
+}
+
+/** Serialize a router href into the hash, preserving foreign params. */
+export function writeHashParams(win: Window, pathParam: string, href: string): string {
+	const params = readHashParams(win);
+	params.set(pathParam, href);
+	return `${win.location.pathname}${win.location.search}#?${params.toString()}`;
+}
+
+/** Hash content (`?…` string) for a router href — the SetLocation payload. */
+export function serializeHashPayload(win: Window, pathParam: string, href: string): string {
+	const params = readHashParams(win);
+	params.set(pathParam, href);
+	return `?${params.toString()}`;
+}
+
+/** Extract the router href from a SetLocation/ChangeFragment payload. */
+export function parseHashPayload(payload: string, pathParam: string): string {
+	if (payload.startsWith("/")) {
+		// legacy plain-hash payload (old createHashRouter hosts)
+		return payload;
+	}
+	return new URLSearchParams(payload.replace(/^\?/, "")).get(pathParam) ?? "/";
+}
+
+/** Hash-mode SetLocation payload: the hash content IS the location. */
+export function serializeHashLocation(location: {
+	pathname: string;
+	search: string;
+	hash: string;
+}): string {
+	return `${location.pathname}${location.search}${location.hash}`;
+}
+
+/** Hash-mode payload → router href (normalized to a leading slash). */
+export function parseHashLocation(payload: string): string {
+	return payload.startsWith("/") ? payload : `/${payload}`;
+}

package/src/core/loose-route.ts

@@ -0,0 +1,17 @@
+/**
+ * Loosely-typed view of a registered route. `AnyRoute`'s options bag is
+ * generic-erased (`any`), so every consumer of `router.routesById` needs
+ * the same structural recast — this owns it once.
+ */
+export interface LooseRoute {
+	options: { staticData?: { panel?: string; modal?: string } };
+	fullPath?: string;
+}
+
+/** Read a route out of the router's registered tree without the cast noise. */
+export function looseRouteOf(
+	router: { routesById: unknown },
+	routeId: string,
+): LooseRoute | undefined {
+	return (router.routesById as Record<string, LooseRoute>)[routeId];
+}

package/src/core/panels-stack.ts

@@ -0,0 +1,85 @@
+/**
+ * Mirror of the browser history stack in terms of VKUI panel ids, indexed
+ * by `location.state.__TSR_index` (the absolute position in the history
+ * stack). Replaces the old router's key-matching ViewHistory with direct
+ * indexing. Pure — the React binding gates writes on the router's
+ * `status === "idle"` (the location commit lands a render before match
+ * resolution, so a naive write records the stale panel at the new index).
+ */
+
+export interface PanelsStackState {
+	/** panel id per history index (null = unknown entry) */
+	entries: Array<string | null>;
+	/** current history index */
+	cursor: number;
+}
+
+export const initialPanelsStack = (): PanelsStackState => ({
+	entries: [],
+	cursor: -1,
+});
+
+/**
+ * @param index `location.state.__TSR_index`, or null when the history entry
+ *              carries no TanStack state (manual hash edit / foreign entry).
+ */
+export function applyLocation(
+	prev: PanelsStackState,
+	index: number | null,
+	panel: string,
+): PanelsStackState {
+	const at = index ?? prev.cursor + 1;
+
+	if (prev.cursor === -1) {
+		// init (cold start / reload / deep link): anchor at the real history
+		// index — `__TSR_index` survives reloads in history.state. Earlier
+		// slots are unknown (null) and skipped by panelsHistoryOf.
+		const filled: Array<string | null> = [];
+		for (let i = 0; i <= at; i++) {
+			filled[i] = i === at ? panel : null;
+		}
+		return { entries: filled, cursor: at };
+	}
+
+	if (at > prev.cursor) {
+		// push: truncate the forward branch, then place the panel at `at`
+		const truncated = prev.entries.slice(0, prev.cursor + 1);
+		const filled: Array<string | null> = [];
+		for (let i = 0; i <= at; i++) {
+			filled[i] = i === at ? panel : (truncated[i] ?? null);
+		}
+		return { entries: filled, cursor: at };
+	}
+
+	if (at === prev.cursor) {
+		// replace (same slot, new location)
+		const entries = [...prev.entries];
+		entries[at] = panel;
+		return { entries, cursor: at };
+	}
+
+	// pop (back/forward into a known or unknown earlier slot)
+	const filled: Array<string | null> = [];
+	for (let i = 0; i <= at; i++) {
+		filled[i] = prev.entries[i] ?? null;
+	}
+	if (filled[at] === null) {
+		filled[at] = panel;
+	}
+	return { entries: filled, cursor: at };
+}
+
+/**
+ * VKUI `View.history` prop: panels in open order. Overlay entries never
+ * reach this stack (they live in history.state, not as panels).
+ */
+export function panelsHistoryOf(state: PanelsStackState): string[] {
+	const out: string[] = [];
+	for (let i = 0; i <= state.cursor; i++) {
+		const panel = state.entries[i];
+		if (panel) {
+			out.push(panel);
+		}
+	}
+	return out;
+}

package/src/core/state-keys.ts

@@ -0,0 +1,39 @@
+/** The key the popout overlay rides under in `history.state`. */
+export const POPOUT_STATE_KEY = "vkma:popout";
+
+export interface PopoutState {
+	id: string;
+	props?: Record<string, unknown>;
+}
+
+/** The key runtime modal props ride under in `history.state`. */
+export const MODAL_STATE_KEY = "vkma:modal";
+
+export interface ModalState {
+	/** Serializable props passed via `showModal({ props })`. */
+	props?: unknown;
+}
+
+export function readModalState(state: unknown): ModalState | undefined {
+	if (state !== null && typeof state === "object" && MODAL_STATE_KEY in state) {
+		const modal = (state as Record<string, unknown>)[MODAL_STATE_KEY];
+		if (modal !== null && typeof modal === "object") {
+			return modal;
+		}
+	}
+	return undefined;
+}
+
+export function readPopoutState(state: unknown): PopoutState | undefined {
+	if (state !== null && typeof state === "object" && POPOUT_STATE_KEY in state) {
+		const popout = (state as Record<string, unknown>)[POPOUT_STATE_KEY];
+		if (
+			popout !== null &&
+			typeof popout === "object" &&
+			typeof (popout as PopoutState).id === "string"
+		) {
+			return popout as PopoutState;
+		}
+	}
+	return undefined;
+}

package/src/core/swipe-back.ts

@@ -0,0 +1,80 @@
+import type { VkBridgeLike } from "./bridge-like.ts";
+
+/**
+ * Auto swipe-back management: the native gesture
+ * (`VKWebAppEnableSwipeBack` / `VKWebAppSetSwipeSettings { history }`) is
+ * enabled while the app can go back in its own history and disabled on the
+ * first entry — where the system back must close the app. Unsupported
+ * platforms (web) answer with error code 6; that is silenced, like the old
+ * router did.
+ *
+ * Two manual layers on top of the automatic decision:
+ * - `enabled: false` is a hard opt-out — the gesture is never enabled
+ *   (an app that drives the gesture itself, or none at all);
+ * - `setOverride(boolean)` — fed by `useEnableSwipeBack` — replaces the
+ *   automatic decision while set; `null` returns to it.
+ */
+
+/** The one active manager — `useEnableSwipeBack` talks to the last created
+ * one (a mini app has exactly one history). `destroy` unregisters. */
+let activeManager: { setOverride(enabled: boolean | null): void } | null = null;
+
+/** Manual override slot behind `useEnableSwipeBack`. */
+export function setSwipeBackOverride(enabled: boolean | null): void {
+	activeManager?.setOverride(enabled);
+}
+
+export interface SwipeBackManagerOptions {
+	bridge: VkBridgeLike;
+	history: {
+		location: { state?: { __TSR_index?: number } };
+		subscribe(listener: () => void): () => void;
+	};
+	/**
+	 * Hard opt-out: the native gesture is never enabled, whatever the
+	 * history position or an override says. Default `true`.
+	 */
+	enabled?: boolean;
+}
+
+export function createSwipeBackManager(options: SwipeBackManagerOptions): {
+	destroy: () => void;
+	/** Manual override — `null` returns to the automatic decision. */
+	setOverride: (enabled: boolean | null) => void;
+} {
+	let lastEnabled: boolean | null = null;
+	let override: boolean | null = null;
+
+	const sync = (): void => {
+		const index = options.history.location.state?.__TSR_index;
+		const auto = index === undefined ? false : index > 0;
+		const enabled = options.enabled === false ? false : (override ?? auto);
+		if (enabled === lastEnabled) {
+			return;
+		}
+		lastEnabled = enabled;
+		void options.bridge.send("VKWebAppSetSwipeSettings", { history: enabled }).catch(() => {});
+		void options.bridge
+			.send(enabled ? "VKWebAppEnableSwipeBack" : "VKWebAppDisableSwipeBack")
+			.catch(() => {});
+	};
+
+	sync();
+	const unsubscribe = options.history.subscribe(sync);
+	const manager = {
+		setOverride: (enabled: boolean | null): void => {
+			override = enabled;
+			sync();
+		},
+	};
+	activeManager = manager;
+	return {
+		setOverride: manager.setOverride,
+		destroy: () => {
+			unsubscribe();
+			if (activeManager === manager) {
+				activeManager = null;
+			}
+		},
+	};
+}

package/src/core/vk-history.ts

@@ -0,0 +1,146 @@
+import { createBrowserHistory } from "@tanstack/history";
+import {
+	parseHashLocation,
+	parseHashPayload,
+	readHrefFromHash,
+	serializeHashPayload,
+	writeHashParams,
+} from "./hash-params.ts";
+
+/**
+ * VK history: the same trick TanStack's own hash history uses —
+ * `createBrowserHistory` with swapped `parseLocation`/`createHref` — so we
+ * inherit blockers with rollback, popstate classification, throttling and
+ * TSR index/key stamping.
+ *
+ * Modes (parity with the old router's three factories):
+ * - `"hash"` (default) → old `createHashRouter`: the hash IS the location
+ *   (`#/item/7?tab=x`).
+ * - `"hash-param"` → old `createHashParamRouter`: the whole router
+ *   location rides in one hash query param (`#?path=%2Fitem%2F7`), foreign
+ *   hash params (launch params, UTM) are preserved next to it, and the
+ *   real `location.search` is never touched.
+ *
+ * Deep links written by the OTHER mode resolve too (legacy tolerance).
+ * `"browser"` → pass TanStack's default history instead (omit `history`
+ * in createRouter) — old `createBrowserRouter`.
+ */
+
+export const DEFAULT_PATH_PARAM = "path";
+
+export type VkHistoryMode = "hash" | "hash-param";
+
+interface HistoryState {
+	key: string;
+	__TSR_key: string;
+	__TSR_index: number;
+}
+
+export interface VkHistoryOptions {
+	window?: Window;
+	/** Hash query param carrying the router location (hash-param mode). */
+	pathParam?: string;
+	/** URL mode. Default `"hash"`. */
+	mode?: VkHistoryMode;
+}
+
+/** The history plus the payload codecs the bridge sync layer needs. */
+export function createVkHistory(options: VkHistoryOptions = {}) {
+	const win = options.window ?? window;
+	const pathParam = options.pathParam ?? DEFAULT_PATH_PARAM;
+	const mode = options.mode ?? "hash";
+
+	let lastIndex = -1;
+
+	/**
+	 * A history entry without TanStack state (manual hash edit / foreign
+	 * pushState) gets a FRESH index = lastIndex + 1, so popstate classifies
+	 * it as FORWARD — the entry behaves like a push (an entry parsed as
+	 * index 0 would desync any parallel stack mirror).
+	 */
+	const stampMissingState = (): HistoryState => {
+		lastIndex += 1;
+		const key = Math.random().toString(36).slice(2, 8);
+		const state: HistoryState = { __TSR_index: lastIndex, key, __TSR_key: key };
+		win.history.replaceState(state, "", win.location.href);
+		return state;
+	};
+
+	const initStamp = (): HistoryState => {
+		const rawState = win.history.state as HistoryState | null;
+		if (rawState?.__TSR_key) {
+			if (rawState.__TSR_index > lastIndex) {
+				lastIndex = rawState.__TSR_index;
+			}
+			return rawState;
+		}
+		return stampMissingState();
+	};
+
+	if (mode === "hash-param") {
+		const parseLocation = () => {
+			const state = initStamp();
+			const href = readHrefFromHash(win, pathParam);
+			const url = new URL(href, win.location.origin);
+			return {
+				href,
+				pathname: url.pathname,
+				search: url.search,
+				hash: url.hash,
+				state,
+			};
+		};
+
+		return {
+			history: createBrowserHistory({
+				window: win,
+				parseLocation,
+				createHref: href => writeHashParams(win, pathParam, href),
+			}),
+			/** Hash content for a router href — the SetLocation payload. */
+			serializePayload: (href: string) => serializeHashPayload(win, pathParam, href),
+			/** Router href from a SetLocation/ChangeFragment payload. */
+			parsePayload: (payload: string) => parseHashPayload(payload, pathParam),
+			/** Router href from the current document hash. */
+			parseCurrentHash: () => readHrefFromHash(win, pathParam),
+		};
+	}
+
+	// hash mode: the hash IS the location; legacy `#?path=` links resolve too
+	const hrefFromHash = (): string => {
+		const hash = win.location.hash;
+		if (hash.startsWith("#?")) {
+			// legacy hash-param deep link — resolve the path param out of it
+			return new URLSearchParams(hash.slice(2)).get(pathParam) ?? "/";
+		}
+		return hash.length > 1 ? hash.slice(1) : "/";
+	};
+	const parseLocation = () => {
+		const state = initStamp();
+		const href = hrefFromHash();
+		const url = new URL(href, win.location.origin);
+		return {
+			href,
+			pathname: url.pathname,
+			search: url.search,
+			hash: url.hash,
+			state,
+		};
+	};
+
+	return {
+		history: createBrowserHistory({
+			window: win,
+			parseLocation,
+			createHref: href => `${win.location.pathname}${win.location.search}#${href}`,
+		}),
+		/** Hash content for a router href — the SetLocation payload. */
+		serializePayload: (href: string) => href,
+		/** Router href from a SetLocation/ChangeFragment payload. */
+		parsePayload: (payload: string) => parseHashLocation(payload),
+		/** Router href from the current document hash. */
+		parseCurrentHash: hrefFromHash,
+	};
+}
+
+export type VkHistory = ReturnType<typeof createVkHistory>;

package/src/index.ts

@@ -0,0 +1,30 @@
+export {
+	DEFAULT_PATH_PARAM,
+	createVkHistory,
+	type VkHistory,
+	type VkHistoryMode,
+	type VkHistoryOptions,
+} from "./core/vk-history.ts";
+export {
+	applyLocation,
+	initialPanelsStack,
+	panelsHistoryOf,
+	type PanelsStackState,
+} from "./core/panels-stack.ts";
+export { POPOUT_STATE_KEY, readPopoutState, type PopoutState } from "./core/state-keys.ts";
+export { createBridgeSync, type BridgeSyncOptions } from "./core/bridge-sync.ts";
+export { createSwipeBackManager } from "./core/swipe-back.ts";
+export {
+	normalizeBridgeEvent,
+	type BridgeEventEnvelope,
+	type VkBridgeLike,
+} from "./core/bridge-like.ts";
+export {
+	readHashParams,
+	readHrefFromHash,
+	writeHashParams,
+	serializeHashPayload,
+	serializeHashLocation,
+	parseHashLocation,
+	parseHashPayload,
+} from "./core/hash-params.ts";

package/src/preset/app.tsx

@@ -0,0 +1,192 @@
+import { useRouter, useRouterState } from "@tanstack/react-router";
+import { useEffect, useRef } from "react";
+import { looseRouteOf } from "../core/loose-route.ts";
+import { Modals } from "../vkui/modals.tsx";
+import { NotFound } from "../vkui/not-found.tsx";
+import { Popouts } from "../vkui/popouts.tsx";
+import { storyKeyOf, VkView } from "../vkui/vk-view.tsx";
+import type { AppHandle } from "./builders.tsx";
+import { deriveInflateChain, interpolatePath } from "./inflate.ts";
+
+interface MatchLike {
+	routeId?: string;
+	status?: string;
+	_notFound?: boolean;
+}
+
+/**
+ * The view route owning the deepest matched route, or null. The walk starts
+ * at the deepest match because the chain depth varies — a modal is a masked
+ * CHILD route of its panel, so `/view:feed/feed/comments` must still resolve
+ * to the feed view. A notFound match anywhere in the chain wins over
+ * everything: the shell must show the NotFound screen, never a story
+ * fallback (an unmatched lazy panel's chunk never loads — a fallback story
+ * would spin forever).
+ */
+export function owningViewIdOf(
+	matches: readonly MatchLike[],
+	views: readonly { id: string }[],
+): string | null {
+	const notFound = matches.some(
+		match =>
+			match.status === "notFound" || (match as { _notFound?: boolean })._notFound === true,
+	);
+	if (notFound) {
+		return null;
+	}
+	for (let i = matches.length - 1; i >= 0; i--) {
+		const routeId = matches[i]?.routeId ?? "";
+		const view = views.find(view => routeId === view.id || routeId.startsWith(`${view.id}/`));
+		if (view !== undefined) {
+			return view.id;
+		}
+	}
+	return null;
+}
+
+/**
+ * Default root shell: the active view + the modal/popout hosts + inflate.
+ * The active view is the one containing the deepest matched route
+ * (single-view apps always get their only view). Multi-story apps with
+ * Epic/Root are built with a custom `root` shell out of the same pieces.
+ *
+ * An unmatched URL (global 404 or a `notFound()` thrown by `beforeLoad`)
+ * renders the VKUI `NotFound` instead of a view — falling back to the
+ * first view here would show its lazy panel as a spinner that never
+ * resolves, because an unmatched panel's chunk is never loaded.
+ */
+export function AppRootShell({ app, inflate = true }: { app: AppHandle; inflate?: boolean }) {
+	useInflate(app, inflate);
+	const views = Object.values(app.views);
+
+	const activeViewId = useRouterState({
+		select: (state): string | null => owningViewIdOf(state.matches, views),
+	});
+	const activeView =
+		activeViewId === null
+			? undefined
+			: Object.values(app.views).find(view => view.id === activeViewId);
+
+	return (
+		<>
+			{activeView !== undefined ? <VkView view={activeView} /> : <NotFound />}
+			<Modals entries={app.modals} />
+			<Popouts entries={app.popouts} />
+		</>
+	);
+}
+
+/**
+ * The active story key for Epic/Root shells: the view key the app author
+ * wrote in `defineView("feed")`, or null on a notFound navigation — render
+ * the NotFound screen instead of a story. Pairs with `<VkView view={…}>`
+ * whose nav defaults to the same key, so `activeStory === tab.id` compares
+ * user-authored keys on both sides.
+ */
+export function useActiveStory(app: AppHandle): string | null {
+	const views = Object.values(app.views);
+	return useRouterState({
+		select: (state): string | null => {
+			const viewId = owningViewIdOf(state.matches, views);
+			return viewId === null ? null : storyKeyOf(viewId);
+		},
+	});
+}
+
+/**
+ * Inflate (spike parity): a cold start (first history entry) on a panel
+ * that is NOT the first of its view replays the panel flow before it, so
+ * back walks the natural chain instead of closing the app. One-shot, waits
+ * for the router to go idle, skips warm navigations. `AppRootShell` runs
+ * it automatically; custom shells (Epic/Tabbar) call the hook themselves.
+ */
+export function useInflate(app: AppHandle, enabled = true): void {
+	const router = useRouter();
+	const snapshot = useRouterState({
+		select: state => {
+			let panelKey: string | null = null;
+			let panelPath: string | null = null;
+			const modalPaths: string[] = [];
+			for (let i = state.matches.length - 1; i >= 0; i--) {
+				const routeId = state.matches[i]?.routeId;
+				if (routeId === undefined) {
+					continue;
+				}
+				const route = looseRouteOf(router, routeId);
+				const staticData = route?.options.staticData;
+				if (staticData?.modal !== undefined && route !== undefined) {
+					// modal levels of the deep link, deepest first (reversed below)
+					if (route.fullPath !== undefined) {
+						modalPaths.push(route.fullPath);
+					}
+				}
+				if (staticData?.panel !== undefined) {
+					panelKey = staticData.panel;
+					panelPath = route?.fullPath ?? null;
+					break;
+				}
+			}
+			return {
+				status: state.status,
+				index:
+					(state.location.state as { __TSR_index?: number } | undefined)?.__TSR_index ??
+					0,
+				href: state.location.href,
+				panelKey,
+				panelPath,
+				modalPaths: modalPaths.toReversed(),
+				deepestParams:
+					(
+						state.matches[state.matches.length - 1] as
+							| { params?: Record<string, string> }
+							| undefined
+					)?.params ?? {},
+			};
+		},
+	});
+	const done = useRef(false);
+
+	useEffect(() => {
+		if (done.current || !enabled || snapshot.status !== "idle") {
+			return; // one-shot; retry until the router settles
+		}
+		done.current = true;
+		if (snapshot.index > 0 || snapshot.panelKey === null) {
+			return; // warm navigation or an unknown panel — nothing to inflate
+		}
+		const target = app.panels[snapshot.panelKey];
+		if (target === undefined) {
+			return;
+		}
+		const ordered = Object.values(app.panels).filter(panel => panel.viewId === target.viewId);
+		let chain = deriveInflateChain(ordered, target.routeId, snapshot.deepestParams);
+		// a deep link INTO A ROUTE MODAL: the full ancestor chain must sit in
+		// history below the target — the parent panel, then every modal level
+		// (outer → inner) — or back skips the screens the user is logically
+		// on. Only modal targets: for a panel target the parentHref IS the
+		// current location and would replay a pointless no-op navigation
+		if (snapshot.modalPaths.length > 0 && snapshot.panelPath !== null) {
+			const parentHref = interpolatePath(snapshot.panelPath, snapshot.deepestParams);
+			if (parentHref !== null && chain[chain.length - 1] !== parentHref) {
+				chain = [...chain, parentHref];
+			}
+		}
+		for (const modalPath of snapshot.modalPaths) {
+			const modalHref = interpolatePath(modalPath, snapshot.deepestParams);
+			if (modalHref !== null && chain[chain.length - 1] !== modalHref) {
+				chain = [...chain, modalHref];
+			}
+		}
+		if (chain.length === 0) {
+			return;
+		}
+		const { href: targetHref } = snapshot;
+		void (async () => {
+			await router.navigate({ href: chain[0], replace: true });
+			for (let i = 1; i < chain.length; i++) {
+				await router.navigate({ href: chain[i] });
+			}
+			await router.navigate({ href: targetHref });
+		})();
+	});
+}