hallo-kit 0.3.0

package/src/hooks/useDevice.ts

@@ -0,0 +1,63 @@
+'use client'
+
+import {
+	createContext,
+	createElement,
+	useContext,
+	useEffect,
+	useState,
+	type ReactNode,
+} from 'react'
+
+import Cookies from 'js-cookie'
+
+import { KitCookies } from '../config'
+
+// Тип устройства по ширине вьюпорта. Граница — Tailwind `md` (768px): < 768 → mobile.
+export type DeviceType = 'mobile' | 'desktop'
+
+const MOBILE_QUERY = '(max-width: 767px)'
+
+// Дефолт 'desktop' — если компонент вне DeviceProvider.
+const DeviceContext = createContext<DeviceType>('desktop')
+
+// Кука живёт год, доступна на всех путях, переживает навигации (Lax). Сервер читает её
+// в getInitialDevice → SSR сразу отдаёт правильную версию.
+const COOKIE_OPTS = { expires: 365, sameSite: 'lax', path: '/' } as const
+
+// Провайдер. initialDevice приходит с СЕРВЕРА: сперва из cookie `device` (её клиент пишет
+// ниже по реальной ширине), иначе по User-Agent — см. getInitialDevice в @/lib/device.
+// Поэтому SSR и первый клиентский рендер СОВПАДАЮТ → нет вспышки/прыжков desktop↔mobile
+// при загрузке и F5. После маунта matchMedia сверяет реальную ширину (десктоп с узким
+// окном, ресайз, поворот), правит state И ОБНОВЛЯЕТ КУКУ — чтобы следующий SSR был точным.
+export function DeviceProvider({
+	initialDevice,
+	children,
+}: {
+	initialDevice: DeviceType
+	children: ReactNode
+}) {
+	const [device, setDevice] = useState<DeviceType>(initialDevice)
+
+	useEffect(() => {
+		const mql = window.matchMedia(MOBILE_QUERY)
+		// setState с тем же значением — no-op (ре-рендера нет). Куку пишем всегда: на первом
+		// визите так СИДИМ её (на сервере был UA-fallback), дальше держим в синхроне с шириной.
+		const apply = () => {
+			const next: DeviceType = mql.matches ? 'mobile' : 'desktop'
+			setDevice(next)
+			Cookies.set(KitCookies.DEVICE, next, COOKIE_OPTS)
+		}
+		apply()
+		mql.addEventListener('change', apply)
+		return () => mql.removeEventListener('change', apply)
+	}, [])
+
+	return createElement(DeviceContext.Provider, { value: device }, children)
+}
+
+// Текущий тип устройства (реактивно на resize). Использовать для УСЛОВНОГО рендера
+// версий (mobile/desktop), чтобы неактивная версия не попадала в DOM.
+export function useDevice(): DeviceType {
+	return useContext(DeviceContext)
+}

package/src/hooks/useIsTelegramMiniApp.ts

@@ -0,0 +1,17 @@
+'use client'
+
+import { useSyncExternalStore } from 'react'
+
+import { getTelegramWebApp } from './useTelegram'
+
+const subscribe = () => () => {}
+
+/** true только внутри Telegram Mini App (есть `Telegram.WebApp`), не обычный браузер.
+ *  Читаем внешнее значение через useSyncExternalStore (SSR-safe, без setState-в-эффекте). */
+export function useIsTelegramMiniApp(): boolean {
+	return useSyncExternalStore(
+		subscribe,
+		() => !!getTelegramWebApp(),
+		() => false
+	)
+}

package/src/hooks/useIsTouch.ts

