@vkma.dev/router 0.0.0-stage → 0.1.0

package/dist/vkui/modals.js

@@ -0,0 +1,116 @@
+import { idleChoreography, reconcile } from "./choreography.js";
+import { useRouterState } from "@tanstack/react-router";
+import { Suspense, createContext, useContext, useEffect, useState } from "react";
+import { ModalCard, ModalPage } from "@vkontakte/vkui";
+import { Fragment, jsx } from "react/jsx-runtime";
+//#region src/vkui/modals.tsx
+const ModalSurfaceContext = createContext(null);
+function useModalSurface() {
+	const api = useContext(ModalSurfaceContext);
+	if (api === null) throw new Error("[vkma-router] ModalPageSurface/ModalCardSurface must be the root of a modal entry rendered by <Modals>");
+	return api;
+}
+/**
+* The host-owned keys VKUI actually accepts. Everything else in the api
+* (`stacked` today, future host keys tomorrow) must NOT reach the spread —
+* VKUI forwards unknown props to the DOM and React warns on booleans
+* ("Received `false` for a non-boolean attribute `stacked`").
+*/
+function hostProps(api) {
+	const { nav, open, onClose, onClosed } = api;
+	return {
+		nav,
+		open,
+		onClose,
+		onClosed
+	};
+}
+/** ModalPage surface for a modal entry — the host owns nav/open/close choreography. */
+function ModalPageSurface({ children, ...surface }) {
+	const api = useModalSurface();
+	return /* @__PURE__ */ jsx(ModalPage, {
+		...hostProps(api),
+		keepMounted: true,
+		disableFocusTrap: api.stacked || void 0,
+		...surface,
+		children
+	});
+}
+/**
+* ModalCard surface for a modal entry — same contract as
+* ModalPageSurface, with the card's icon/title/description/actions as
+* ordinary runtime props.
+*/
+function ModalCardSurface({ children, ...surface }) {
+	const api = useModalSurface();
+	return /* @__PURE__ */ jsx(ModalCard, {
+		...hostProps(api),
+		keepMounted: true,
+		disableFocusTrap: api.stacked || void 0,
+		...surface,
+		children
+	});
+}
+function Modals({ entries, exitDuration = 420 }) {
+	const routeIds = new Set(entries.map((entry) => entry.routeId));
+	const matchedModalEntry = useRouterState({ select: (state) => {
+		for (let i = state.matches.length - 1; i >= 0; i--) {
+			const routeId = state.matches[i]?.routeId;
+			if (routeId !== void 0 && routeIds.has(routeId)) return entries.find((entry) => entry.routeId === routeId) ?? null;
+		}
+		return null;
+	} });
+	const globalModalId = useRouterState({ select: (state) => state.location.search?.modal ?? null });
+	const globalEntry = globalModalId !== null ? entries.find((entry) => entry.id === globalModalId) ?? null : null;
+	const target = matchedModalEntry ?? globalEntry;
+	const [state, setState] = useState(() => reconcile(idleChoreography(), target));
+	useEffect(() => {
+		setState((previous) => reconcile(previous, target));
+	}, [target]);
+	const handleClosed = (closedId) => {
+		setState((previous) => {
+			if (previous.awaitingExitId !== closedId) return previous;
+			const settled = {
+				...previous,
+				exiting: null,
+				awaitingExitId: null
+			};
+			return reconcile(settled, settled.target);
+		});
+	};
+	useEffect(() => {
+		if (state.awaitingExitId === null) return;
+		const watchdog = setTimeout(() => handleClosed(state.awaitingExitId), exitDuration * 2);
+		return () => clearTimeout(watchdog);
+	}, [state.awaitingExitId, exitDuration]);
+	const rendered = [];
+	state.stack.forEach((entry, index) => {
+		rendered.push({
+			entry,
+			open: true,
+			stacked: index < state.stack.length - 1
+		});
+	});
+	if (state.exiting !== null && !state.stack.some((entry) => entry.id === state.exiting?.id)) rendered.push({
+		entry: state.exiting,
+		open: false,
+		stacked: false
+	});
+	return /* @__PURE__ */ jsx(Fragment, { children: rendered.map(({ entry, open, stacked }) => /* @__PURE__ */ jsx(ModalSurfaceContext.Provider, {
+		value: {
+			nav: entry.id,
+			open,
+			stacked,
+			onClose: () => window.history.back(),
+			onClosed: () => handleClosed(entry.id)
+		},
+		children: /* @__PURE__ */ jsx(Suspense, {
+			fallback: null,
+			children: /* @__PURE__ */ jsx(entry.Component, {})
+		})
+	}, entry.id)) });
+}
+//#endregion
+export { ModalCardSurface, ModalPageSurface, Modals, hostProps };
+
+//# sourceMappingURL=modals.js.map

