@pablozaiden/webapp 0.3.10 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @pablozaiden/webapp
 
-Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, multi-user passkey auth, user-owned API keys, device auth, realtime websocket state, scoped settings, binary builds and Docker images.
+Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, multi-user passkey auth, user-owned API keys, device auth, realtime websocket state, PWA shell metadata, scoped settings, binary builds and Docker images.
 
 ## Quick start
 

package/docs/getting-started.md

@@ -37,12 +37,33 @@ const app = createWebAppServer({
   index: webIndex,
   auth: { passkeys: true, apiKeys: true, deviceAuth: true },
   realtime: { path: "/api/ws" },
+  pwa: {
+    shortName: "MyApp",
+    themeColor: "#111827",
+    backgroundColor: "#ffffff",
+  },
   routes,
 });
 
 await app.runFromCli();
 ```
 
+The `pwa` option is optional; by default the framework derives install metadata from `appName` and serves `/manifest.webmanifest`. Configure `icons`, `appleTouchIcon`, `startUrl`, and `scope` when your app serves the manifest dynamically through the framework.
+
+For the recommended Bun `HTMLBundle` shape (`import webIndex from "./index.html"`), keep the install metadata static and relative to `index.html` so Bun can bundle and rewrite those assets:
+
+```html
+<link rel="manifest" href="./site.webmanifest" />
+<link rel="icon" type="image/svg+xml" href="./favicon.svg" />
+<link rel="apple-touch-icon" href="./apple-touch-icon.png" />
+<meta name="mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-title" content="MyApp" />
+<meta name="theme-color" content="#111827" />
+```
+
+Place `site.webmanifest`, icons, and apple-touch icons next to `index.html`, and reference manifest icons with relative paths such as `"./web-app-manifest-192x192.png"`. A single SVG favicon is enough for lightweight examples; production apps should include PNG manifest icons and an Apple touch icon like Clanky. For string, `Blob`, or `Response` HTML indexes, the framework injects equivalent tags automatically.
+
 Apps should stay one app and one binary. Use subcommands for different modes:
 
 ```bash

package/docs/server.md

@@ -94,6 +94,77 @@ Built-in endpoints include:
 | `/api/server/kill` | Authenticated server shutdown |
 | `/api/ws` | Realtime websocket by default |
 
+## PWA metadata
+
+`createWebAppServer` provides shell-level PWA metadata. PWA support is enabled by default with `appName`-derived manifest values, `/manifest.webmanifest`, `/` start/scope, `standalone` display, and conventional icon paths (`/web-app-manifest-192x192.png`, `/web-app-manifest-512x512.png`, and `/apple-touch-icon.png`).
+
+```ts
+createWebAppServer({
+  appName: "My App",
+  // ...
+  pwa: {
+    shortName: "MyApp",
+    themeColor: "#111827",
+    backgroundColor: "#ffffff",
+    display: "standalone",
+    icons: [
+      { src: "/web-app-manifest-192x192.png", sizes: "192x192", type: "image/png", purpose: "any maskable" },
+      { src: "/web-app-manifest-512x512.png", sizes: "512x512", type: "image/png", purpose: "any maskable" },
+    ],
+    appleTouchIcon: { href: "/apple-touch-icon.png", sizes: "180x180" },
+    startUrl: "/",
+    scope: "/",
+  },
+});
+```
+
+The framework serves the manifest with `application/manifest+json; charset=utf-8`.
+
+For string, `Blob`, or `Response` HTML indexes, the framework also injects the installability tags into HTML shell responses:
+
+```html
+<link rel="manifest" href="/manifest.webmanifest" />
+<link rel="icon" href="/web-app-manifest-192x192.png" type="image/png" sizes="192x192" />
+<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+<meta name="mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-title" content="MyApp" />
+<meta name="theme-color" content="#111827" />
+```
+
+For Bun `HTMLBundle` indexes imported from `index.html`, Bun must serve the HTML and generated assets directly so module rewriting and transpilation keep working. In that mode the framework still serves `/manifest.webmanifest`, but it does not mutate the HTML response. Follow the Clanky-style static asset pattern instead: place `site.webmanifest`, favicons, and apple-touch icons next to `index.html`, then reference them with relative paths so Bun can bundle and rewrite them:
+
+```html
+<link rel="manifest" href="./site.webmanifest" />
+<link rel="icon" href="./favicon.ico" sizes="any" />
+<link rel="icon" type="image/svg+xml" href="./favicon.svg" />
+<link rel="apple-touch-icon" href="./apple-touch-icon.png" />
+<meta name="mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-capable" content="yes" />
+<meta name="apple-mobile-web-app-title" content="MyApp" />
+<meta name="theme-color" content="#111827" />
+```
+
+Use relative icon paths inside `site.webmanifest` as well:
+
+```json
+{
+  "name": "My App",
+  "short_name": "MyApp",
+  "start_url": "./",
+  "scope": "./",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#111827",
+  "icons": [
+    { "src": "./web-app-manifest-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "any maskable" },
+    { "src": "./web-app-manifest-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
+  ]
+}
+```
+
+Icon files still need to exist in the app bundle or public routes; the framework advertises and serves metadata, but it does not generate image assets. Set `pwa: { enabled: false }` to opt out. Apps that already serve `/manifest.webmanifest` through `publicRoutes` can keep that override; explicit public routes take precedence over the generated manifest.
+
 ## Public/static routes
 
 Declare public non-API assets explicitly with `publicRoutes`:
