@motor-hero/ui-kit 0.44.1 → 0.46.0

package/dist/vite.cjs

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/vite.ts
+var vite_exports = {};
+__export(vite_exports, {
+  versionFile: () => versionFile
+});
+module.exports = __toCommonJS(vite_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+function versionFile(options = {}) {
+  const fileName = options.fileName ?? "version.json";
+  const buildTime = (/* @__PURE__ */ new Date()).toISOString();
+  let outDir = "dist";
+  return {
+    name: "motor-hero:version-file",
+    config: () => ({
+      define: { "import.meta.env.VITE_BUILD_TIME": JSON.stringify(buildTime) }
+    }),
+    configResolved(config) {
+      outDir = config.build.outDir;
+    },
+    closeBundle() {
+      (0, import_node_fs.mkdirSync)(outDir, { recursive: true });
+      (0, import_node_fs.writeFileSync)(
+        (0, import_node_path.join)(outDir, fileName),
+        JSON.stringify({ buildTime, timestamp: Date.parse(buildTime) }, null, 2)
+      );
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  versionFile
+});
+//# sourceMappingURL=vite.cjs.map

package/dist/vite.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite.ts"],"sourcesContent":["import { mkdirSync, writeFileSync } from \"node:fs\"\nimport { join } from \"node:path\"\nimport type { Plugin } from \"vite\"\n\n/**\n * One build id in two places: baked into the bundle as\n * `import.meta.env.VITE_BUILD_TIME` and written to `dist/version.json`.\n * `UpdateBanner` / `useVersionCheck` compare the two at runtime, so the\n * running app knows its own version instead of guessing it from a fetch.\n *\n *   // vite.config.ts\n *   import { versionFile } from \"@motor-hero/ui-kit/vite\"\n *   export default defineConfig({ plugins: [react(), versionFile()] })\n */\nexport function versionFile(options: { fileName?: string } = {}): Plugin {\n  const fileName = options.fileName ?? \"version.json\"\n  const buildTime = new Date().toISOString()\n  let outDir = \"dist\"\n  return {\n    name: \"motor-hero:version-file\",\n    config: () => ({\n      define: { \"import.meta.env.VITE_BUILD_TIME\": JSON.stringify(buildTime) },\n    }),\n    configResolved(config) {\n      outDir = config.build.outDir\n    },\n    closeBundle() {\n      mkdirSync(outDir, { recursive: true })\n      writeFileSync(\n        join(outDir, fileName),\n        JSON.stringify({ buildTime, timestamp: Date.parse(buildTime) }, null, 2),\n      )\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAAyC;AACzC,uBAAqB;AAad,SAAS,YAAY,UAAiC,CAAC,GAAW;AACvE,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,aAAY,oBAAI,KAAK,GAAE,YAAY;AACzC,MAAI,SAAS;AACb,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ,OAAO;AAAA,MACb,QAAQ,EAAE,mCAAmC,KAAK,UAAU,SAAS,EAAE;AAAA,IACzE;AAAA,IACA,eAAe,QAAQ;AACrB,eAAS,OAAO,MAAM;AAAA,IACxB;AAAA,IACA,cAAc;AACZ,oCAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;AACrC;AAAA,YACE,uBAAK,QAAQ,QAAQ;AAAA,QACrB,KAAK,UAAU,EAAE,WAAW,WAAW,KAAK,MAAM,SAAS,EAAE,GAAG,MAAM,CAAC;AAAA,MACzE;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/vite.d.ts

@@ -0,0 +1,15 @@
+import type { Plugin } from "vite";
+/**
+ * One build id in two places: baked into the bundle as
+ * `import.meta.env.VITE_BUILD_TIME` and written to `dist/version.json`.
+ * `UpdateBanner` / `useVersionCheck` compare the two at runtime, so the
+ * running app knows its own version instead of guessing it from a fetch.
+ *
+ *   // vite.config.ts
+ *   import { versionFile } from "@motor-hero/ui-kit/vite"
+ *   export default defineConfig({ plugins: [react(), versionFile()] })
+ */
+export declare function versionFile(options?: {
+    fileName?: string;
+}): Plugin;
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAoBvE"}

package/dist/vite.js

@@ -0,0 +1,28 @@
+// src/vite.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+function versionFile(options = {}) {
+  const fileName = options.fileName ?? "version.json";
+  const buildTime = (/* @__PURE__ */ new Date()).toISOString();
+  let outDir = "dist";
+  return {
+    name: "motor-hero:version-file",
+    config: () => ({
+      define: { "import.meta.env.VITE_BUILD_TIME": JSON.stringify(buildTime) }
+    }),
+    configResolved(config) {
+      outDir = config.build.outDir;
+    },
+    closeBundle() {
+      mkdirSync(outDir, { recursive: true });
+      writeFileSync(
+        join(outDir, fileName),
+        JSON.stringify({ buildTime, timestamp: Date.parse(buildTime) }, null, 2)
+      );
+    }
+  };
+}
+export {
+  versionFile
+};
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite.ts"],"sourcesContent":["import { mkdirSync, writeFileSync } from \"node:fs\"\nimport { join } from \"node:path\"\nimport type { Plugin } from \"vite\"\n\n/**\n * One build id in two places: baked into the bundle as\n * `import.meta.env.VITE_BUILD_TIME` and written to `dist/version.json`.\n * `UpdateBanner` / `useVersionCheck` compare the two at runtime, so the\n * running app knows its own version instead of guessing it from a fetch.\n *\n *   // vite.config.ts\n *   import { versionFile } from \"@motor-hero/ui-kit/vite\"\n *   export default defineConfig({ plugins: [react(), versionFile()] })\n */\nexport function versionFile(options: { fileName?: string } = {}): Plugin {\n  const fileName = options.fileName ?? \"version.json\"\n  const buildTime = new Date().toISOString()\n  let outDir = \"dist\"\n  return {\n    name: \"motor-hero:version-file\",\n    config: () => ({\n      define: { \"import.meta.env.VITE_BUILD_TIME\": JSON.stringify(buildTime) },\n    }),\n    configResolved(config) {\n      outDir = config.build.outDir\n    },\n    closeBundle() {\n      mkdirSync(outDir, { recursive: true })\n      writeFileSync(\n        join(outDir, fileName),\n        JSON.stringify({ buildTime, timestamp: Date.parse(buildTime) }, null, 2),\n      )\n    },\n  }\n}\n"],"mappings":";AAAA,SAAS,WAAW,qBAAqB;AACzC,SAAS,YAAY;AAad,SAAS,YAAY,UAAiC,CAAC,GAAW;AACvE,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,aAAY,oBAAI,KAAK,GAAE,YAAY;AACzC,MAAI,SAAS;AACb,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ,OAAO;AAAA,MACb,QAAQ,EAAE,mCAAmC,KAAK,UAAU,SAAS,EAAE;AAAA,IACzE;AAAA,IACA,eAAe,QAAQ;AACrB,eAAS,OAAO,MAAM;AAAA,IACxB;AAAA,IACA,cAAc;AACZ,gBAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;AACrC;AAAA,QACE,KAAK,QAAQ,QAAQ;AAAA,QACrB,KAAK,UAAU,EAAE,WAAW,WAAW,KAAK,MAAM,SAAS,EAAE,GAAG,MAAM,CAAC;AAAA,MACzE;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motor-hero/ui-kit",
-  "version": "0.44.1",
+  "version": "0.46.0",
   "description": "Componentes React reutilizáveis para o ecossistema MotorHero — shadcn/ui + Tailwind CSS v4",
   "author": "MotorHero",
   "license": "UNLICENSED",