package/dist/vkui/modals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modals.js","names":[],"sources":["../../src/vkui/modals.tsx"],"sourcesContent":["import { useRouterState } from \"@tanstack/react-router\";\nimport { ModalCard, ModalPage, type ModalCardProps, type ModalPageProps } from \"@vkontakte/vkui\";\nimport {\n\ttype ComponentType,\n\tcreateContext,\n\ttype LazyExoticComponent,\n\tSuspense,\n\tuseContext,\n\tuseEffect,\n\tuseState,\n} from \"react\";\nimport { idleChoreography, reconcile, type ChoreographyState } from \"./choreography.ts\";\n\n/**\n * Modal choreography host. The state machine lives in `choreography.ts`\n * (pure — sibling closes first, nested stacks on top, back reveals the\n * parent, retarget-during-exit cancels or queues). This host binds it to\n * VKUI: exit completion is EVENT-DRIVEN — VKUI fires `onClosed` at the\n * transition end and backs it with an internal timer computed from the\n * element's real `transitionDuration` (adapts to platform/theme/reduced-\n * motion — more accurate than any host-side constant). The host\n * `exitDuration` is only a WATCHDOG for the one case VKUI cannot report:\n * the modal unmounting before the exit finishes (its entry vanished from\n * `entries`).\n */\n\n/** A renderable modal entry component — plain or React.lazy. */\nexport type ModalEntryComponent = ComponentType | LazyExoticComponent<ComponentType>;\n\nexport interface ModalEntry {\n\t/** Full route id of the modal route (e.g. `/item/$id/details`). */\n\trouteId: string;\n\t/** Modal id — also the VKUI `nav`. */\n\tid: string;\n\t/**\n\t * The modal content. Its root must be a ModalPageSurface or\n\t * ModalCardSurface — the host binds nav/open/close choreography to it\n\t * through context; the component owns every other prop at runtime.\n\t */\n\tComponent: ModalEntryComponent;\n}\n\nexport interface ModalsProps {\n\tentries: ModalEntry[];\n\t/**\n\t * Watchdog bound for an exit whose `onClosed` never arrives (the modal\n\t * unmounted mid-animation), ms. Default 420 — well past any VKUI modal\n\t * exit animation; a healthy `onClosed` lands long before it fires.\n\t */\n\texitDuration?: number;\n}\n\n/** Host-bound surface controls, provided to every mounted modal entry. */\ninterface ModalSurfaceApi {\n\tnav: string;\n\topen: boolean;\n\t/** Another modal is stacked on top of this one — suppress the focus trap. */\n\tstacked: boolean;\n\tonClose: () => void;\n\tonClosed: () => void;\n}\n\nconst ModalSurfaceContext = createContext<ModalSurfaceApi | null>(null);\n\nfunction useModalSurface(): ModalSurfaceApi {\n\tconst api = useContext(ModalSurfaceContext);\n\tif (api === null) {\n\t\tthrow new Error(\n\t\t\t\"[vkma-router] ModalPageSurface/ModalCardSurface must be the root of a modal entry rendered by <Modals>\",\n\t\t);\n\t}\n\treturn api;\n}\n\n/**\n * The host-owned keys VKUI actually accepts. Everything else in the api\n * (`stacked` today, future host keys tomorrow) must NOT reach the spread —\n * VKUI forwards unknown props to the DOM and React warns on booleans\n * (\"Received `false` for a non-boolean attribute `stacked`\").\n */\nexport function hostProps(api: ModalSurfaceApi): {\n\tnav: string;\n\topen: boolean;\n\tonClose: () => void;\n\tonClosed: () => void;\n} {\n\tconst { nav, open, onClose, onClosed } = api;\n\treturn { nav, open, onClose, onClosed };\n}\n\n/** ModalPage surface for a modal entry — the host owns nav/open/close choreography. */\nexport function ModalPageSurface({\n\tchildren,\n\t...surface\n}: Omit<ModalPageProps, \"nav\" | \"open\" | \"onClose\" | \"onClosed\" | \"keepMounted\">) {\n\tconst api = useModalSurface();\n\treturn (\n\t\t<ModalPage\n\t\t\t{...hostProps(api)}\n\t\t\tkeepMounted\n\t\t\tdisableFocusTrap={api.stacked || undefined}\n\t\t\t{...surface}\n\t\t>\n\t\t\t{children}\n\t\t</ModalPage>\n\t);\n}\n\n/**\n * ModalCard surface for a modal entry — same contract as\n * ModalPageSurface, with the card's icon/title/description/actions as\n * ordinary runtime props.\n */\nexport function ModalCardSurface({\n\tchildren,\n\t...surface\n}: Omit<ModalCardProps, \"nav\" | \"open\" | \"onClose\" | \"onClosed\" | \"keepMounted\">) {\n\tconst api = useModalSurface();\n\treturn (\n\t\t<ModalCard\n\t\t\t{...hostProps(api)}\n\t\t\tkeepMounted\n\t\t\tdisableFocusTrap={api.stacked || undefined}\n\t\t\t{...surface}\n\t\t>\n\t\t\t{children}\n\t\t</ModalCard>\n\t);\n}\n\nexport function Modals({ entries, exitDuration = 420 }: ModalsProps) {\n\tconst routeIds = new Set(entries.map(entry => entry.routeId));\n\tconst matchedModalEntry = useRouterState({\n\t\tselect: state => {\n\t\t\tfor (let i = state.matches.length - 1; i >= 0; i--) {\n\t\t\t\tconst routeId = state.matches[i]?.routeId;\n\t\t\t\tif (routeId !== undefined && routeIds.has(routeId)) {\n\t\t\t\t\treturn entries.find(entry => entry.routeId === routeId) ?? null;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn null;\n\t\t},\n\t});\n\tconst globalModalId = useRouterState({\n\t\tselect: state => (state.location.search as { modal?: string } | undefined)?.modal ?? null,\n\t});\n\tconst globalEntry =\n\t\tglobalModalId !== null ? (entries.find(entry => entry.id === globalModalId) ?? null) : null;\n\tconst target = matchedModalEntry ?? globalEntry;\n\n\tconst [state, setState] = useState<ChoreographyState<ModalEntry>>(() =>\n\t\treconcile(idleChoreography<ModalEntry>(), target),\n\t);\n\n\t// choreograph target changes (see reconcile)\n\tuseEffect(() => {\n\t\tsetState(previous => reconcile(previous, target));\n\t}, [target]);\n\n\tconst handleClosed = (closedId: string): void => {\n\t\tsetState(previous => {\n\t\t\tif (previous.awaitingExitId !== closedId) {\n\t\t\t\treturn previous; // stale or unexpected callback\n\t\t\t}\n\t\t\tconst settled: ChoreographyState<ModalEntry> = {\n\t\t\t\t...previous,\n\t\t\t\texiting: null,\n\t\t\t\tawaitingExitId: null,\n\t\t\t};\n\t\t\treturn reconcile(settled, settled.target);\n\t\t});\n\t};\n\n\t// watchdog for the lost-onClosed case (unmount mid-exit); the dep set\n\t// re-arms it on every new exit and cleans up on completion/unmount\n\tuseEffect(() => {\n\t\tif (state.awaitingExitId === null) {\n\t\t\treturn;\n\t\t}\n\t\tconst watchdog = setTimeout(\n\t\t\t() => handleClosed(state.awaitingExitId as string),\n\t\t\texitDuration * 2,\n\t\t);\n\t\treturn () => clearTimeout(watchdog);\n\t}, [state.awaitingExitId, exitDuration]);\n\n\t// render the open stack (bottom → top) plus the exiting sheet\n\tconst rendered: Array<{ entry: ModalEntry; open: boolean; stacked: boolean }> = [];\n\tstate.stack.forEach((entry, index) => {\n\t\trendered.push({ entry, open: true, stacked: index < state.stack.length - 1 });\n\t});\n\tif (state.exiting !== null && !state.stack.some(entry => entry.id === state.exiting?.id)) {\n\t\trendered.push({ entry: state.exiting, open: false, stacked: false });\n\t}\n\n\treturn (\n\t\t<>\n\t\t\t{rendered.map(({ entry, open, stacked }) => (\n\t\t\t\t<ModalSurfaceContext.Provider\n\t\t\t\t\tkey={entry.id}\n\t\t\t\t\tvalue={{\n\t\t\t\t\t\tnav: entry.id,\n\t\t\t\t\t\topen,\n\t\t\t\t\t\tstacked,\n\t\t\t\t\t\tonClose: () => window.history.back(),\n\t\t\t\t\t\tonClosed: () => handleClosed(entry.id),\n\t\t\t\t\t}}\n\t\t\t\t>\n\t\t\t\t\t<Suspense fallback={null}>\n\t\t\t\t\t\t<entry.Component />\n\t\t\t\t\t</Suspense>\n\t\t\t\t</ModalSurfaceContext.Provider>\n\t\t\t))}\n\t\t</>\n\t);\n}\n"],"mappings":"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"}