@@ -102,10 +173,6 @@ Declare public non-API assets explicitly with `publicRoutes`:
 createWebAppServer({
   // ...
   publicRoutes: {
-    "/manifest.webmanifest": {
-      headers: { "content-type": "application/manifest+json" },
-      GET: manifestJson,
-    },
     "/service-worker": serviceWorker,
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.3.10",
+  "version": "0.4.1",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",

package/src/server/create-web-app-server.ts

@@ -51,6 +51,7 @@ export interface WebAppServerConfig<TEvent = unknown> {
   store?: WebAppStore;
   routes?: RouteTable<TEvent>;
   publicRoutes?: Record<string, PublicRouteDefinition>;
+  pwa?: WebAppPwaConfig;
   websockets?: Record<string, Partial<WebSocketHandler<WebAppWebSocketData>>>;
   auth?: {
     passkeys?: boolean | { rpName?: string; userName?: string; userDisplayName?: string };
@@ -66,6 +67,34 @@ export interface WebAppServerConfig<TEvent = unknown> {
   configResponse?: (req: Request, base: Readonly<WebAppConfigResponse>) => Record<string, unknown>;
 }
 
+export type WebAppPwaDisplay = "fullscreen" | "standalone" | "minimal-ui" | "browser";
+
+export interface WebAppPwaIcon {
+  src: string;
+  sizes?: string;
+  type?: string;
+  purpose?: string;
+}
+
+export interface WebAppPwaAppleTouchIcon {
+  href: string;
+  sizes?: string;
+}
+
+export interface WebAppPwaConfig {
+  enabled?: boolean;
+  manifestPath?: string;
+  appName?: string;
+  shortName?: string;
+  themeColor?: string;
+  backgroundColor?: string;
+  display?: WebAppPwaDisplay;
+  icons?: WebAppPwaIcon[];
+  appleTouchIcon?: string | WebAppPwaAppleTouchIcon | WebAppPwaAppleTouchIcon[];
+  startUrl?: string;
+  scope?: string;
+}
+
 export const WEBAPP_SOCKET_HANDLER = "webappSocketHandler";
 
 export type WebAppWebSocketData = WebSocketData & {
@@ -95,6 +124,23 @@ export interface WebAppServer<TEvent = unknown> {
 
 const log = createLogger("webapp:server");
 const LOG_LEVELS = new Set<LogLevelName>(["trace", "debug", "info", "warn", "error"]);
+const DEFAULT_PWA_THEME_COLOR = "#111827";
+const DEFAULT_PWA_BACKGROUND_COLOR = "#ffffff";
+
+type HtmlBundleIndex = { index: string };
+
+interface NormalizedPwaConfig {
+  manifestPath: string;
+  appName: string;
+  shortName: string;
+  themeColor: string;
+  backgroundColor: string;
+  display: WebAppPwaDisplay;
+  icons: WebAppPwaIcon[];
+  appleTouchIcons: WebAppPwaAppleTouchIcon[];
+  startUrl: string;
+  scope: string;
+}
 
 function bearerToken(req: Request): string | undefined {
   const header = req.headers.get("authorization")?.trim();
@@ -139,14 +185,217 @@ function addHeaders(response: Response, headers: Headers): Response {
   return response;
 }
 
-function htmlResponse(index: unknown): Response {
+function isHtmlBundleIndex(index: unknown): index is HtmlBundleIndex {
+  return typeof index === "object"
+    && index !== null
+    && "index" in index
+    && typeof (index as { index?: unknown }).index === "string"
+    && String(index) === "[object HTMLBundle]";
+}
+
+function requestLooksLikeNavigation(req?: Request): boolean {
+  if (!req) {
+    return true;
+  }
+  const url = new URL(req.url);
+  const lastSegment = url.pathname.split("/").pop() ?? "";
+  const hasFileExtension = /\.[A-Za-z0-9]+$/.test(lastSegment);
+  if (hasFileExtension) {
+    return false;
+  }
+  const accept = req.headers.get("accept");
+  return !accept || accept.includes("text/html") || accept.includes("*/*");
+}
+
+function normalizePath(path: string, field: string): string {
+  const trimmed = path.trim();
+  if (!trimmed) {
+    throw new Error(`PWA ${field} cannot be empty`);
+  }
+  return trimmed;
+}
+
+function normalizeServerPath(path: string, field: string): string {
+  const normalized = normalizePath(path, field);
+  return normalized.startsWith("/") ? normalized : `/${normalized}`;
+}
+
+function normalizePwaIcon(icon: WebAppPwaIcon): WebAppPwaIcon {
+  const src = normalizePath(icon.src, "icon src");
+  return {
+    src,
+    ...(icon.sizes ? { sizes: icon.sizes } : {}),
+    ...(icon.type ? { type: icon.type } : {}),
+    ...(icon.purpose ? { purpose: icon.purpose } : {}),
+  };
+}
+
+function normalizeAppleTouchIcon(icon: string | WebAppPwaAppleTouchIcon): WebAppPwaAppleTouchIcon {
+  if (typeof icon === "string") {
+    return { href: normalizePath(icon, "appleTouchIcon") };
+  }
+  return {
+    href: normalizePath(icon.href, "appleTouchIcon href"),
+    ...(icon.sizes ? { sizes: icon.sizes } : {}),
+  };
+}
+
+function normalizePwaConfig(appName: string, input?: WebAppPwaConfig): NormalizedPwaConfig | undefined {
+  if (input?.enabled === false) {
+    return undefined;
+  }
+  const icons = input?.icons?.map(normalizePwaIcon) ?? [
+    { src: "/web-app-manifest-192x192.png", sizes: "192x192", type: "image/png", purpose: "any maskable" },
+    { src: "/web-app-manifest-512x512.png", sizes: "512x512", type: "image/png", purpose: "any maskable" },
+  ];
+  const appleTouchIconInput = input?.appleTouchIcon;
+  const appleTouchIcons = Array.isArray(appleTouchIconInput)
+    ? appleTouchIconInput.map(normalizeAppleTouchIcon)
+    : appleTouchIconInput
+      ? [normalizeAppleTouchIcon(appleTouchIconInput)]
+      : [{ href: "/apple-touch-icon.png" }];
+  return {
+    manifestPath: normalizeServerPath(input?.manifestPath ?? "/manifest.webmanifest", "manifestPath"),
+    appName: input?.appName ?? appName,
+    shortName: input?.shortName ?? input?.appName ?? appName,
+    themeColor: input?.themeColor ?? DEFAULT_PWA_THEME_COLOR,
+    backgroundColor: input?.backgroundColor ?? DEFAULT_PWA_BACKGROUND_COLOR,
+    display: input?.display ?? "standalone",
+    icons,
+    appleTouchIcons,
+    startUrl: normalizeServerPath(input?.startUrl ?? "/", "startUrl"),
+    scope: normalizeServerPath(input?.scope ?? "/", "scope"),
+  };
+}
+
+function pwaManifestJson(pwa: NormalizedPwaConfig): string {
+  return JSON.stringify({
+    name: pwa.appName,
+    short_name: pwa.shortName,
+    start_url: pwa.startUrl,
+    scope: pwa.scope,
+    display: pwa.display,
+    background_color: pwa.backgroundColor,
+    theme_color: pwa.themeColor,
+    icons: pwa.icons,
+  });
+}
+
+function pwaManifestResponse(pwa: NormalizedPwaConfig): Response {
+  return withSecurityHeaders(new Response(pwaManifestJson(pwa), {
+    headers: { "content-type": "application/manifest+json; charset=utf-8" },
+  }));
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function hasHeadTag(html: string, pattern: RegExp): boolean {
+  return pattern.test(html);
+}
+
+function hasLinkRel(html: string, rel: string): boolean {
+  const links = html.matchAll(/<link\b[^>]*\brel\s*=\s*(["'])(.*?)\1[^>]*>/gi);
+  for (const link of links) {
+    const relValue = link[2]?.toLowerCase();
+    if (relValue?.split(/\s+/).includes(rel)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function pwaHeadTags(html: string, pwa: NormalizedPwaConfig): string {
+  const tags: string[] = [];
+  if (!hasLinkRel(html, "manifest")) {
+    tags.push(`<link rel="manifest" href="${escapeHtmlAttribute(pwa.manifestPath)}" />`);
+  }
+  if (!hasLinkRel(html, "icon")) {
+    for (const icon of pwa.icons) {
+      const attributes = [
+        `rel="icon"`,
+        `href="${escapeHtmlAttribute(icon.src)}"`,
+        icon.type ? `type="${escapeHtmlAttribute(icon.type)}"` : undefined,
+        icon.sizes ? `sizes="${escapeHtmlAttribute(icon.sizes)}"` : undefined,
+      ].filter(Boolean);
+      tags.push(`<link ${attributes.join(" ")} />`);
+    }
+  }
+  if (!hasLinkRel(html, "apple-touch-icon")) {
+    for (const icon of pwa.appleTouchIcons) {
+      const attributes = [
+        `rel="apple-touch-icon"`,
+        icon.sizes ? `sizes="${escapeHtmlAttribute(icon.sizes)}"` : undefined,
+        `href="${escapeHtmlAttribute(icon.href)}"`,
+      ].filter(Boolean);
+      tags.push(`<link ${attributes.join(" ")} />`);
+    }
+  }
+  if (!hasHeadTag(html, /<meta\b[^>]*\bname=["']mobile-web-app-capable["']/i)) {
+    tags.push(`<meta name="mobile-web-app-capable" content="yes" />`);
+  }
+  if (!hasHeadTag(html, /<meta\b[^>]*\bname=["']apple-mobile-web-app-capable["']/i)) {
+    tags.push(`<meta name="apple-mobile-web-app-capable" content="yes" />`);
+  }
+  if (!hasHeadTag(html, /<meta\b[^>]*\bname=["']apple-mobile-web-app-title["']/i)) {
+    tags.push(`<meta name="apple-mobile-web-app-title" content="${escapeHtmlAttribute(pwa.shortName)}" />`);
+  }
+  if (!hasHeadTag(html, /<meta\b[^>]*\bname=["']theme-color["']/i)) {
+    tags.push(`<meta name="theme-color" content="${escapeHtmlAttribute(pwa.themeColor)}" />`);
+  }
+  return tags.length > 0 ? `\n    ${tags.join("\n    ")}\n` : "";
+}
+
+function injectPwaHeadTags(html: string, pwa?: NormalizedPwaConfig): string {
+  if (!pwa) {
+    return html;
+  }
+  const tags = pwaHeadTags(html, pwa);
+  if (!tags) {
+    return html;
+  }
+  const headClose = /<\/head\s*>/i;
+  if (headClose.test(html)) {
+    return html.replace(headClose, `${tags}</head>`);
+  }
+  return `${html}${tags}`;
+}
+
+async function htmlResponse(index: unknown, pwa?: NormalizedPwaConfig, req?: Request): Promise<Response> {
+  if (isHtmlBundleIndex(index)) {
+    if (requestLooksLikeNavigation(req)) {
+      const html = await Bun.file(index.index).text();
+      return withSecurityHeaders(new Response(injectPwaHeadTags(html, pwa), { headers: { "content-type": "text/html; charset=utf-8" } }));
+    }
+    return index as unknown as Response;
+  }
   if (index instanceof Response) {
+    const contentType = index.headers.get("content-type");
+    if (pwa && (!contentType || contentType.includes("text/html"))) {
+      const headers = new Headers(index.headers);
+      if (!headers.has("content-type")) {
+        headers.set("content-type", "text/html; charset=utf-8");
+      }
+      return withSecurityHeaders(new Response(injectPwaHeadTags(await index.clone().text(), pwa), {
+        status: index.status,
+        statusText: index.statusText,
+        headers,
+      }));
+    }
     return withSecurityHeaders(index);
   }
   if (typeof index === "string") {
-    return withSecurityHeaders(new Response(index, { headers: { "content-type": "text/html; charset=utf-8" } }));
+    return withSecurityHeaders(new Response(injectPwaHeadTags(index, pwa), { headers: { "content-type": "text/html; charset=utf-8" } }));
   }
   if (index instanceof Blob) {
+    if (pwa && (!index.type || index.type.includes("text/html"))) {
+      return withSecurityHeaders(new Response(injectPwaHeadTags(await index.text(), pwa), { headers: { "content-type": index.type || "text/html; charset=utf-8" } }));
+    }
     return withSecurityHeaders(new Response(index));
   }
   return index as Response;
@@ -171,7 +420,11 @@ function secureDynamicResponse(response: Response): Response {
 }
 
 function canRespondWithIndex(index: unknown): boolean {
-  return index instanceof Response || typeof index === "string" || index instanceof Blob;
+  return index instanceof Response || typeof index === "string" || index instanceof Blob || isHtmlBundleIndex(index);
+}
+
+function hasOwnPublicRoute(publicRoutes: Record<string, PublicRouteDefinition>, path: string): boolean {
+  return Object.prototype.hasOwnProperty.call(publicRoutes, path);
 }
 
 function scopesFromBearer(claims: { scope: string }): string[] {
@@ -297,6 +550,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
   const wsPath = input.realtime?.path ?? "/api/ws";
   const routes = input.routes ?? {};
   const publicRoutes = input.publicRoutes ?? {};
+  const pwa = normalizePwaConfig(config.appName, input.pwa);
   const appWebsockets = input.websockets ?? {};
   const passkeysEnabled = input.auth?.passkeys !== false;
   const apiKeysEnabled = input.auth?.apiKeys ?? false;
@@ -704,7 +958,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         return successResponse({ success: true, message: "Server is shutting down" });
       }
       if (deviceAuthEnabled && path === "/device" && req.method === "GET") {
-        return htmlResponse(input.index);
+        return htmlResponse(input.index, pwa, req);
       }
     } catch (error) {
       return authErrorResponse(error);
@@ -714,6 +968,9 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
 
   async function handlePublicRoute(req: Request): Promise<Response | undefined> {
     const url = new URL(req.url);
+    if (!hasOwnPublicRoute(publicRoutes, url.pathname)) {
+      return undefined;
+    }
     const route = publicRoutes[url.pathname];
     if (!route) {
       return undefined;
@@ -740,6 +997,20 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
     return response;
   }
 
+  function handlePwaManifest(req: Request): Response | undefined {
+    if (!pwa || new URL(req.url).pathname !== pwa.manifestPath || hasOwnPublicRoute(publicRoutes, pwa.manifestPath)) {
+      return undefined;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      return withSecurityHeaders(methodNotAllowed());
+    }
+    const response = pwaManifestResponse(pwa);
+    if (req.method === "HEAD") {
+      return new Response(null, { status: response.status, statusText: response.statusText, headers: response.headers });
+    }
+    return response;
+  }
+
   async function handleMatchedRoute(req: Request, matched: NonNullable<ReturnType<typeof matchRoute<TEvent>>>, server?: Server<WebAppWebSocketData>): Promise<Response | undefined> {
     const handler = matched.route[method(req) ?? "GET"];
     if (!handler) {
@@ -804,6 +1075,10 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
     if (publicRoute) {
       return publicRoute;
     }
+    const manifest = handlePwaManifest(req);
+    if (manifest) {
+      return manifest;
+    }
     const matched = matchRoute(routes, url.pathname);
     if (url.pathname.startsWith("/api/") || url.pathname.startsWith("/.well-known/") || url.pathname === "/device") {
       const builtIn = await handleBuiltIn(req, server);
@@ -818,7 +1093,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
     if (matched) {
       return handleMatchedRoute(req, matched, server);
     }
-    return htmlResponse(input.index);
+    return htmlResponse(input.index, pwa, req);
   }
 
   function customHandler(socket: ServerWebSocket<WebAppWebSocketData>): Partial<WebSocketHandler<WebAppWebSocketData>> | undefined {
@@ -829,16 +1104,20 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
   function start(): Server<WebAppWebSocketData> {
     const dynamicHandler = (req: Request, server: Server<WebAppWebSocketData>) => handleRequest(req, server);
     const publicRouteHandlers = Object.fromEntries(Object.keys(publicRoutes).map((path) => [path, dynamicHandler]));
+    const pwaRouteHandlers = pwa && !hasOwnPublicRoute(publicRoutes, pwa.manifestPath) ? { [pwa.manifestPath]: dynamicHandler } : {};
+    const indexCanRespond = canRespondWithIndex(input.index);
+    const indexIsHtmlBundle = isHtmlBundleIndex(input.index);
     const server = Bun.serve<WebAppWebSocketData>({
       hostname: config.host,
       port: config.port,
       routes: {
         ...publicRouteHandlers,
+        ...pwaRouteHandlers,
         "/api/*": dynamicHandler,
         "/.well-known/*": dynamicHandler,
-        "/device": deviceAuthEnabled && !canRespondWithIndex(input.index) ? input.index as never : dynamicHandler,
-        "/setup": passkeysEnabled && !canRespondWithIndex(input.index) ? input.index as never : dynamicHandler,
-        "/*": canRespondWithIndex(input.index) ? dynamicHandler : input.index as never,
+        "/device": deviceAuthEnabled && (!indexCanRespond || indexIsHtmlBundle) ? input.index as never : dynamicHandler,
+        "/setup": passkeysEnabled && (!indexCanRespond || indexIsHtmlBundle) ? input.index as never : dynamicHandler,
+        "/*": indexCanRespond && !indexIsHtmlBundle ? dynamicHandler : input.index as never,
       },
       websocket: {
         open(socket) {

package/src/web/WebAppRoot.tsx

@@ -84,7 +84,7 @@ function isSidebarShortcutEditableTarget(target: EventTarget | null): boolean {
     || target instanceof HTMLSelectElement;
 }
 
-function routeToHash(route: WebAppRoute): string {
+export function routeToHash(route: WebAppRoute): string {
   const params = new URLSearchParams();
   for (const [key, value] of Object.entries(route)) {
     if (key !== "view" && value !== undefined) {
@@ -94,6 +94,30 @@ function routeToHash(route: WebAppRoute): string {
   return `#/${route.view}${params.size ? `?${params.toString()}` : ""}`;
 }
 
+export function replaceHashRoute(hash: string): boolean {
+  const normalizedHash = hash.startsWith("#") ? hash : `#${hash}`;
+  if (window.location.hash === normalizedHash) {
+    return false;
+  }
+
+  const previousUrl = window.location.href;
+  let hashChangeEmitted = false;
+  const markHashChangeEmitted = () => {
+    hashChangeEmitted = true;
+  };
+  window.addEventListener("hashchange", markHashChangeEmitted, { once: true });
+  window.history.replaceState(window.history.state, "", normalizedHash);
+  window.removeEventListener("hashchange", markHashChangeEmitted);
+  if (!hashChangeEmitted) {
+    window.dispatchEvent(new HashChangeEvent("hashchange", { oldURL: previousUrl, newURL: window.location.href }));
+  }
+  return true;
+}
+
+export function replaceWebAppRoute(route: WebAppRoute): boolean {
+  return replaceHashRoute(routeToHash(route));
+}
+
 function parseRoute(defaultRoute: WebAppRoute): WebAppRoute {
   const hash = window.location.hash.replace(/^#\/?/, "");
   if (!hash) return defaultRoute;
@@ -110,8 +134,9 @@ function useRoute(defaultRoute: WebAppRoute) {
     return () => window.removeEventListener("hashchange", listener);
   }, [defaultRoute]);
   const navigate = useCallback((next: WebAppRoute) => {
-    window.location.hash = routeToHash(next);
-    setRoute(next);
+    if (replaceWebAppRoute(next)) {
+      setRoute(next);
+    }
   }, []);
   return { route, navigate };
 }