@@ -0,0 +1,23 @@
+'use client'
+
+import { useSyncExternalStore } from 'react'
+
+// Сенсорный ввод (грубый указатель — палец, не мышь). Через useSyncExternalStore (SSR-safe):
+// на сервере false, на клиенте — реальное значение matchMedia, с подпиской на смену
+// (например, планшет с подключённой/отключённой мышью). Нужен, чтобы показывать свайп-хинты
+// только там, где свайп реально доступен.
+const QUERY = '(pointer: coarse)'
+
+function subscribe(onChange: () => void) {
+	if (typeof window === 'undefined') return () => {}
+	const mq = window.matchMedia(QUERY)
+	mq.addEventListener('change', onChange)
+	return () => mq.removeEventListener('change', onChange)
+}
+
+const getSnapshot = () => window.matchMedia(QUERY).matches
+const getServerSnapshot = () => false
+
+export function useIsTouch(): boolean {
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}

package/src/hooks/useKeyboardOpen.ts

@@ -0,0 +1,35 @@
+'use client'
+
+import { useSyncExternalStore } from 'react'
+
+// Открыта ли экранная клавиатура. Определяем по сжатию visual viewport относительно
+// layout viewport: при фокусе на поле мобильный браузер / Telegram MiniApp поднимает
+// клавиатуру и уменьшает visualViewport.height, тогда как window.innerHeight (layout)
+// остаётся прежним. Порог отсекает мелкие расхождения (адресная строка, тулбары).
+//
+// SSR-safe (useSyncExternalStore): на сервере и в отсутствие visualViewport → false.
+// Нужно, чтобы прятать нижний таб-бар, пока идёт набор (иначе sticky-бар пиннится к низу
+// видимой области ПОВЕРХ поля ввода — см. TelegramBottomNav).
+const KEYBOARD_THRESHOLD_PX = 150
+
+const subscribe = (onChange: () => void) => {
+	const vv = typeof window !== 'undefined' ? window.visualViewport : null
+	if (!vv) return () => {}
+	// resize — открытие/закрытие клавиатуры; scroll — сдвиг visual viewport при ней.
+	vv.addEventListener('resize', onChange)
+	vv.addEventListener('scroll', onChange)
+	return () => {
+		vv.removeEventListener('resize', onChange)
+		vv.removeEventListener('scroll', onChange)
+	}
+}
+
+const getSnapshot = (): boolean => {
+	const vv = typeof window !== 'undefined' ? window.visualViewport : null
+	if (!vv) return false
+	return window.innerHeight - vv.height > KEYBOARD_THRESHOLD_PX
+}
+
+export function useKeyboardOpen(): boolean {
+	return useSyncExternalStore(subscribe, getSnapshot, () => false)
+}

package/src/hooks/useMediaQuery.ts

@@ -0,0 +1,24 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+// Реактивное совпадение произвольного media-query. SSR-safe: и на сервере, и на ПЕРВОМ
+// клиентском рендере возвращает false → гидрация без mismatch; сразу после маунта
+// matchMedia проставляет реальное значение (и следит за resize/поворотом).
+//
+// Для раскладки mobile/desktop (порог 767px) бери useDevice — он SSR-точный через cookie
+// и не мигает. useMediaQuery — для порогов, которых у useDevice нет (напр. очень узкие
+// экраны ≤360px), где мгновенная точность на первом кадре некритична.
+export function useMediaQuery(query: string): boolean {
+	const [matches, setMatches] = useState(false)
+
+	useEffect(() => {
+		const mql = window.matchMedia(query)
+		const apply = () => setMatches(mql.matches)
+		apply()
+		mql.addEventListener('change', apply)
+		return () => mql.removeEventListener('change', apply)
+	}, [query])
+
+	return matches
+}

package/src/hooks/usePlatform.ts