package/dist/vkui/not-found.d.ts

@@ -0,0 +1,9 @@
+//#region src/vkui/not-found.d.ts
+/**
+ * Default 404 screen (parity with the old router's DefaultNotFound): wire it
+ * as `defaultNotFoundComponent` in `createRouter` — TanStack otherwise
+ * renders a bare `<p>Not Found</p>` and warns.
+ */
+export declare function NotFound(): React.ReactNode;
+//#endregion
+//# sourceMappingURL=not-found.d.ts.map

package/dist/vkui/not-found.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.d.ts","names":[],"sources":["../../src/vkui/not-found.tsx"],"mappings":";;;;;;wBAOgB,YAAY,MAAM"}

package/dist/vkui/not-found.js

@@ -0,0 +1,23 @@
+import { Button, Placeholder } from "@vkontakte/vkui";
+import { jsx } from "react/jsx-runtime";
+//#region src/vkui/not-found.tsx
+/**
+* Default 404 screen (parity with the old router's DefaultNotFound): wire it
+* as `defaultNotFoundComponent` in `createRouter` — TanStack otherwise
+* renders a bare `<p>Not Found</p>` and warns.
+*/
+function NotFound() {
+	return /* @__PURE__ */ jsx(Placeholder, {
+		title: "Страница не найдена",
+		action: /* @__PURE__ */ jsx(Button, {
+			size: "l",
+			onClick: () => window.history.back(),
+			children: "Назад"
+		}),
+		children: "Такой страницы не существует."
+	});
+}
+//#endregion
+export { NotFound };
+
+//# sourceMappingURL=not-found.js.map

package/dist/vkui/not-found.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.js","names":[],"sources":["../../src/vkui/not-found.tsx"],"sourcesContent":["import { Button, Placeholder } from \"@vkontakte/vkui\";\n\n/**\n * Default 404 screen (parity with the old router's DefaultNotFound): wire it\n * as `defaultNotFoundComponent` in `createRouter` — TanStack otherwise\n * renders a bare `<p>Not Found</p>` and warns.\n */\nexport function NotFound(): React.ReactNode {\n\treturn (\n\t\t<Placeholder\n\t\t\ttitle=\"Страница не найдена\"\n\t\t\taction={\n\t\t\t\t<Button size=\"l\" onClick={() => window.history.back()}>\n\t\t\t\t\tНазад\n\t\t\t\t</Button>\n\t\t\t}\n\t\t>\n\t\t\tТакой страницы не существует.\n\t\t</Placeholder>\n\t);\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,WAA4B;CAC3C,OACC,oBAAC,aAAD;EACC,OAAM;EACN,QACC,oBAAC,QAAD;GAAQ,MAAK;GAAI,eAAe,OAAO,QAAQ,KAAK;GAAG,UAAA;EAE/C,CAAA;EAET,UAAA;CAEY,CAAA;AAEf"}

package/dist/vkui/popouts.d.ts

@@ -0,0 +1,34 @@
+import { ComponentType } from "react";
+//#region src/vkui/popouts.d.ts
+/**
+ * Popouts are transient overlays, not routes: `history.state` holds
+ * `{ popout: id, props }`, so the native/system back closes them, and
+ * back/forward restores both the id and the props. Components come from
+ * the registry (per-panel and/or global — see the preset builders);
+ * `onClose` is injected by the host.
+ */
+export interface PopoutEntry {
+  id: string;
+  Component: ComponentType<{
+    onClose: () => void;
+  }>;
+  /**
+   * The owning panel key (`${view}/${panel}`) for a panel-local popout —
+   * it resolves only while that panel is the deepest matched one.
+   * Undefined = global (resolves from any panel).
+   */
+  panel?: string;
+}
+export declare function usePopoutState(): {
+  id: string;
+  props?: Record<string, unknown>;
+} | undefined;
+/** `showPopout(id, props)` — pushes a popout entry; replaces if one is open. */
+export declare function useShowPopout(): (id: string, props?: Record<string, unknown>) => void;
+/** `hidePopout()` — unwinds the popout entry; on the first entry, strips in place. */
+export declare function useHidePopout(): () => void;
+export declare function Popouts({ entries }: {
+  entries: PopoutEntry[];
+}): import("react").JSX.Element | null;
+//#endregion
+//# sourceMappingURL=popouts.d.ts.map

package/dist/vkui/popouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popouts.d.ts","names":[],"sources":["../../src/vkui/popouts.tsx"],"mappings":";;;;;;;;;iBAaiB;EAChB;EACA,WAAW;IAAgB;;;;;;;EAM3B;;wBAGe;EAAoB;EAAY,QAAQ;;;wBAKxC,kBAAkB,YAAY,QAAQ;;wBAiBtC;wBAuCA,UAAU;EAAa,SAAS;oBAAe,IAAA"}

package/dist/vkui/popouts.js

