@vkma.dev/router 0.0.0-stage → 0.1.1

package/dist/core/vk-history.js

@@ -0,0 +1,115 @@
+import { parseHashLocation, parseHashPayload, readHrefFromHash, serializeHashPayload, writeHashParams } from "./hash-params.js";
+import { createBrowserHistory } from "@tanstack/history";
+//#region src/core/vk-history.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`.
+*/
+const DEFAULT_PATH_PARAM = "path";
+/** The history plus the payload codecs the bridge sync layer needs. */
+function createVkHistory(options = {}) {
+	const win = options.window ?? window;
+	const pathParam = options.pathParam ?? "path";
+	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 = () => {
+		lastIndex += 1;
+		const key = Math.random().toString(36).slice(2, 8);
+		const state = {
+			__TSR_index: lastIndex,
+			key,
+			__TSR_key: key
+		};
+		win.history.replaceState(state, "", win.location.href);
+		return state;
+	};
+	const initStamp = () => {
+		const rawState = win.history.state;
+		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) => serializeHashPayload(win, pathParam, href),
+			/** Router href from a SetLocation/ChangeFragment payload. */
+			parsePayload: (payload) => parseHashPayload(payload, pathParam),
+			/** Router href from the current document hash. */
+			parseCurrentHash: () => readHrefFromHash(win, pathParam)
+		};
+	}
+	const hrefFromHash = () => {
+		const hash = win.location.hash;
+		if (hash.startsWith("#?")) 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) => href,
+		/** Router href from a SetLocation/ChangeFragment payload. */
+		parsePayload: (payload) => parseHashLocation(payload),
+		/** Router href from the current document hash. */
+		parseCurrentHash: hrefFromHash
+	};
+}
+//#endregion
+export { DEFAULT_PATH_PARAM, createVkHistory };
+
+//# sourceMappingURL=vk-history.js.map