@@ -0,0 +1,102 @@
+'use client'
+
+import { createContext, useContext } from 'react'
+
+import { getTelegram } from './useTelegram'
+
+export type PlatformType = 'telegram' | 'browser'
+
+// Launch-параметры Mini App (tgWebApp* в query/hash) — их подставляет ТОЛЬКО запуск
+// мини-аппа, в inapp-браузере Telegram их нет. Нужны как ранний сигнал, пока SDK ещё
+// не распарсил initData (первый рендер до/во время загрузки telegram-web-app.js).
+function hasMiniAppLaunchParams(): boolean {
+	if (typeof window === 'undefined') return false
+	const href = window.location?.href || ''
+	return /[?#&]tgWebApp(Data|Version|Platform)=/i.test(href)
+}
+
+// Мок платформы для локальной отладки MiniApp-веток в браузере (таб-бар, telegram-only и т.д.).
+// Включается в .env.local: NEXT_PUBLIC_MOCK_TELEGRAM=true. В прод-окружении переменной нет.
+const MOCK_TELEGRAM = process.env.NEXT_PUBLIC_MOCK_TELEGRAM === 'true'
+
+// 'telegram' = ТОЛЬКО настоящий Mini App: initData с user (SDK) либо launch-параметры
+// tgWebApp*. UA «Telegram» и window.TelegramWebviewProxy сигналами НЕ являются — они
+// есть и в inapp-браузере Telegram (открытие обычной ссылки), где нет ни initData,
+// ни сессии: такой «telegram» давал фейковую авторизацию и цикл login↔home.
+function computePlatform(): PlatformType {
+	if (MOCK_TELEGRAM) return 'telegram'
+	return getTelegram() || hasMiniAppLaunchParams() ? 'telegram' : 'browser'
+}
+
+// ── Внешнее хранилище платформы ──────────────────────────────────────────────
+// SDK Telegram грузится по сети со стороннего домена (см. лоадер в layout.tsx), поэтому
+// на первом клиентском рендере window.Telegram может ещё не существовать. Раньше здесь
+// стояла пустая подписка: значение считалось один раз и застревало на 'browser' навсегда,
+// даже когда SDK через мгновение приезжал. Мини-апп в этом случае оставался без маркера
+// сессии, и сервер уводил его на /login — «раз через раз», в зависимости от того, успел
+// ли скрипт до гидрации. Теперь ждём SDK и уведомляем подписчиков.
+const POLL_INTERVAL_MS = 100
+const POLL_TIMEOUT_MS = 10_000
+
+let cachedPlatform: PlatformType | null = null
+const listeners = new Set<() => void>()
+let stopWaiting: (() => void) | null = null
+
+/** Снимок платформы. Значение стабильно: 'telegram' обратно в 'browser' не превращается. */
+export function getPlatform(): PlatformType {
+	if (cachedPlatform === null) {
+		cachedPlatform = computePlatform()
+	}
+
+	return cachedPlatform
+}
+
+function waitForTelegram(): void {
+	if (stopWaiting || cachedPlatform === 'telegram' || typeof window === 'undefined') {
+		return
+	}
+
+	const startedAt = Date.now()
+	const timer = window.setInterval(() => {
+		if (computePlatform() === 'telegram') {
+			cachedPlatform = 'telegram'
+			stopWaiting?.()
+			listeners.forEach((listener) => listener())
+			return
+		}
+
+		// Не крутим таймер вечно: вне Telegram SDK не появится никогда.
+		if (Date.now() - startedAt >= POLL_TIMEOUT_MS) {
+			stopWaiting?.()
+		}
+	}, POLL_INTERVAL_MS)
+
+	stopWaiting = () => {
+		window.clearInterval(timer)
+		stopWaiting = null
+	}
+}
+
+export function subscribePlatform(listener: () => void): () => void {
+	listeners.add(listener)
+	waitForTelegram()
+
+	return () => {
+		listeners.delete(listener)
+	}
+}
+
+/** Снимок для SSR и гидрации: на сервере Telegram-окружения нет. */
+export function getServerPlatform(): PlatformType {
+	return 'browser'
+}
+
+export const PlatformContext = createContext<PlatformType>('browser')
+
+export function usePlatform(): PlatformType {
+	return useContext(PlatformContext)
+}
+
+export function isTelegram(): boolean {
+	return getTelegram() !== null || hasMiniAppLaunchParams()
+}

package/src/hooks/useQueryParams.tsx

@@ -0,0 +1,70 @@
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
+
+export const useQueryParams = () => {
+	const router = useRouter()
+	const pathname = usePathname()
+	const searchParams = useSearchParams()
+
+	const setQuery = (params: Record<string, string | number | undefined>, isReplace?: boolean) => {
+		const currentParams = new URLSearchParams()
+
+		Object.entries(params).forEach((value) => {
+			if (typeof value[1] !== 'undefined') currentParams.set(value[0], value[1].toString())
+			else currentParams.delete(value[0])
+		})
+
+		if (isReplace) return router.replace(`${pathname}?${currentParams.toString()}`)
+		router.push(`${pathname}?${currentParams.toString()}`)
+	}
+
+	const pushQuery = (params: Record<string, string | number | undefined>, isReplace?: boolean) => {
+		const currentParams = new URLSearchParams(searchParams.toString())
+
+		Object.entries(params).forEach((value) => {
+			if (typeof value[1] !== 'undefined') currentParams.set(value[0], value[1].toString())
+		})
+
+		if (isReplace) return router.replace(`${pathname}?${currentParams.toString()}`)
+		router.push(`${pathname}?${currentParams.toString()}`)
+	}
+
+	const getQuery = (key: string) => {
+		const query = searchParams.get(key)
+		return query
+	}
+
+	const getAllQuery = (key: string) => {
+		const query = searchParams.getAll(key)
+		return query
+	}
+
+	const removeQuery = (key: string, isReplace?: boolean) => {
+		const currentParams = new URLSearchParams(searchParams.toString())
+		currentParams.delete(key)
+
+		if (isReplace) return router.replace(`${pathname}?${currentParams.toString()}`)
+		router.push(`${pathname}?${currentParams.toString()}`)
+	}
+
+	const removeAllQuery = (isReplace?: boolean) => {
+		const currentParams = new URLSearchParams()
+
+		if (isReplace) return router.replace(`${pathname}?${currentParams.toString()}`)
+		router.push(`${pathname}?${currentParams.toString()}`)
+	}
+
+	const getAllQueries = () => {
+		const query = searchParams.toString()
+		return { string: query, object: Object.fromEntries(searchParams) }
+	}
+
+	return {
+		setQuery,
+		pushQuery,
+		getQuery,
+		getAllQuery,
+		removeQuery,
+		removeAllQuery,
+		getAllQueries,
+	}
+}

package/src/hooks/useRevealOnce.ts

@@ -0,0 +1,21 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+// Ключи, чьё появление уже сыграло за сессию (пока жив JS).
+const revealedKeys = new Set<string>()
+
+// true — если для этого ключа появление ещё НЕ проигрывалось (первый показ за сессию). После
+// монтирования ключ отмечается отыгранным → повторный заход на страницу вернёт false, и список
+// показывается сразу, без каскада. Значение фиксируется на первом рендере (useState-инициализатор),
+// поэтому не «мигает» при последующих ре-рендерах того же экрана. Без ключа (undefined) —
+// всегда false: каскад выключен (удобно для опционального пропа revealKey).
+export function useRevealOnce(key?: string): boolean {
+	const [play] = useState(() => key != null && !revealedKeys.has(key))
+
+	useEffect(() => {
+		if (key != null) revealedKeys.add(key)
+	}, [key])
+
+	return play
+}

package/src/hooks/useScrolledPast.ts

@@ -0,0 +1,19 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+// true, когда страница проскроллена ниже threshold (px). Слушатель passive; setState
+// с тем же boolean ре-рендер не вызывает, так что на каждый пиксель скролла не рендерим.
+// До гидрации — false (SSR window недоступен), первый эффект сверяет реальную позицию.
+export function useScrolledPast(threshold: number): boolean {
+	const [past, setPast] = useState(false)
+
+	useEffect(() => {
+		const onScroll = () => setPast(window.scrollY > threshold)
+		onScroll()
+		window.addEventListener('scroll', onScroll, { passive: true })
+		return () => window.removeEventListener('scroll', onScroll)
+	}, [threshold])
+
+	return past
+}

package/src/hooks/useSettleOnce.ts

@@ -0,0 +1,26 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+// Ключи, у которых «доводка» уже сыграла за сессию (пока жив JS). Повторный заход на
+// страницу с тем же ключом сразу отдаёт финальное значение — анимация одноразовая.
+const settledKeys = new Set<string>()
+
+// Значение «доезжает» до target через CSS-переход у ПОТРЕБИТЕЛЯ (ширина полосы, дуга donut):
+// на первом показе стартует с 0 → на следующий кадр становится target (переход анимирует),
+// а при повторном заходе (ключ уже отыгран) — сразу target, без анимации. reduced-motion не
+// трогаем: CSS-переход глушит глобальный @media в globals.css.
+export function useSettleOnce(target: number, replayKey?: string): number {
+	const alreadySettled = replayKey != null && settledKeys.has(replayKey)
+	const [value, setValue] = useState(alreadySettled ? target : 0)
+
+	useEffect(() => {
+		const id = requestAnimationFrame(() => {
+			setValue(target)
+			if (replayKey != null) settledKeys.add(replayKey)
+		})
+		return () => cancelAnimationFrame(id)
+	}, [target, replayKey])
+
+	return value
+}

package/src/hooks/useTelegram.tsx

@@ -0,0 +1,57 @@
+import { useEffect, useSyncExternalStore } from 'react'
+
+/** WebApp только если в initData уже есть user (авторизация через TG). */
+export function getTelegram(): TelegramWebApp | null {
+	if (typeof window === 'undefined') return null
+	return window.Telegram?.WebApp?.initDataUnsafe?.user ? window.Telegram.WebApp : null
+}
+
+/** Объект Telegram.WebApp при наличии (в т.ч. без user в initData) — для openLink и т.п. */
+export function getTelegramWebApp(): TelegramWebApp | null {
+	if (typeof window === 'undefined') return null
+	return window.Telegram?.WebApp ?? null
+}
+
+/**
+ * ЕДИНЫЙ источник initData для АВТОРИЗАЦИИ (REST-заголовок InitData + query WS-хабов).
+ * Реальный MiniApp — из SDK. Локальная отладка: NEXT_PUBLIC_MOCK_TELEGRAM=true +
+ * NEXT_PUBLIC_MOCK_TELEGRAM_INITDATA=<строка из DevTools реального Telegram> — тогда API/хабы
+ * авторизуются как из мини-аппа прямо в браузере. Без строки мок остаётся UI-only.
+ */
+export function getInitData(): string | null {
+	const real = getTelegram()?.initData
+	if (real) return real
+	if (process.env.NEXT_PUBLIC_MOCK_TELEGRAM === 'true') {
+		return process.env.NEXT_PUBLIC_MOCK_TELEGRAM_INITDATA || null
+	}
+	return null
+}
+
+// Значение читается из внешней системы (window.Telegram) — берём его через
+// useSyncExternalStore (SSR-safe), без setState-в-эффекте с каскадными ререндерами.
+// SDK инжектится синхронно лоадером, поэтому подписка не нужна (snapshot стабилен).
+const subscribeTelegram = () => () => {}
+
+export function useTelegram(): TelegramWebApp | null {
+	const tg = useSyncExternalStore(subscribeTelegram, getTelegram, () => null)
+
+	useEffect(() => {
+		tg?.ready()
+	}, [tg])
+
+	return tg
+}
+
+export function applyTelegramChromeColor(color: string) {
+	const tg = getTelegram()
+	if (!tg || !color) return
+
+	tg.setHeaderColor?.(color)
+	tg.setBackgroundColor?.(color)
+	tg.setBottomBarColor?.(color)
+
+	// Fallback for older clients where setters can be flaky.
+	tg.headerColor = color
+	tg.backgroundColor = color
+	tg.bottomBarColor = color
+}

package/src/i18n/index.tsx

@@ -0,0 +1,92 @@
+'use client'
+
+// Порт локализации кита — по образцу @/utils/notify: кит НЕ знает, какой библиотекой
+// приложение переводит тексты. Он объявляет контракт (locale + t), а приложение один раз
+// подключает свою реализацию через <KitI18nProvider>.
+//
+// Зачем порт, а не пропсы: подписи вроде «Отмена» на кнопке confirm-диалога нужны глубоко
+// внутри компонентов, и протаскивать их пропсами через каждый вызов — шум. Зачем контекст,
+// а не модульная переменная (как в notify): смена локали обязана перерисовать компоненты,
+// а запись в модульную переменную ре-рендер не вызывает.
+//
+// Без провайдера кит работает на встроенном словаре (ru/en) — новый лендинг заводится
+// без настройки i18n вообще, а подключает её, когда дорастёт.
+
+import * as React from 'react'
+
+export type KitLocale = 'ru' | 'en'
+
+/** Разделы словаря, которые использует сам кит. */
+export type KitScope = 'ui.confirm' | 'ui.actions' | 'ui.toast'
+
+export interface KitI18nValue {
+	locale: KitLocale
+	/** Вернуть перевод. Если ключа нет — вернуть undefined, кит подставит свой дефолт. */
+	t: (scope: KitScope, key: string) => string | undefined
+}
+
+// Встроенный словарь — фолбэк и одновременно полный перечень ключей, которые
+// приложение может переопределить. Ключи совпадают с dictionaries кабинета
+// (ui.confirm.cancel, ui.actions.copy …), поэтому подключение сводится к одной строке.
+const FALLBACK: Record<KitLocale, Record<KitScope, Record<string, string>>> = {
+	ru: {
+		'ui.confirm': { cancel: 'Отмена', confirm: 'Подтвердить' },
+		'ui.actions': {
+			clear: 'Очистить',
+			paste: 'Вставить',
+			copy: 'Скопировать',
+			copied: 'Скопировано',
+		},
+		'ui.toast': { copied: 'Скопировано' },
+	},
+	en: {
+		'ui.confirm': { cancel: 'Cancel', confirm: 'Confirm' },
+		'ui.actions': {
+			clear: 'Clear',
+			paste: 'Paste',
+			copy: 'Copy',
+			copied: 'Copied',
+		},
+		'ui.toast': { copied: 'Copied' },
+	},
+}
+
+const DEFAULT_LOCALE: KitLocale = 'ru'
+
+const KitI18nContext = React.createContext<KitI18nValue | null>(null)
+
+/**
+ * Подключить локализацию приложения к киту.
+ *
+ * @example
+ * const t = useScopedI18n('ui')
+ * <KitI18nProvider locale={locale} t={(scope, key) => t(`${scope.slice(3)}.${key}`)}>
+ */
+export function KitI18nProvider({
+	locale,
+	t,
+	children,
+}: KitI18nValue & { children: React.ReactNode }) {
+	const value = React.useMemo(() => ({ locale, t }), [locale, t])
+	return <KitI18nContext.Provider value={value}>{children}</KitI18nContext.Provider>
+}
+
+/** Текущая локаль кита. Вне провайдера — DEFAULT_LOCALE. */
+export function useKitLocale(): KitLocale {
+	return React.useContext(KitI18nContext)?.locale ?? DEFAULT_LOCALE
+}
+
+/**
+ * Переводчик раздела. Всегда возвращает строку: приложение → встроенный словарь → сам ключ.
+ * Ключ как последний фолбэк лучше пустоты — по нему видно, чего не хватает в словаре.
+ */
+export function useKitT(scope: KitScope): (key: string) => string {
+	const ctx = React.useContext(KitI18nContext)
+	const locale = ctx?.locale ?? DEFAULT_LOCALE
+	const t = ctx?.t
+
+	return React.useCallback(
+		(key: string) => t?.(scope, key) ?? FALLBACK[locale]?.[scope]?.[key] ?? key,
+		[t, scope, locale],
+	)
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// Публичный вход кита: UI-компоненты, логотип и обвязка темы.
+// Next-специфика (Link, Image, useQueryParams) — 'hallo-kit/next'.
+// Хуки — 'hallo-kit/hooks', утилиты — 'hallo-kit/utils', серверное — 'hallo-kit/server'.
+
+export * from './ui/Icon'
+export * from './ui/badge'
+export * from './ui/burger-icon'
+export * from './ui/button'
+export * from './ui/card'
+export * from './ui/confirm'
+export * from './ui/count-up'
+export * from './ui/data-list'
+export * from './ui/drawer'
+export * from './ui/flag'
+export * from './ui/input'
+export * from './ui/label'
+export * from './ui/method-card'
+export * from './ui/modal'
+export * from './ui/otp-input'
+export * from './ui/pagination'
+export * from './ui/radio-group'
+export * from './ui/select'
+export * from './ui/separator'
+export * from './ui/skeleton'
+export * from './ui/spinner'
+export * from './ui/switch'
+export * from './ui/tabs'
+export * from './ui/textarea'
+export * from './ui/theme-switch'
+export * from './ui/toast'
+
+export * from './logo'
+export * from './theme-color-sync'
+export * from './theme-provider'
+export * from './config'

package/src/lib/device.ts

@@ -0,0 +1,28 @@
+import { cookies, headers } from 'next/headers'
+
+import { KitCookies } from '../config'
+import type { DeviceType } from '../hooks/useDevice'
+import { type Platform, platformFromUA } from './platform'
+
+// Серверное определение устройства — чтобы SSR сразу отдал ПРАВИЛЬНУЮ версию
+// (mobile/desktop) и не было вспышки/прыжков при F5.
+//
+// 1) Сначала пробуем cookie `device`: её пишет клиент (DeviceProvider) по РЕАЛЬНОЙ ширине
+//    вьюпорта (matchMedia). Если кука есть — сервер отдаёт ровно ту версию, что покажет
+//    клиент → расхождения UA↔viewport нет, переключения после гидратации нет.
+// 2) Куки ещё нет (самый первый визит) → fallback на User-Agent. `/Mobi/` — рекомендованный
+//    MDN минимальный тест (его содержат UA телефонных браузеров). Десктоп с узким окном
+//    UA не поймает, но клиент тут же измерит ширину и поставит куку → со следующего рендера
+//    всё чётко.
+export async function getInitialDevice(): Promise<DeviceType> {
+	const cookie = (await cookies()).get(KitCookies.DEVICE)?.value
+	if (cookie === 'mobile' || cookie === 'desktop') return cookie
+
+	const ua = (await headers()).get('user-agent') ?? ''
+	return /Mobi/i.test(ua) ? 'mobile' : 'desktop'
+}
+
+export async function getServerPlatform(): Promise<Platform> {
+	const ua = (await headers()).get('user-agent') ?? ''
+	return platformFromUA(ua)
+}

package/src/lib/platform.ts

@@ -0,0 +1,19 @@
+export type Platform = 'android' | 'ios' | 'macos' | 'windows' | 'linux' | 'web'
+
+export function platformFromUA(ua: string): Platform {
+	const s = ua.toLowerCase()
+	if (/android/.test(s)) return 'android'
+	if (/iphone|ipad|ipod/.test(s)) return 'ios'
+	if (/macintosh|mac os x/.test(s)) return 'macos'
+	if (/windows/.test(s)) return 'windows'
+	if (/linux/.test(s)) return 'linux'
+	return 'web'
+}
+
+export const OS_LABEL: Record<Exclude<Platform, 'web'>, string> = {
+	android: 'Android',
+	ios: 'iOS',
+	macos: 'macOS',
+	windows: 'Windows',
+	linux: 'Linux',
+}