@@ -0,0 +1,69 @@
+import { POPOUT_STATE_KEY, readPopoutState } from "../core/state-keys.js";
+import { looseRouteOf } from "../core/loose-route.js";
+import { useRouter, useRouterState } from "@tanstack/react-router";
+import { jsx } from "react/jsx-runtime";
+//#region src/vkui/popouts.tsx
+function usePopoutState() {
+	return useRouterState({ select: (state) => readPopoutState(state.location.state) });
+}
+/** `showPopout(id, props)` — pushes a popout entry; replaces if one is open. */
+function useShowPopout() {
+	const router = useRouter();
+	const isOpen = usePopoutState() !== void 0;
+	return (id, props) => {
+		router.navigate({
+			href: router.state.location.href,
+			state: (previous) => ({
+				...previous ?? {},
+				[POPOUT_STATE_KEY]: {
+					id,
+					props
+				}
+			}),
+			replace: isOpen
+		});
+	};
+}
+/** `hidePopout()` — unwinds the popout entry; on the first entry, strips in place. */
+function useHidePopout() {
+	const router = useRouter();
+	return () => {
+		if (router.history.canGoBack()) {
+			router.history.back();
+			return;
+		}
+		const state = { ...router.state.location.state };
+		delete state[POPOUT_STATE_KEY];
+		router.navigate({
+			href: router.state.location.href,
+			replace: true,
+			state
+		});
+	};
+}
+/** The deepest matched panel's registry key (`${view}/${panel}`), or null. */
+function useActivePanelKey() {
+	const router = useRouter();
+	return useRouterState({ select: (state) => {
+		for (let i = state.matches.length - 1; i >= 0; i--) {
+			const routeId = state.matches[i]?.routeId;
+			if (routeId === void 0) continue;
+			const panel = looseRouteOf(router, routeId)?.options.staticData?.panel;
+			if (panel !== void 0) return panel;
+		}
+		return null;
+	} });
+}
+function Popouts({ entries }) {
+	const popout = usePopoutState();
+	const hide = useHidePopout();
+	const activePanelKey = useActivePanelKey();
+	if (popout === void 0) return null;
+	const entry = entries.find((candidate) => candidate.panel !== void 0 && candidate.panel === activePanelKey && candidate.id === popout.id) ?? entries.find((candidate) => candidate.panel === void 0 && candidate.id === popout.id);
+	if (!entry) return null;
+	return /* @__PURE__ */ jsx(entry.Component, { onClose: hide });
+}
+//#endregion
+export { Popouts, useHidePopout, usePopoutState, useShowPopout };
+
+//# sourceMappingURL=popouts.js.map

package/dist/vkui/popouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popouts.js","names":[],"sources":["../../src/vkui/popouts.tsx"],"sourcesContent":["import { useRouter, useRouterState } from \"@tanstack/react-router\";\nimport { type ComponentType } from \"react\";\nimport { looseRouteOf } from \"../core/loose-route.ts\";\nimport { POPOUT_STATE_KEY, readPopoutState } from \"../core/state-keys.ts\";\n\n/**\n * Popouts are transient overlays, not routes: `history.state` holds\n * `{ popout: id, props }`, so the native/system back closes them, and\n * back/forward restores both the id and the props. Components come from\n * the registry (per-panel and/or global — see the preset builders);\n * `onClose` is injected by the host.\n */\n\nexport interface PopoutEntry {\n\tid: string;\n\tComponent: ComponentType<{ onClose: () => void }>;\n\t/**\n\t * The owning panel key (`${view}/${panel}`) for a panel-local popout —\n\t * it resolves only while that panel is the deepest matched one.\n\t * Undefined = global (resolves from any panel).\n\t */\n\tpanel?: string;\n}\n\nexport function usePopoutState(): { id: string; props?: Record<string, unknown> } | undefined {\n\treturn useRouterState({ select: state => readPopoutState(state.location.state) });\n}\n\n/** `showPopout(id, props)` — pushes a popout entry; replaces if one is open. */\nexport function useShowPopout(): (id: string, props?: Record<string, unknown>) => void {\n\tconst router = useRouter();\n\tconst isOpen = usePopoutState() !== undefined;\n\treturn (id, props) => {\n\t\tvoid router.navigate({\n\t\t\thref: router.state.location.href,\n\t\t\tstate: (previous: unknown) =>\n\t\t\t\t({\n\t\t\t\t\t...((previous ?? {}) as Record<string, unknown>),\n\t\t\t\t\t[POPOUT_STATE_KEY]: { id, props },\n\t\t\t\t}) as never,\n\t\t\treplace: isOpen,\n\t\t});\n\t};\n}\n\n/** `hidePopout()` — unwinds the popout entry; on the first entry, strips in place. */\nexport function useHidePopout(): () => void {\n\tconst router = useRouter();\n\treturn () => {\n\t\tif (router.history.canGoBack()) {\n\t\t\trouter.history.back();\n\t\t\treturn;\n\t\t}\n\t\tconst state = {\n\t\t\t...(router.state.location.state as unknown as Record<string, unknown>),\n\t\t};\n\t\tdelete state[POPOUT_STATE_KEY];\n\t\tvoid router.navigate({\n\t\t\thref: router.state.location.href,\n\t\t\treplace: true,\n\t\t\tstate,\n\t\t});\n\t};\n}\n\n/** The deepest matched panel's registry key (`${view}/${panel}`), or null. */\nfunction useActivePanelKey(): string | null {\n\tconst router = useRouter();\n\treturn useRouterState({\n\t\tselect: (state): string | null => {\n\t\t\tfor (let i = state.matches.length - 1; i >= 0; i--) {\n\t\t\t\tconst routeId = state.matches[i]?.routeId;\n\t\t\t\tif (routeId === undefined) {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst panel = looseRouteOf(router, routeId)?.options.staticData?.panel;\n\t\t\t\tif (panel !== undefined) {\n\t\t\t\t\treturn panel;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn null;\n\t\t},\n\t});\n}\n\nexport function Popouts({ entries }: { entries: PopoutEntry[] }) {\n\tconst popout = usePopoutState();\n\tconst hide = useHidePopout();\n\tconst activePanelKey = useActivePanelKey();\n\tif (popout === undefined) {\n\t\treturn null;\n\t}\n\t// resolution local → global: the current panel's own popouts shadow the\n\t// global registry\n\tconst entry =\n\t\tentries.find(\n\t\t\tcandidate =>\n\t\t\t\tcandidate.panel !== undefined &&\n\t\t\t\tcandidate.panel === activePanelKey &&\n\t\t\t\tcandidate.id === popout.id,\n\t\t) ?? entries.find(candidate => candidate.panel === undefined && candidate.id === popout.id);\n\tif (!entry) {\n\t\treturn null;\n\t}\n\treturn <entry.Component onClose={hide} />;\n}\n"],"mappings":";;;;;AAwBA,SAAgB,iBAA8E;CAC7F,OAAO,eAAe,EAAE,SAAQ,UAAS,gBAAgB,MAAM,SAAS,KAAK,EAAE,CAAC;AACjF;;AAGA,SAAgB,gBAAuE;CACtF,MAAM,SAAS,UAAU;CACzB,MAAM,SAAS,eAAe,MAAM,KAAA;CACpC,QAAQ,IAAI,UAAU;EACrB,OAAY,SAAS;GACpB,MAAM,OAAO,MAAM,SAAS;GAC5B,QAAQ,cACN;IACA,GAAK,YAAY,CAAC;KACjB,mBAAmB;KAAE;KAAI;IAAM;GACjC;GACD,SAAS;EACV,CAAC;CACF;AACD;;AAGA,SAAgB,gBAA4B;CAC3C,MAAM,SAAS,UAAU;CACzB,aAAa;EACZ,IAAI,OAAO,QAAQ,UAAU,GAAG;GAC/B,OAAO,QAAQ,KAAK;GACpB;EACD;EACA,MAAM,QAAQ,EACb,GAAI,OAAO,MAAM,SAAS,MAC3B;EACA,OAAO,MAAM;EACb,OAAY,SAAS;GACpB,MAAM,OAAO,MAAM,SAAS;GAC5B,SAAS;GACT;EACD,CAAC;CACF;AACD;;AAGA,SAAS,oBAAmC;CAC3C,MAAM,SAAS,UAAU;CACzB,OAAO,eAAe,EACrB,SAAS,UAAyB;EACjC,KAAK,IAAI,IAAI,MAAM,QAAQ,SAAS,GAAG,KAAK,GAAG,KAAK;GACnD,MAAM,UAAU,MAAM,QAAQ,EAAE,EAAE;GAClC,IAAI,YAAY,KAAA,GACf;GAED,MAAM,QAAQ,aAAa,QAAQ,OAAO,CAAC,EAAE,QAAQ,YAAY;GACjE,IAAI,UAAU,KAAA,GACb,OAAO;EAET;EACA,OAAO;CACR,EACD,CAAC;AACF;AAEA,SAAgB,QAAQ,EAAE,WAAuC;CAChE,MAAM,SAAS,eAAe;CAC9B,MAAM,OAAO,cAAc;CAC3B,MAAM,iBAAiB,kBAAkB;CACzC,IAAI,WAAW,KAAA,GACd,OAAO;CAIR,MAAM,QACL,QAAQ,MACP,cACC,UAAU,UAAU,KAAA,KACpB,UAAU,UAAU,kBACpB,UAAU,OAAO,OAAO,EAC1B,KAAK,QAAQ,MAAK,cAAa,UAAU,UAAU,KAAA,KAAa,UAAU,OAAO,OAAO,EAAE;CAC3F,IAAI,CAAC,OACJ,OAAO;CAER,OAAO,oBAAC,MAAM,WAAP,EAAiB,SAAS,KAAO,CAAA;AACzC"}