package/dist/core/vk-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vk-history.js","names":[],"sources":["../../src/core/vk-history.ts"],"sourcesContent":["import { createBrowserHistory } from \"@tanstack/history\";\nimport {\n\tparseHashLocation,\n\tparseHashPayload,\n\treadHrefFromHash,\n\tserializeHashPayload,\n\twriteHashParams,\n} from \"./hash-params.ts\";\n\n/**\n * VK history: the same trick TanStack's own hash history uses —\n * `createBrowserHistory` with swapped `parseLocation`/`createHref` — so we\n * inherit blockers with rollback, popstate classification, throttling and\n * TSR index/key stamping.\n *\n * Modes (parity with the old router's three factories):\n * - `\"hash\"` (default) → old `createHashRouter`: the hash IS the location\n *   (`#/item/7?tab=x`).\n * - `\"hash-param\"` → old `createHashParamRouter`: the whole router\n *   location rides in one hash query param (`#?path=%2Fitem%2F7`), foreign\n *   hash params (launch params, UTM) are preserved next to it, and the\n *   real `location.search` is never touched.\n *\n * Deep links written by the OTHER mode resolve too (legacy tolerance).\n * `\"browser\"` → pass TanStack's default history instead (omit `history`\n * in createRouter) — old `createBrowserRouter`.\n */\n\nexport const DEFAULT_PATH_PARAM = \"path\";\n\nexport type VkHistoryMode = \"hash\" | \"hash-param\";\n\ninterface HistoryState {\n\tkey: string;\n\t__TSR_key: string;\n\t__TSR_index: number;\n}\n\nexport interface VkHistoryOptions {\n\twindow?: Window;\n\t/** Hash query param carrying the router location (hash-param mode). */\n\tpathParam?: string;\n\t/** URL mode. Default `\"hash\"`. */\n\tmode?: VkHistoryMode;\n}\n\n/** The history plus the payload codecs the bridge sync layer needs. */\nexport function createVkHistory(options: VkHistoryOptions = {}) {\n\tconst win = options.window ?? window;\n\tconst pathParam = options.pathParam ?? DEFAULT_PATH_PARAM;\n\tconst mode = options.mode ?? \"hash\";\n\n\tlet lastIndex = -1;\n\n\t/**\n\t * A history entry without TanStack state (manual hash edit / foreign\n\t * pushState) gets a FRESH index = lastIndex + 1, so popstate classifies\n\t * it as FORWARD — the entry behaves like a push (an entry parsed as\n\t * index 0 would desync any parallel stack mirror).\n\t */\n\tconst stampMissingState = (): HistoryState => {\n\t\tlastIndex += 1;\n\t\tconst key = Math.random().toString(36).slice(2, 8);\n\t\tconst state: HistoryState = { __TSR_index: lastIndex, key, __TSR_key: key };\n\t\twin.history.replaceState(state, \"\", win.location.href);\n\t\treturn state;\n\t};\n\n\tconst initStamp = (): HistoryState => {\n\t\tconst rawState = win.history.state as HistoryState | null;\n\t\tif (rawState?.__TSR_key) {\n\t\t\tif (rawState.__TSR_index > lastIndex) {\n\t\t\t\tlastIndex = rawState.__TSR_index;\n\t\t\t}\n\t\t\treturn rawState;\n\t\t}\n\t\treturn stampMissingState();\n\t};\n\n\tif (mode === \"hash-param\") {\n\t\tconst parseLocation = () => {\n\t\t\tconst state = initStamp();\n\t\t\tconst href = readHrefFromHash(win, pathParam);\n\t\t\tconst url = new URL(href, win.location.origin);\n\t\t\treturn {\n\t\t\t\thref,\n\t\t\t\tpathname: url.pathname,\n\t\t\t\tsearch: url.search,\n\t\t\t\thash: url.hash,\n\t\t\t\tstate,\n\t\t\t};\n\t\t};\n\n\t\treturn {\n\t\t\thistory: createBrowserHistory({\n\t\t\t\twindow: win,\n\t\t\t\tparseLocation,\n\t\t\t\tcreateHref: href => writeHashParams(win, pathParam, href),\n\t\t\t}),\n\t\t\t/** Hash content for a router href — the SetLocation payload. */\n\t\t\tserializePayload: (href: string) => serializeHashPayload(win, pathParam, href),\n\t\t\t/** Router href from a SetLocation/ChangeFragment payload. */\n\t\t\tparsePayload: (payload: string) => parseHashPayload(payload, pathParam),\n\t\t\t/** Router href from the current document hash. */\n\t\t\tparseCurrentHash: () => readHrefFromHash(win, pathParam),\n\t\t};\n\t}\n\n\t// hash mode: the hash IS the location; legacy `#?path=` links resolve too\n\tconst hrefFromHash = (): string => {\n\t\tconst hash = win.location.hash;\n\t\tif (hash.startsWith(\"#?\")) {\n\t\t\t// legacy hash-param deep link — resolve the path param out of it\n\t\t\treturn new URLSearchParams(hash.slice(2)).get(pathParam) ?? \"/\";\n\t\t}\n\t\treturn hash.length > 1 ? hash.slice(1) : \"/\";\n\t};\n\tconst parseLocation = () => {\n\t\tconst state = initStamp();\n\t\tconst href = hrefFromHash();\n\t\tconst url = new URL(href, win.location.origin);\n\t\treturn {\n\t\t\thref,\n\t\t\tpathname: url.pathname,\n\t\t\tsearch: url.search,\n\t\t\thash: url.hash,\n\t\t\tstate,\n\t\t};\n\t};\n\n\treturn {\n\t\thistory: createBrowserHistory({\n\t\t\twindow: win,\n\t\t\tparseLocation,\n\t\t\tcreateHref: href => `${win.location.pathname}${win.location.search}#${href}`,\n\t\t}),\n\t\t/** Hash content for a router href — the SetLocation payload. */\n\t\tserializePayload: (href: string) => href,\n\t\t/** Router href from a SetLocation/ChangeFragment payload. */\n\t\tparsePayload: (payload: string) => parseHashLocation(payload),\n\t\t/** Router href from the current document hash. */\n\t\tparseCurrentHash: hrefFromHash,\n\t};\n}\n\nexport type VkHistory = ReturnType<typeof createVkHistory>;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA4BA,MAAa,qBAAqB;;AAmBlC,SAAgB,gBAAgB,UAA4B,CAAC,GAAG;CAC/D,MAAM,MAAM,QAAQ,UAAU;CAC9B,MAAM,YAAY,QAAQ,aAAA;CAC1B,MAAM,OAAO,QAAQ,QAAQ;CAE7B,IAAI,YAAY;;;;;;;CAQhB,MAAM,0BAAwC;EAC7C,aAAa;EACb,MAAM,MAAM,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC;EACjD,MAAM,QAAsB;GAAE,aAAa;GAAW;GAAK,WAAW;EAAI;EAC1E,IAAI,QAAQ,aAAa,OAAO,IAAI,IAAI,SAAS,IAAI;EACrD,OAAO;CACR;CAEA,MAAM,kBAAgC;EACrC,MAAM,WAAW,IAAI,QAAQ;EAC7B,IAAI,UAAU,WAAW;GACxB,IAAI,SAAS,cAAc,WAC1B,YAAY,SAAS;GAEtB,OAAO;EACR;EACA,OAAO,kBAAkB;CAC1B;CAEA,IAAI,SAAS,cAAc;EAC1B,MAAM,sBAAsB;GAC3B,MAAM,QAAQ,UAAU;GACxB,MAAM,OAAO,iBAAiB,KAAK,SAAS;GAC5C,MAAM,MAAM,IAAI,IAAI,MAAM,IAAI,SAAS,MAAM;GAC7C,OAAO;IACN;IACA,UAAU,IAAI;IACd,QAAQ,IAAI;IACZ,MAAM,IAAI;IACV;GACD;EACD;EAEA,OAAO;GACN,SAAS,qBAAqB;IAC7B,QAAQ;IACR;IACA,aAAY,SAAQ,gBAAgB,KAAK,WAAW,IAAI;GACzD,CAAC;;GAED,mBAAmB,SAAiB,qBAAqB,KAAK,WAAW,IAAI;;GAE7E,eAAe,YAAoB,iBAAiB,SAAS,SAAS;;GAEtE,wBAAwB,iBAAiB,KAAK,SAAS;EACxD;CACD;CAGA,MAAM,qBAA6B;EAClC,MAAM,OAAO,IAAI,SAAS;EAC1B,IAAI,KAAK,WAAW,IAAI,GAEvB,OAAO,IAAI,gBAAgB,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,KAAK;EAE7D,OAAO,KAAK,SAAS,IAAI,KAAK,MAAM,CAAC,IAAI;CAC1C;CACA,MAAM,sBAAsB;EAC3B,MAAM,QAAQ,UAAU;EACxB,MAAM,OAAO,aAAa;EAC1B,MAAM,MAAM,IAAI,IAAI,MAAM,IAAI,SAAS,MAAM;EAC7C,OAAO;GACN;GACA,UAAU,IAAI;GACd,QAAQ,IAAI;GACZ,MAAM,IAAI;GACV;EACD;CACD;CAEA,OAAO;EACN,SAAS,qBAAqB;GAC7B,QAAQ;GACR;GACA,aAAY,SAAQ,GAAG,IAAI,SAAS,WAAW,IAAI,SAAS,OAAO,GAAG;EACvE,CAAC;;EAED,mBAAmB,SAAiB;;EAEpC,eAAe,YAAoB,kBAAkB,OAAO;;EAE5D,kBAAkB;CACnB;AACD"}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,8 @@
+import { parseHashLocation, parseHashPayload, readHashParams, readHrefFromHash, serializeHashLocation, serializeHashPayload, writeHashParams } from "./core/hash-params.js";
+import { DEFAULT_PATH_PARAM, createVkHistory } from "./core/vk-history.js";
+import { applyLocation, initialPanelsStack, panelsHistoryOf } from "./core/panels-stack.js";
+import { POPOUT_STATE_KEY, readPopoutState } from "./core/state-keys.js";
+import { normalizeBridgeEvent } from "./core/bridge-like.js";
+import { createBridgeSync } from "./core/bridge-sync.js";
+import { createSwipeBackManager } from "./core/swipe-back.js";
+export { DEFAULT_PATH_PARAM, POPOUT_STATE_KEY, applyLocation, createBridgeSync, createSwipeBackManager, createVkHistory, initialPanelsStack, normalizeBridgeEvent, panelsHistoryOf, parseHashLocation, parseHashPayload, readHashParams, readHrefFromHash, readPopoutState, serializeHashLocation, serializeHashPayload, writeHashParams };