@@ -23,7 +23,12 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./styles": "./dist/styles.css"
+    "./styles": "./dist/styles.css",
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js",
+      "require": "./dist/vite.cjs"
+    }
   },
   "files": [
     "dist",

package/src/components/app-shell.tsx

@@ -20,6 +20,14 @@ export interface AppShellProps {
   headerActions?: ReactNode
   collapsible?: boolean
   defaultCollapsed?: boolean
+  /**
+   * Bottom of the desktop sidebar, above the collapse control — a product
+   * credit, a version, a support link. Receives the collapsed state so it
+   * can shrink with the sidebar.
+   */
+  sidebarFooter?: ReactNode | ((collapsed: boolean) => ReactNode)
+  /** Above the header, full width of the content column — `UpdateBanner` goes here. */
+  banner?: ReactNode
   children: ReactNode
 }
 
@@ -37,6 +45,8 @@ export function AppShell({
   headerActions,
   collapsible = true,
   defaultCollapsed = false,
+  sidebarFooter,
+  banner,
   children,
 }: AppShellProps) {
   const [collapsed, setCollapsed] = useState(defaultCollapsed)
@@ -67,6 +77,11 @@ export function AppShell({
           {collapsed ? (brandCollapsed ?? brand) : brand}
         </div>
         <div className="flex-1 overflow-y-auto px-2 py-4">{nav(collapsed)}</div>
+        {sidebarFooter && (
+          <div className="border-t px-3 py-2" data-slot="sidebar-footer">
+            {typeof sidebarFooter === "function" ? sidebarFooter(collapsed) : sidebarFooter}
+          </div>
+        )}
         {collapsible && (
           <div className="border-t p-2">
             <button
@@ -104,6 +119,7 @@ export function AppShell({
 
       {/* Main column */}
       <div className="flex flex-1 flex-col overflow-hidden">
+        {banner}
         <header className="flex h-14 shrink-0 items-center gap-2 border-b bg-background px-4">
           <button
             type="button"

package/src/components/combobox.tsx

@@ -93,11 +93,26 @@ export function Combobox({
 	const [search, setSearch] = React.useState("");
 	const isDesktop = useIsDesktop();
 	const isServer = onSearchChange !== undefined;
-	const selected =
+	// Mesmo cache do multi-combobox: em modo servidor `options` é só a página
+	// carregada, então o rótulo do valor escolhido precisa sobreviver à troca de
+	// página — senão o gatilho volta ao placeholder com o valor ainda setado.
+	const labelCache = React.useRef(new Map<string, ComboboxOption>());
+	const fromPage =
 		selectedOption?.value === value
 			? selectedOption
-			: (options.find((option) => option.value === value) ??
-				(creatable && value ? { value, label: value } : undefined));
+			: options.find((option) => option.value === value);
+
+	// No efeito, nunca no render — mutar a ref durante o render é impuro.
+	React.useEffect(() => {
+		for (const option of options) labelCache.current.set(option.value, option);
+		if (selectedOption)
+			labelCache.current.set(selectedOption.value, selectedOption);
+	});
+
+	const selected =
+		fromPage ??
+		(value ? labelCache.current.get(value) : undefined) ??
+		(creatable && value ? { value, label: value } : undefined);
 
 	const handleOpenChange = (next: boolean) => {
 		setOpen(next);

package/src/components/multi-combobox.tsx

@@ -73,14 +73,30 @@ export function MultiCombobox({
   const [open, setOpen] = React.useState(false)
   const isDesktop = useIsDesktop()
   const isServer = onSearchChange !== undefined
-  // Chips a partir de selectedOptions (rótulos salvos) + página atual, dedup
-  // por value (primeira ocorrência vence → o rótulo salvo prevalece).
-  const seen = new Set<string>()
-  const selected = [...(selectedOptions ?? []), ...options].filter((option) => {
-    if (!value.includes(option.value) || seen.has(option.value)) return false
-    seen.add(option.value)
-    return true
+  // Em modo servidor `options` é só a página carregada no momento, então um
+  // rótulo visto uma vez precisa sobreviver à troca de página: sem esse cache,
+  // buscar (ou paginar) fazia o chip de um valor ainda selecionado sumir do
+  // gatilho, como se nada estivesse escolhido. Prioridade de rótulo:
+  // `selectedOptions` (o salvo) → página atual → cache.
+  const labelCache = React.useRef(new Map<string, ComboboxOption>())
+  const byValue = new Map<string, ComboboxOption>()
+  for (const option of options) byValue.set(option.value, option)
+  for (const option of selectedOptions ?? []) byValue.set(option.value, option)
+
+  // Escrita no efeito, nunca no render — mutar a ref durante o render é impuro.
+  // Não pisca: no render em que a opção fica selecionável ela ainda está em
+  // `options`, e este efeito a grava antes de `options` mudar.
+  React.useEffect(() => {
+    for (const [key, option] of byValue) labelCache.current.set(key, option)
   })
+
+  // Ordem de seleção (`value`), que é estável — a antiga vinha da ordem da
+  // página carregada e mudava sozinha conforme as páginas chegavam. Um valor
+  // sem rótulo conhecido (edição sem `selectedOptions`) segue sem chip.
+  const selected = value
+    .map((v) => byValue.get(v) ?? labelCache.current.get(v))
+    .filter((option): option is ComboboxOption => option !== undefined)
+
   const { listRef, sentinelRef } = useInfiniteScrollSentinel({
     enabled: isServer && !!hasMore,
     loading,

package/src/components/update-banner.tsx

@@ -0,0 +1,53 @@
+import { RefreshCw } from "lucide-react"
+import { cn } from "../lib/utils"
+import { type UseVersionCheckOptions, useVersionCheck } from "../hooks/use-version-check"
+
+export interface UpdateBannerProps extends UseVersionCheckOptions {
+  title?: string
+  description?: string
+  actionLabel?: string
+  className?: string
+}
+
+/**
+ * A bar that appears when a newer build is deployed and stays until the
+ * person reloads — not a toast: a notice that can be missed or dismissed
+ * leaves the old bundle running against a new API. Themed with the product
+ * tokens so it matches light and dark alike. Put it in `AppShell`'s
+ * `banner` slot (or at the top of any page).
+ */
+export function UpdateBanner({
+  title = "Nova versão disponível",
+  description = "Atualize para continuar na versão mais recente.",
+  actionLabel = "Atualizar",
+  className,
+  ...options
+}: UpdateBannerProps) {
+  const { updateAvailable, reload } = useVersionCheck(options)
+  if (!updateAvailable) return null
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      data-slot="update-banner"
+      className={cn(
+        "flex flex-wrap items-center justify-between gap-3 border-b border-primary/30 bg-primary px-4 py-2 text-sm text-primary-foreground",
+        className,
+      )}
+    >
+      <span className="flex min-w-0 items-center gap-2">
+        <RefreshCw className="h-4 w-4 shrink-0 animate-spin [animation-duration:3s]" aria-hidden />
+        <span className="font-medium">{title}</span>
+        <span className="hidden truncate opacity-80 sm:inline">{description}</span>
+      </span>
+      <button
+        type="button"
+        onClick={reload}
+        className="shrink-0 rounded-md bg-background px-3 py-1 text-xs font-medium text-foreground transition-colors hover:bg-background/90"
+      >
+        {actionLabel}
+      </button>
+    </div>
+  )
+}

package/src/hooks/use-infinite-scroll-sentinel.ts

@@ -1,10 +1,19 @@
 import * as React from "react"
 
 /**
- * Dispara `onLoadMore` quando o `sentinelRef` entra na viewport do `listRef`
- * (raiz = a lista rolável, não a janela — a lista rola por dentro do Popover/
- * Drawer). Usa refs "latest" para `loading`/`onLoadMore` e evita reassinar o
- * observer a cada render.
+ * Dispara `onLoadMore` quando o sentinela entra na viewport da lista rolável
+ * (raiz = a lista, não a janela — ela rola por dentro do Popover/Drawer). Usa
+ * refs "latest" para `loading`/`onLoadMore` e não reassina o observer a cada
+ * render.
+ *
+ * Os nós entram como **estado** (callback refs), não como `useRef`: lista e
+ * sentinela vivem dentro do Portal do Popover/Drawer e só existem no DOM com o
+ * dropdown aberto, o que acontece bem depois de `enabled` virar `true`. Com
+ * `useRef` + deps `[enabled]` o efeito rodava uma única vez, com o dropdown
+ * fechado e os dois refs `null`, e o observer nunca chegava a ser registrado —
+ * a paginação por scroll simplesmente não acontecia. Guardar os nós em estado
+ * também refaz a assinatura quando o sentinela desmonta e remonta (`hasMore`
+ * oscilando), em vez de deixar o observer preso a um nó já destacado.
  */
 export function useInfiniteScrollSentinel({
   enabled,
@@ -15,21 +24,29 @@ export function useInfiniteScrollSentinel({
   loading?: boolean
   onLoadMore?: () => void
 }) {
-  const listRef = React.useRef<HTMLDivElement | null>(null)
-  const sentinelRef = React.useRef<HTMLDivElement | null>(null)
+  const [listNode, setListNode] = React.useState<HTMLDivElement | null>(null)
+  const [sentinelNode, setSentinelNode] = React.useState<HTMLDivElement | null>(
+    null,
+  )
   const loadingRef = React.useRef(loading)
   const onLoadMoreRef = React.useRef(onLoadMore)
 
+  // Memoizadas de propósito: uma callback ref recriada a cada render é chamada
+  // com `null` e de novo com o nó em *todo* render, realimentando o estado.
+  const listRef = React.useCallback((node: HTMLDivElement | null) => {
+    setListNode(node)
+  }, [])
+  const sentinelRef = React.useCallback((node: HTMLDivElement | null) => {
+    setSentinelNode(node)
+  }, [])
+
   React.useEffect(() => {
     loadingRef.current = loading
     onLoadMoreRef.current = onLoadMore
   })
 
   React.useEffect(() => {
-    if (!enabled) return
-    const root = listRef.current
-    const sentinel = sentinelRef.current
-    if (!root || !sentinel) return
+    if (!enabled || !listNode || !sentinelNode) return
 
     const observer = new IntersectionObserver(
       (entries) => {
@@ -37,11 +54,11 @@ export function useInfiniteScrollSentinel({
           onLoadMoreRef.current?.()
         }
       },
-      { root, rootMargin: "0px 0px 100px 0px" },
+      { root: listNode, rootMargin: "0px 0px 100px 0px" },
     )
-    observer.observe(sentinel)
+    observer.observe(sentinelNode)
     return () => observer.disconnect()
-  }, [enabled])
+  }, [enabled, listNode, sentinelNode])
 
   return { listRef, sentinelRef }
 }

package/src/hooks/use-version-check.ts

@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useState } from "react"
+
+export interface UseVersionCheckOptions {
+  /** The build id baked into the running bundle (see `versionFile` in `@motor-hero/ui-kit/vite`). */
+  currentBuild: string | undefined
+  /** Where the deployed build id is published. */
+  url?: string
+  intervalMs?: number
+}
+
+export interface VersionCheckState {
+  /** The deployed build differs from the running one. */
+  updateAvailable: boolean
+  /** Grows on every poll that still sees a newer build. */
+  staleChecks: number
+  latestBuild: string | null
+  reload: () => void
+}
+
+/**
+ * Polls the deployed `version.json` and compares its `buildTime` with the
+ * build id baked into this bundle. Nothing is inferred from a first fetch —
+ * a page loaded during a deploy, or a poll that fails while the server
+ * restarts, cannot make the running code believe it is current. Polling
+ * pauses while the tab is hidden and runs at once when it comes back.
+ */
+export function useVersionCheck({
+  currentBuild,
+  url = "/version.json",
+  intervalMs = 60_000,
+}: UseVersionCheckOptions): VersionCheckState {
+  const [latestBuild, setLatestBuild] = useState<string | null>(null)
+  const [staleChecks, setStaleChecks] = useState(0)
+
+  useEffect(() => {
+    if (!currentBuild) return
+    let cancelled = false
+
+    const check = async () => {
+      if (document.visibilityState === "hidden") return
+      try {
+        const res = await fetch(url, { cache: "no-store" })
+        const contentType = res.headers.get("content-type") ?? ""
+        if (!res.ok || !contentType.includes("application/json")) return
+        const data: { buildTime?: unknown } = await res.json()
+        if (cancelled || typeof data.buildTime !== "string") return
+        if (data.buildTime !== currentBuild) {
+          setLatestBuild(data.buildTime)
+          setStaleChecks((n) => n + 1)
+        }
+      } catch (error) {
+        console.error("Version check failed", error)
+      }
+    }
+
+    check()
+    const interval = setInterval(check, intervalMs)
+    const onVisible = () => {
+      if (document.visibilityState === "visible") check()
+    }
+    document.addEventListener("visibilitychange", onVisible)
+    return () => {
+      cancelled = true
+      clearInterval(interval)
+      document.removeEventListener("visibilitychange", onVisible)
+    }
+  }, [currentBuild, url, intervalMs])
+
+  const reload = useCallback(() => window.location.reload(), [])
+
+  return { updateAvailable: latestBuild !== null, staleChecks, latestBuild, reload }
+}

package/src/index.ts

@@ -64,6 +64,8 @@ export type {
 } from "./components/theme-provider";
 export { ThemeProvider, useTheme } from "./components/theme-provider";
 export { Toaster } from "./components/toaster";
+export type { UpdateBannerProps } from "./components/update-banner";
+export { UpdateBanner } from "./components/update-banner";
 export type { RenderLink, RenderLinkProps } from "./components/types";
 export { defaultRenderLink } from "./components/types";
 export type {
@@ -83,6 +85,8 @@ export {
 // Hooks
 export { useDisclosure } from "./hooks/use-disclosure";
 export { useIsDesktop } from "./hooks/use-is-desktop";
+export type { UseVersionCheckOptions, VersionCheckState } from "./hooks/use-version-check";
+export { useVersionCheck } from "./hooks/use-version-check";
 export { toast, useCustomToast } from "./hooks/use-toast";
 export { extractApiError } from "./lib/api-error";
 export type { CompanyTheme, CompanyThemeTokens } from "./lib/company-theme";

package/src/vite.ts

@@ -0,0 +1,35 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import type { Plugin } from "vite"
+
+/**
+ * One build id in two places: baked into the bundle as
+ * `import.meta.env.VITE_BUILD_TIME` and written to `dist/version.json`.
+ * `UpdateBanner` / `useVersionCheck` compare the two at runtime, so the
+ * running app knows its own version instead of guessing it from a fetch.
+ *
+ *   // vite.config.ts
+ *   import { versionFile } from "@motor-hero/ui-kit/vite"
+ *   export default defineConfig({ plugins: [react(), versionFile()] })
+ */
+export function versionFile(options: { fileName?: string } = {}): Plugin {
+  const fileName = options.fileName ?? "version.json"
+  const buildTime = new Date().toISOString()
+  let outDir = "dist"
+  return {
+    name: "motor-hero:version-file",
+    config: () => ({
+      define: { "import.meta.env.VITE_BUILD_TIME": JSON.stringify(buildTime) },
+    }),
+    configResolved(config) {
+      outDir = config.build.outDir
+    },
+    closeBundle() {
+      mkdirSync(outDir, { recursive: true })
+      writeFileSync(
+        join(outDir, fileName),
+        JSON.stringify({ buildTime, timestamp: Date.parse(buildTime) }, null, 2),
+      )
+    },
+  }
+}