package/dist/vkui/vk-view.d.ts

@@ -0,0 +1,26 @@
+import { AnyRoute } from "@tanstack/react-router";
+//#region src/vkui/vk-view.d.ts
+export declare function panelIdOf(route: AnyRoute): string;
+export interface VkViewProps {
+  /** The pathless view layout route created by the preset. */
+  view: AnyRoute;
+  /** VKUI nav id of the View. Defaults to the route id. */
+  nav?: string;
+  /** Native swipe-back pop; defaults to `window.history.back()`. */
+  onSwipeBack?: () => void;
+}
+/**
+ * Static-children view: every panel route renders as an always-present JSX
+ * child of VKUI <View>; the router only feeds `activePanel` (and `history`
+ * for the iOS swipe-back). VKUI hides inactive panels itself and infers
+ * the animation direction from the children order — a plain <Outlet>
+ * breaks both. A lazy panel's `options.component` is undefined until its
+ * chunk resolves (TanStack merges loaded options in place), so the panel
+ * renders a spinner fallback until then. For the same reason TanStack's
+ * Outlet-driven `pendingComponent` swap never happens on its own — while
+ * the panel's match is pending (loader/beforeLoad), the route's
+ * `pendingComponent` renders instead of the component.
+ */
+export declare function VkView({ view, nav, onSwipeBack }: VkViewProps): import("react").JSX.Element;
+//#endregion
+//# sourceMappingURL=vk-view.d.ts.map

package/dist/vkui/vk-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vk-view.d.ts","names":[],"sources":["../../src/vkui/vk-view.tsx"],"mappings":";;wBAUgB,UAAU,OAAO;iBAyBhB;;EAEhB,MAAM;;EAEN;;EAEA;;;;;;;;;;;;;;wBAee,SAAS,MAAM,KAAK,eAAe,8BAAW,IAAA"}

package/dist/vkui/vk-view.js

@@ -0,0 +1,71 @@
+import { usePanelsHistory } from "../react/hooks.js";
+import { useRouterState } from "@tanstack/react-router";
+import { Panel, Spinner, View } from "@vkontakte/vkui";
+import { jsx } from "react/jsx-runtime";
+//#region src/vkui/vk-view.tsx
+function panelIdOf(route) {
+	return route.options.staticData?.panel ?? "";
+}
+function deepestPanelMatchId(view, matchedRouteIds) {
+	const panelIds = new Set(view.children.map((child) => child.id));
+	for (let i = matchedRouteIds.length - 1; i >= 0; i--) {
+		const id = matchedRouteIds[i];
+		if (id !== void 0 && panelIds.has(id)) return id;
+	}
+	return view.children[0]?.id ?? "";
+}
+function useMatchSummaries() {
+	return useRouterState({ select: (state) => state.matches.map((match) => `${match.routeId}#${match.status}`).join("|") });
+}
+/**
+* Static-children view: every panel route renders as an always-present JSX
+* child of VKUI <View>; the router only feeds `activePanel` (and `history`
+* for the iOS swipe-back). VKUI hides inactive panels itself and infers
+* the animation direction from the children order — a plain <Outlet>
+* breaks both. A lazy panel's `options.component` is undefined until its
+* chunk resolves (TanStack merges loaded options in place), so the panel
+* renders a spinner fallback until then. For the same reason TanStack's
+* Outlet-driven `pendingComponent` swap never happens on its own — while
+* the panel's match is pending (loader/beforeLoad), the route's
+* `pendingComponent` renders instead of the component.
+*/
+function VkView({ view, nav, onSwipeBack }) {
+	useMatchSummaries();
+	const matchedRouteIds = useRouterState({ select: (state) => state.matches.map((match) => match.routeId) });
+	const pendingRouteIds = useRouterState({ select: (state) => state.matches.filter((match) => match.status === "pending").map((match) => String(match.routeId)) });
+	const notFoundRouteIds = useRouterState({ select: (state) => state.matches.filter((match) => match.status === "notFound").map((match) => String(match.routeId)) });
+	const activeRouteId = deepestPanelMatchId(view, matchedRouteIds);
+	const activeChild = view.children.find((child) => child.id === activeRouteId) ?? view.children[0];
+	const activePanel = activeChild ? panelIdOf(activeChild) : "";
+	const history = usePanelsHistory(activePanel);
+	return /* @__PURE__ */ jsx(View, {
+		nav: nav ?? view.id,
+		activePanel,
+		history,
+		onSwipeBack: onSwipeBack ?? (() => window.history.back()),
+		children: view.children.map((child) => {
+			const id = panelIdOf(child);
+			const Component = child.options.component;
+			const Pending = child.options.pendingComponent;
+			const isPending = pendingRouteIds.includes(String(child.id));
+			const isNotFound = notFoundRouteIds.includes(String(child.id));
+			return /* @__PURE__ */ jsx(Panel, {
+				nav: id,
+				children: isPending ? Pending !== void 0 ? /* @__PURE__ */ jsx(Pending, {}) : /* @__PURE__ */ jsx(PanelSpinnerFallback, {}) : isNotFound ? /* @__PURE__ */ jsx(PanelSpinnerFallback, {}) : Component ? /* @__PURE__ */ jsx(Component, {}) : /* @__PURE__ */ jsx(PanelSpinnerFallback, {})
+			}, id);
+		})
+	});
+}
+function PanelSpinnerFallback() {
+	return /* @__PURE__ */ jsx("div", {
+		style: {
+			paddingTop: 64,
+			textAlign: "center"
+		},
+		children: /* @__PURE__ */ jsx(Spinner, { size: "l" })
+	});
+}
+//#endregion
+export { VkView, panelIdOf };
+
+//# sourceMappingURL=vk-view.js.map