package/dist/preset/app.d.ts

@@ -0,0 +1,35 @@
+import { AppHandle } from "./builders.js";
+//#region src/preset/app.d.ts
+/**
+ * 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 declare function AppRootShell({ app, inflate }: {
+  app: AppHandle;
+  inflate?: boolean;
+}): import("react").JSX.Element;
+/**
+ * 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 declare function useActiveStory(app: AppHandle): string | null;
+/**
+ * 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 declare function useInflate(app: AppHandle, enabled?: boolean): void;
+//#endregion
+//# sourceMappingURL=app.d.ts.map

package/dist/preset/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","names":[],"sources":["../../src/preset/app.tsx"],"mappings":";;;;;;;;;;;;;wBA2DgB,eAAe,KAAK;EAAoB,KAAK;EAAW;oBAAmB,IAAA;;;;;;;;wBA4B3E,eAAe,KAAK;;;;;;;;wBAiBpB,WAAW,KAAK,WAAW"}

package/dist/preset/app.js

@@ -0,0 +1,134 @@
+import { looseRouteOf } from "../core/loose-route.js";
+import { VkView, storyKeyOf } from "../vkui/vk-view.js";
+import { Modals } from "../vkui/modals.js";
+import { Popouts } from "../vkui/popouts.js";
+import { NotFound } from "../vkui/not-found.js";
+import { deriveInflateChain, interpolatePath } from "./inflate.js";
+import { useRouter, useRouterState } from "@tanstack/react-router";
+import { useEffect, useRef } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/preset/app.tsx
+/**
+* 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).
+*/
+function owningViewIdOf(matches, views) {
+	if (matches.some((match) => match.status === "notFound" || match._notFound === true)) 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 !== void 0) 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.
+*/
+function AppRootShell({ app, inflate = true }) {
+	useInflate(app, inflate);
+	const views = Object.values(app.views);
+	const activeViewId = useRouterState({ select: (state) => owningViewIdOf(state.matches, views) });
+	const activeView = activeViewId === null ? void 0 : Object.values(app.views).find((view) => view.id === activeViewId);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		activeView !== void 0 ? /* @__PURE__ */ jsx(VkView, { view: activeView }) : /* @__PURE__ */ jsx(NotFound, {}),
+		/* @__PURE__ */ jsx(Modals, { entries: app.modals }),
+		/* @__PURE__ */ jsx(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.
+*/
+function useActiveStory(app) {
+	const views = Object.values(app.views);
+	return useRouterState({ select: (state) => {
+		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.
+*/
+function useInflate(app, enabled = true) {
+	const router = useRouter();
+	const snapshot = useRouterState({ select: (state) => {
+		let panelKey = null;
+		let panelPath = null;
+		const modalPaths = [];
+		for (let i = state.matches.length - 1; i >= 0; i--) {
+			const routeId = state.matches[i]?.routeId;
+			if (routeId === void 0) continue;
+			const route = looseRouteOf(router, routeId);
+			const staticData = route?.options.staticData;
+			if (staticData?.modal !== void 0 && route !== void 0) {
+				if (route.fullPath !== void 0) modalPaths.push(route.fullPath);
+			}
+			if (staticData?.panel !== void 0) {
+				panelKey = staticData.panel;
+				panelPath = route?.fullPath ?? null;
+				break;
+			}
+		}
+		return {
+			status: state.status,
+			index: state.location.state?.__TSR_index ?? 0,
+			href: state.location.href,
+			panelKey,
+			panelPath,
+			modalPaths: modalPaths.toReversed(),
+			deepestParams: state.matches[state.matches.length - 1]?.params ?? {}
+		};
+	} });
+	const done = useRef(false);
+	useEffect(() => {
+		if (done.current || !enabled || snapshot.status !== "idle") return;
+		done.current = true;
+		if (snapshot.index > 0 || snapshot.panelKey === null) return;
+		const target = app.panels[snapshot.panelKey];
+		if (target === void 0) return;
+		const ordered = Object.values(app.panels).filter((panel) => panel.viewId === target.viewId);
+		let chain = deriveInflateChain(ordered, target.routeId, snapshot.deepestParams);
+		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;
+		(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 });
+		})();
+	});
+}
+//#endregion
+export { AppRootShell, owningViewIdOf, useActiveStory, useInflate };
+
+//# sourceMappingURL=app.js.map

package/dist/preset/app.js.map

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

package/dist/preset/builders.d.ts

@@ -0,0 +1,209 @@
+import { ModalEntry } from "../vkui/modals.js";
+import { PopoutEntry } from "../vkui/popouts.js";
+import { PanelDefinition } from "./define-panel.js";
+import { ViewDefinition } from "./define-view.js";
+import { AnyRoute, RouteMask } from "@tanstack/react-router";
+import { ComponentType, LazyExoticComponent, ReactNode } from "react";
+//#region src/preset/builders.d.ts
+/**
+ * Typed builders that generate the TanStack route tree in the /vkui
+ * convention: view = pathless layout route, panels = path children, modals
+ * = sibling child routes of their panel (chained modals are siblings — the
+ * host closes one before opening the next). Local route modals are
+ * URL-masked back to their panel (`app.routeMasks` → `createRouter`'s
+ * `routeMasks`): the address stays at the panel while any modal level is
+ * open, the raw modal path still deep-links (parsing is never masked), and
+ * the mask survives reload (history.state.__tempLocation). Global modals
+ * are rendered by the host from `?modal=<id>` on any panel (deep-linkable;
+ * the imperative open carries its own mask). Every node accepts raw
+ * TanStack options (`loader`, `beforeLoad`, `validateSearch`, `lazy`, …)
+ * passed through untouched, and the underlying routes stay reachable for
+ * escape hatches.
+ */
+/**
+ * Route options with the builder-managed fields removed. `AnyRoute`'s
+ * options carry TanStack's generics pre-instanced, so this stays a plain
+ * structural type; the registered route tree provides the real typing for
+ * navigation, loaders and search.
+ */
+export type LooseRouteOptions = Partial<Omit<NonNullable<AnyRoute>["options"], "getParentRoute" | "path" | "id">>;
+/** A renderable modal entry component — plain or React.lazy. */
+export type ModalEntryComponent = ComponentType | LazyExoticComponent<ComponentType>;
+/**
+ * A declared modal: a renderable component, or a component with ITS OWN
+ * nested modals. Nested modals are child routes of their parent modal and
+ * stack ON TOP of it (back unwinds the stack instead of closing everything).
+ */
+export interface ModalDeclaration {
+  component: ModalEntryComponent;
+  modals?: Record<string, ModalComponent>;
+}
+/** What a modals record accepts: either shape. */
+export type ModalComponent = ModalEntryComponent | ModalDeclaration;
+export interface PanelOptions extends LooseRouteOptions {
+  /**
+   * Chunk splitting without file-based routing: resolves to the panel's
+   * component. The preset bridges it into TanStack's `route.lazy()` (which
+   * expects a `{ options }`-shaped lazy route) and hands the caller the
+   * panel's route id. The payload is either `{ component }` or a dynamic
+   * import namespace with a `default` export (`lazy: () => import("./feed")`).
+   */
+  lazy?: PanelLazy;
+  /** Route-level modals: sibling child routes of this panel (recursible). */
+  modals?: Record<string, ModalComponent>;
+  /**
+   * Panel-local popouts: resolved BEFORE the global registry while this
+   * panel is the deepest matched one. The same id declared globally is a
+   * dev-time error.
+   */
+  popouts?: Record<string, PopoutEntry["Component"]>;
+}
+/**
+ * The lazy loader shape: an explicit `{ component }` payload or a dynamic
+ * import namespace whose `default` export is the component. The arrow keeps
+ * the chunk out of the main graph; the union keeps call sites terse
+ * (`lazy: () => import("./feed")`).
+ */
+export type PanelLazy = (routeId: string) => Promise<{
+  component: ComponentType;
+} | {
+  default: ComponentType;
+}>;
+export interface ViewOptions extends LooseRouteOptions {
+  /**
+   * Panels of the view: raw inline options (small apps, wrap `lazy` in
+   * `panel()`) or a {@link PanelDefinition} from `definePanel` — the
+   * recommended shape, whose handle lives in a leaf module so panel chunks
+   * never import the app back.
+   */
+  panels: Record<string, PanelOptions | PanelDefinition>;
+}
+export interface PanelHandle<TParams = Record<string, string>, TSearch = Record<string, unknown>, TLoaderData = unknown> {
+  /** Full TanStack route id — the `from` for the /react data hooks. */
+  readonly routeId: string;
+  /** URL path of the panel. */
+  path: string;
+  /** The view route id the panel belongs to. */
+  viewId: string;
+  /** Phantom carrier — the panel's data types for the /react hooks. */
+  readonly types?: {
+    params: TParams;
+    search: TSearch;
+    loaderData: TLoaderData;
+  };
+}
+/** `view:feed` + panel `post/$id` → the runtime id `/view:feed/post/$id`. */
+export type PanelRouteId<V extends string, P extends string> = P extends "index" ? `/view:${V}/` : `/view:${V}/${P}`;
+/** `$id`-segments of a panel path → the params object type. */
+export type ParamsOfKey<P extends string> = P extends `${infer Head}/${infer Rest}` ? ParamsOfSegment<Head> & ParamsOfKey<Rest> : ParamsOfSegment<P>;
+type ParamsOfSegment<S extends string> = S extends `$${infer Name}` ? { [K in Name]: string; } : {};
+export type SearchOf<O extends PanelOptions> = O extends {
+  validateSearch: (search: never) => infer S;
+} ? S : Record<string, never>;
+export type LoaderDataOf<O extends PanelOptions> = O extends {
+  loader: (...args: never[]) => infer L;
+} ? Awaited<L> : unknown;
+/**
+ * The options a panels-map member declares — a {@link PanelDefinition}
+ * carries them in its third type parameter, raw inline options ARE the
+ * options.
+ */
+export type OptionsOf<M extends PanelOptions | PanelDefinition> = M extends PanelDefinition<any, any, infer O> ? O : M;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
+/**
+ * The declared panels map with LITERAL route ids and option-derived data
+ * types: `app.panels["feed/post/$id"]` autocompletes, is never undefined,
+ * its `routeId` is the literal runtime id, and `usePanelParams(handle)` &
+ * co. resolve params / search / loaderData from the declared options.
+ */
+export type PanelHandlesOf<TViews extends Record<string, ViewOptions>> = UnionToIntersection<{ [V in keyof TViews & string]: { [P in keyof TViews[V]["panels"] & string as `${V}/${P}`]: PanelHandle<ParamsOfKey<P>, SearchOf<OptionsOf<TViews[V]["panels"][P]>>, LoaderDataOf<OptionsOf<TViews[V]["panels"][P]>>> & {
+  readonly routeId: PanelRouteId<V, P>;
+}; }; }[keyof TViews & string]>;
+export interface AppHandle {
+  routeTree: AnyRoute;
+  /** Modal entries for the `<Modals>` host. */
+  modals: ModalEntry[];
+  /**
+   * Declarative URL masks for the local route modals — pass into
+   * `createRouter({ routeMasks })`, or a modal open puts its own path in
+   * the address bar.
+   */
+  routeMasks: RouteMask<any>[];
+  /** Popout registry for the `<Popouts>` host. */
+  popouts: PopoutEntry[];
+  /** Panel handles keyed by `${viewKey}/${panelKey}`. */
+  panels: Record<string, PanelHandle>;
+  views: Record<string, AnyRoute>;
+  /** Inflate flag (see {@link AppOptions.inflate}). */
+  inflate: boolean;
+}
+/**
+ * The app handle with the DECLARED panels shape: literal keys
+ * (`app.panels["feed/post/$id"]` — autocomplete, never undefined) and
+ * literal route ids that drive the /react hooks' typing. Structurally an
+ * AppHandle, so it flows into AppRootShell / useInflate / deriveInflateChain.
+ */
+export interface TypedAppHandle<TViews extends Record<string, ViewOptions>> {
+  routeTree: AnyRoute;
+  modals: ModalEntry[];
+  routeMasks: RouteMask<any>[];
+  popouts: PopoutEntry[];
+  panels: PanelHandlesOf<TViews>;
+  views: Record<string, AnyRoute>;
+  inflate: boolean;
+}
+export interface AppOptionsBase {
+  /**
+   * Custom root shell (renders inside the router context). Defaults to
+   * AppRootShell: the active view + modal/popout hosts. Deliberately
+   * LOOSE (`AppHandle`, not `TypedAppHandle<TViews>`): a contextual type
+   * mentioning TViews makes the app const's own initializer circular
+   * (TS7022) — typed panel handles are read from the RETURN value.
+   */
+  root?: (props: {
+    app: AppHandle;
+  }) => ReactNode;
+  /** Global modals: `?modal=<id>` opens them from any panel. */
+  modals?: Record<string, ModalEntryComponent>;
+  /** Global popout registry. */
+  popouts?: Record<string, PopoutEntry["Component"]>;
+  /**
+   * Inflate (default `true`): a cold start on a deep-linked panel replays
+   * the panel flow before it, so back walks the natural chain.
+   */
+  inflate?: boolean;
+}
+export interface AppOptions<TViews extends Record<string, ViewOptions> = Record<string, ViewOptions>> extends AppOptionsBase {
+  views: TViews;
+}
+/** `createApp` with `defineView` hubs — handles live on the panel definitions. */
+export interface AppDefinitionOptions extends AppOptionsBase {
+  views: readonly ViewDefinition[] | Record<string, ViewDefinition>;
+}
+/**
+ * Type-erasing wrapper for `lazy` panel chunks. The chunk module imports
+ * the app back for its typed panel handles — passing its component types
+ * straight into `views` makes the app's own inference circular (the
+ * component's inferred type depends on `app.panels`). `panel()` erases the
+ * chunk to `{ component: ComponentType }` at the boundary.
+ *
+ * ```tsx
+ * lazy: panel(() => import("./panels/feed").then(m => ({ component: m.FeedPanel })))
+ * lazy: panel(routeId => import("./panels/post.lazy").then(m => m.postLazy(routeId)))
+ * ```
+ */
+/**
+ * Identity eraser for RAW inline `lazy` loaders (small apps declaring panels
+ * directly in `createApp`): the chunk modules import the app back for their
+ * handles, so the loader's return type must not carry the chunk's component
+ * type into the app's own inference. Apps using `definePanel` don't need it
+ * — the definition boundary already erases.
+ */
+export declare function panel(load: PanelLazy): PanelLazy;
+/** Definition-form views: the typed handles live on the panel definitions. */
+export declare function createApp(options: AppDefinitionOptions): AppHandle;
+/** Raw inline options: `app.panels` is fully typed from the declared tree. */
+export declare function createApp<const TViews extends Record<string, ViewOptions>>(options: AppOptions<TViews>): TypedAppHandle<TViews>;
+//#endregion
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/dist/preset/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","names":[],"sources":["../../src/preset/builders.tsx"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;YAoCY,oBAAoB,QAC/B,KAAK,YAAY;;YAIN,sBAAsB,gBAAgB,oBAAoB;;;;;;iBAOrD;EAChB,WAAW;EACX,SAAS,eAAe;;;YAIb,iBAAiB,sBAAsB;iBAElC,qBAAqB;;;;;;;;EAQrC,OAAO;;EAEP,SAAS,eAAe;;;;;;EAMxB,UAAU,eAAe;;;;;;;;YASd,aACX,oBACI;EAAU,WAAW;;EAAoB,SAAS;;iBAEtC,oBAAoB;;;;;;;EAOpC,QAAQ,eAAe,eAAe;;iBAGtB,YAChB,UAAU,wBACV,UAAU,yBACV;;WAGS;;EAET;;EAEA;;WAES;IAAU,QAAQ;IAAS,QAAQ;IAAS,YAAY;;;;YAItD,aAAa,kBAAkB,oBAAoB,6BACnD,gBACA,KAAK;;YAGL,YAAY,oBAAoB,mBAAmB,cAAc,SAC1E,gBAAgB,QAAQ,YAAY,QACpC,gBAAgB;KACd,gBAAgB,oBAAoB,oBAAoB,YAAY,KAAK;YAClE,SAAS,UAAU,gBAAgB;EAC9C,iBAAiB,wBAAwB;IAEvC,IACA;YACS,aAAa,UAAU,gBAAgB;EAClD,YAAY,wBAAwB;IAElC,QAAQ;;;;;;YAQC,UAAU,UAAU,eAAe,mBAC9C,UAAU,gCAAgC,KAAK,IAAI;KAE/C,oBAAoB,MAAM,qBAAqB,KAAK,8BACxD,WAAW,cAET;;;;;;;YASS,eAAe,eAAe,eAAe,gBAAgB,uBAEtE,WAAW,qBACV,WAAW,OAAO,4BAA4B,KAAK,MAAM,YACzD,YAAY,IACZ,SAAS,UAAU,OAAO,aAAa,MACvC,aAAa,UAAU,OAAO,aAAa;WAElC,SAAS,aAAa,GAAG;cAG7B;iBAGQ;EAChB,WAAW;;EAEX,QAAQ;;;;;;EAMR,YAAY;;EAEZ,SAAS;;EAET,QAAQ,eAAe;EACvB,OAAO,eAAe;;EAEtB;;;;;;;;iBASgB,eAAe,eAAe,eAAe;EAC7D,WAAW;EACX,QAAQ;EACR,YAAY;EACZ,SAAS;EACT,QAAQ,eAAe;EACvB,OAAO,eAAe;EACtB;;iBAGgB;;;;;;;;EAQhB,QAAQ;IAAS,KAAK;QAAgB;;EAEtC,SAAS,eAAe;;EAExB,UAAU,eAAe;;;;;EAKzB;;iBAGgB,WAChB,eAAe,eAAe,eAAe,eAAe,sBACnD;EACT,OAAO;;;iBAIS,6BAA6B;EAC7C,gBAAgB,mBAAmB,eAAe;;;;;;;;;;;;;;;;;;;;;wBAsBnC,MAAM,MAAM,YAAY;;wBA6GxB,UAAU,SAAS,uBAAuB;;wBAE1C,gBAAgB,eAAe,eAAe,cAC7D,SAAS,WAAW,UAClB,eAAe"}