package/dist/vkui/vk-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vk-view.js","names":[],"sources":["../../src/vkui/vk-view.tsx"],"sourcesContent":["import type { AnyRoute } from \"@tanstack/react-router\";\nimport { useRouterState } from \"@tanstack/react-router\";\nimport { Panel, Spinner, View } from \"@vkontakte/vkui\";\nimport { type ComponentType } from \"react\";\nimport { usePanelsHistory } from \"../react/hooks.ts\";\n\nexport interface PanelStaticData {\n\tpanel: string;\n}\n\nexport function panelIdOf(route: AnyRoute): string {\n\treturn (route.options.staticData as PanelStaticData | undefined)?.panel ?? \"\";\n}\n\nfunction deepestPanelMatchId(view: AnyRoute, matchedRouteIds: string[]): string {\n\tconst panelIds = new Set(view.children.map((child: AnyRoute) => child.id));\n\tfor (let i = matchedRouteIds.length - 1; i >= 0; i--) {\n\t\tconst id = matchedRouteIds[i];\n\t\tif (id !== undefined && panelIds.has(id)) {\n\t\t\treturn id;\n\t\t}\n\t}\n\treturn view.children[0]?.id ?? \"\";\n}\n\nfunction useMatchSummaries(): string {\n\treturn useRouterState({\n\t\tselect: state =>\n\t\t\t// routeId + status: a lazy panel's chunk resolution flips the match\n\t\t\t// status, which must re-render the static children (the resolved\n\t\t\t// component merges into route.options at that point)\n\t\t\tstate.matches.map(match => `${match.routeId}#${match.status}`).join(\"|\"),\n\t});\n}\n\nexport interface VkViewProps {\n\t/** The pathless view layout route created by the preset. */\n\tview: AnyRoute;\n\t/** VKUI nav id of the View. Defaults to the route id. */\n\tnav?: string;\n\t/** Native swipe-back pop; defaults to `window.history.back()`. */\n\tonSwipeBack?: () => void;\n}\n\n/**\n * Static-children view: every panel route renders as an always-present JSX\n * child of VKUI <View>; the router only feeds `activePanel` (and `history`\n * for the iOS swipe-back). VKUI hides inactive panels itself and infers\n * the animation direction from the children order — a plain <Outlet>\n * breaks both. A lazy panel's `options.component` is undefined until its\n * chunk resolves (TanStack merges loaded options in place), so the panel\n * renders a spinner fallback until then. For the same reason TanStack's\n * Outlet-driven `pendingComponent` swap never happens on its own — while\n * the panel's match is pending (loader/beforeLoad), the route's\n * `pendingComponent` renders instead of the component.\n */\nexport function VkView({ view, nav, onSwipeBack }: VkViewProps) {\n\tuseMatchSummaries();\n\tconst matchedRouteIds = useRouterState({\n\t\tselect: state => state.matches.map(match => match.routeId),\n\t});\n\t// structurally-compared array — TanStack keeps the reference stable when\n\t// the selection is deep-equal. TanStack's Outlet would swap in the\n\t// route's pendingComponent itself, but static children render the\n\t// component directly, so the swap is ours to make while the loader runs\n\tconst pendingRouteIds = useRouterState({\n\t\tselect: state =>\n\t\t\tstate.matches\n\t\t\t\t.filter(match => (match as { status?: string }).status === \"pending\")\n\t\t\t\t.map(match => String(match.routeId)),\n\t});\n\t// a notFound match (notFound() from beforeLoad/validateSearch) must NOT\n\t// render its panel component: the component's data guards assume a valid\n\t// match, and the shell renders the NotFound screen for this navigation —\n\t// the panel itself stays invisible. Without the gate the component would\n\t// throw in a transient render and dirty the console on every cold 404\n\tconst notFoundRouteIds = useRouterState({\n\t\tselect: state =>\n\t\t\tstate.matches\n\t\t\t\t.filter(match => (match as { status?: string }).status === \"notFound\")\n\t\t\t\t.map(match => String(match.routeId)),\n\t});\n\tconst activeRouteId = deepestPanelMatchId(view, matchedRouteIds);\n\tconst activeChild =\n\t\tview.children.find((child: AnyRoute) => child.id === activeRouteId) ?? view.children[0];\n\tconst activePanel = activeChild ? panelIdOf(activeChild) : \"\";\n\n\tconst history = usePanelsHistory(activePanel);\n\n\treturn (\n\t\t<View\n\t\t\tnav={nav ?? view.id}\n\t\t\tactivePanel={activePanel}\n\t\t\thistory={history}\n\t\t\tonSwipeBack={onSwipeBack ?? (() => window.history.back())}\n\t\t>\n\t\t\t{view.children.map((child: AnyRoute) => {\n\t\t\t\tconst id = panelIdOf(child);\n\t\t\t\tconst Component = child.options.component as ComponentType | undefined;\n\t\t\t\tconst Pending = child.options.pendingComponent as ComponentType | undefined;\n\t\t\t\tconst isPending = pendingRouteIds.includes(String(child.id));\n\t\t\t\tconst isNotFound = notFoundRouteIds.includes(String(child.id));\n\t\t\t\t// pending without a pendingComponent renders the FALLBACK, never\n\t\t\t\t// the component: a lazy chunk may have already merged its\n\t\t\t\t// component while the match is still pending (or parked on a\n\t\t\t\t// notFound boundary up the tree) — the component's data guards\n\t\t\t\t// assume a resolvable match and would throw in a hidden panel\n\t\t\t\treturn (\n\t\t\t\t\t<Panel key={id} nav={id}>\n\t\t\t\t\t\t{isPending ? (\n\t\t\t\t\t\t\tPending !== undefined ? (\n\t\t\t\t\t\t\t\t<Pending />\n\t\t\t\t\t\t\t) : (\n\t\t\t\t\t\t\t\t<PanelSpinnerFallback />\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t) : isNotFound ? (\n\t\t\t\t\t\t\t<PanelSpinnerFallback />\n\t\t\t\t\t\t) : Component ? (\n\t\t\t\t\t\t\t<Component />\n\t\t\t\t\t\t) : (\n\t\t\t\t\t\t\t<PanelSpinnerFallback />\n\t\t\t\t\t\t)}\n\t\t\t\t\t</Panel>\n\t\t\t\t);\n\t\t\t})}\n\t\t</View>\n\t);\n}\n\nfunction PanelSpinnerFallback() {\n\treturn (\n\t\t<div style={{ paddingTop: 64, textAlign: \"center\" }}>\n\t\t\t<Spinner size=\"l\" />\n\t\t</div>\n\t);\n}\n"],"mappings":";;;;;AAUA,SAAgB,UAAU,OAAyB;CAClD,OAAQ,MAAM,QAAQ,YAA4C,SAAS;AAC5E;AAEA,SAAS,oBAAoB,MAAgB,iBAAmC;CAC/E,MAAM,WAAW,IAAI,IAAI,KAAK,SAAS,KAAK,UAAoB,MAAM,EAAE,CAAC;CACzE,KAAK,IAAI,IAAI,gBAAgB,SAAS,GAAG,KAAK,GAAG,KAAK;EACrD,MAAM,KAAK,gBAAgB;EAC3B,IAAI,OAAO,KAAA,KAAa,SAAS,IAAI,EAAE,GACtC,OAAO;CAET;CACA,OAAO,KAAK,SAAS,EAAE,EAAE,MAAM;AAChC;AAEA,SAAS,oBAA4B;CACpC,OAAO,eAAe,EACrB,SAAQ,UAIP,MAAM,QAAQ,KAAI,UAAS,GAAG,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,CAAC,KAAK,GAAG,EACzE,CAAC;AACF;;;;;;;;;;;;;AAuBA,SAAgB,OAAO,EAAE,MAAM,KAAK,eAA4B;CAC/D,kBAAkB;CAClB,MAAM,kBAAkB,eAAe,EACtC,SAAQ,UAAS,MAAM,QAAQ,KAAI,UAAS,MAAM,OAAO,EAC1D,CAAC;CAKD,MAAM,kBAAkB,eAAe,EACtC,SAAQ,UACP,MAAM,QACJ,QAAO,UAAU,MAA8B,WAAW,SAAS,CAAC,CACpE,KAAI,UAAS,OAAO,MAAM,OAAO,CAAC,EACtC,CAAC;CAMD,MAAM,mBAAmB,eAAe,EACvC,SAAQ,UACP,MAAM,QACJ,QAAO,UAAU,MAA8B,WAAW,UAAU,CAAC,CACrE,KAAI,UAAS,OAAO,MAAM,OAAO,CAAC,EACtC,CAAC;CACD,MAAM,gBAAgB,oBAAoB,MAAM,eAAe;CAC/D,MAAM,cACL,KAAK,SAAS,MAAM,UAAoB,MAAM,OAAO,aAAa,KAAK,KAAK,SAAS;CACtF,MAAM,cAAc,cAAc,UAAU,WAAW,IAAI;CAE3D,MAAM,UAAU,iBAAiB,WAAW;CAE5C,OACC,oBAAC,MAAD;EACC,KAAK,OAAO,KAAK;EACJ;EACJ;EACT,aAAa,sBAAsB,OAAO,QAAQ,KAAK;EAEtD,UAAA,KAAK,SAAS,KAAK,UAAoB;GACvC,MAAM,KAAK,UAAU,KAAK;GAC1B,MAAM,YAAY,MAAM,QAAQ;GAChC,MAAM,UAAU,MAAM,QAAQ;GAC9B,MAAM,YAAY,gBAAgB,SAAS,OAAO,MAAM,EAAE,CAAC;GAC3D,MAAM,aAAa,iBAAiB,SAAS,OAAO,MAAM,EAAE,CAAC;GAM7D,OACC,oBAAC,OAAD;IAAgB,KAAK;IACnB,UAAA,YACA,YAAY,KAAA,IACX,oBAAC,SAAD,CAAU,CAAA,IAEV,oBAAC,sBAAD,CAAuB,CAAA,IAErB,aACH,oBAAC,sBAAD,CAAuB,CAAA,IACpB,YACH,oBAAC,WAAD,CAAY,CAAA,IAEZ,oBAAC,sBAAD,CAAuB,CAAA;GAElB,GAdK,EAcL;EAET,CAAC;CACI,CAAA;AAER;AAEA,SAAS,uBAAuB;CAC/B,OACC,oBAAC,OAAD;EAAK,OAAO;GAAE,YAAY;GAAI,WAAW;EAAS;EACjD,UAAA,oBAAC,SAAD,EAAS,MAAK,IAAK,CAAA;CACf,CAAA;AAEP"}

package/dist/vkui.d.ts

@@ -0,0 +1,5 @@
+import { ModalCardSurface, ModalEntry, ModalEntryComponent, ModalPageSurface, Modals, ModalsProps } from "./vkui/modals.js";
+import { PopoutEntry, Popouts, useHidePopout, usePopoutState, useShowPopout } from "./vkui/popouts.js";
+import { VkView, VkViewProps, panelIdOf } from "./vkui/vk-view.js";
+import { NotFound } from "./vkui/not-found.js";
+export { ModalCardSurface, type ModalEntry, type ModalEntryComponent, ModalPageSurface, Modals, type ModalsProps, NotFound, type PopoutEntry, Popouts, VkView, type VkViewProps, panelIdOf, useHidePopout, usePopoutState, useShowPopout };

package/dist/vkui.js

@@ -0,0 +1,5 @@
+import { VkView, panelIdOf } from "./vkui/vk-view.js";
+import { ModalCardSurface, ModalPageSurface, Modals } from "./vkui/modals.js";
+import { Popouts, useHidePopout, usePopoutState, useShowPopout } from "./vkui/popouts.js";
+import { NotFound } from "./vkui/not-found.js";
+export { ModalCardSurface, ModalPageSurface, Modals, NotFound, Popouts, VkView, panelIdOf, useHidePopout, usePopoutState, useShowPopout };

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@vkma.dev/router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "VK Mini Apps router on top of TanStack Router — VKUI views/panels/modals/popouts, VK history and bridge sync",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vkui": {
+      "types": "./dist/vkui.d.ts",
+      "import": "./dist/vkui.js"
+    },
+    "./preset": {
+      "types": "./dist/preset.d.ts",
+      "import": "./dist/preset.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "dependencies": {
+    "@tanstack/history": "^1.162.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": "^1.170.0",
+    "@vkontakte/vkui": "^8.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@vkontakte/vkui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-router": "^1.170.46",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@vkontakte/vkui": "^8.4.0",
+    "happy-dom": "^21.0.4",
+    "publint": "^0.3.25",
+    "react": "^19.3.1",
+    "tsdown": "^0.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint:package": "publint",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  }
 }

package/src/core/bridge-like.ts

@@ -0,0 +1,25 @@
+/**
+ * The structural bridge contract: type-compatible with both
+ * `@vkontakte/vk-bridge` (whose subscribe handlers receive
+ * `{ detail: { type, data } }` CustomEvents) and `@vkma.dev/bridge`
+ * (flat `{ type, data }`). The router never hard-depends on either.
+ */
+
+export interface BridgeEventEnvelope {
+	type?: string;
+	data?: unknown;
+	detail?: { type?: string; data?: unknown };
+}
+
+export interface VkBridgeLike {
+	send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+	subscribe(handler: (event: BridgeEventEnvelope) => void): () => void;
+}
+
+export function normalizeBridgeEvent(
+	event: BridgeEventEnvelope,
+): { type: string; data: unknown } | null {
+	const type = event.detail?.type ?? event.type;
+	const data = event.detail !== undefined ? event.detail.data : event.data;
+	return type !== undefined ? { type, data } : null;
+}

package/src/core/bridge-sync.ts

@@ -0,0 +1,95 @@
+import { normalizeBridgeEvent, type VkBridgeLike } from "./bridge-like.ts";
+import { parseHashLocation, serializeHashLocation } from "./hash-params.ts";
+
+/**
+ * The host↔app location sync contract:
+ * - every committed history change → `VKWebAppSetLocation`
+ *   (`replace_state: true`) so the host URL/share reflects the app;
+ * - incoming `VKWebAppChangeFragment` / `VKWebAppLocationChanged`
+ *   (host-initiated jumps) → `history.replace(href)`;
+ * - loop protection: an incoming href equal to the current one is ignored.
+ *
+ * Payload codecs come from the history (they are mode-specific: hash mode
+ * sends the hash content, hash-param mode sends `?path=…` preserving
+ * foreign params). The initial location is sent once at creation.
+ * Serialization happens from the history EVENT's location: subscribers are
+ * notified synchronously before the microtask flush writes the URL, so
+ * `window.location.hash` is stale by one entry at notify time.
+ */
+
+const LOCATION_EVENTS = new Set(["VKWebAppChangeFragment", "VKWebAppLocationChanged"]);
+
+export interface BridgeSyncOptions {
+	history: {
+		location: { pathname: string; search: string; hash: string };
+		subscribe(
+			listener: (event: {
+				location: { pathname: string; search: string; hash: string };
+			}) => void,
+		): () => void;
+		replace(path: string): void;
+	};
+	bridge: VkBridgeLike;
+	/**
+	 * SetLocation payload for a committed location. Defaults to the hash
+	 * mode (the hash content); hash-param users pass the codecs from
+	 * `createVkHistory`.
+	 */
+	serializePayload?: (location: { pathname: string; search: string; hash: string }) => string;
+	/** Router href from a SetLocation/ChangeFragment payload. */
+	parsePayload?: (payload: string) => string;
+}
+
+/** Hash-mode codecs are the defaults. */
+const serializeDefault = (location: { pathname: string; search: string; hash: string }): string =>
+	serializeHashLocation(location);
+
+const parseDefault = (payload: string): string => parseHashLocation(payload);
+
+export function createBridgeSync(options: BridgeSyncOptions): { destroy(): void } {
+	const serializePayload = options.serializePayload ?? serializeDefault;
+	const parsePayload = options.parsePayload ?? parseDefault;
+	let lastSent = "";
+
+	const sendLocation = (location: { pathname: string; search: string; hash: string }): void => {
+		const payload = serializePayload(location);
+		if (payload !== lastSent) {
+			lastSent = payload;
+			void options.bridge.send("VKWebAppSetLocation", {
+				location: payload,
+				replace_state: true,
+			});
+		}
+	};
+
+	// the host must learn the location the app started at
+	sendLocation(options.history.location);
+
+	const unsubscribeHistory = options.history.subscribe(event => {
+		sendLocation(event.location);
+	});
+
+	const unsubscribeBridge = options.bridge.subscribe(rawEvent => {
+		const event = normalizeBridgeEvent(rawEvent);
+		if (event === null || !LOCATION_EVENTS.has(event.type)) {
+			return;
+		}
+		const data = event.data as { location?: string } | undefined;
+		if (!data?.location) {
+			return; // malformed — the host always sends a location; never act on it
+		}
+		const incoming = parsePayload(data.location);
+		const current = `${options.history.location.pathname}${options.history.location.search}`;
+		if (incoming === current) {
+			return; // echo of our own location — loop protection
+		}
+		options.history.replace(incoming);
+	});
+
+	return {
+		destroy() {
+			unsubscribeHistory();
+			unsubscribeBridge();
+		},
+	};
+}