@djangocfg/layouts 2.1.607 → 2.1.609

package/src/components/account/useAccountModel.tsx

@@ -0,0 +1,76 @@
+/**
+ * What the account menu shows, shared by every place it can live (sidebar footer, top bar avatar): the user, the
+ * display fields and the menu items. One source, so the menus can never drift apart.
+ */
+
+'use client';
+
+import React from 'react';
+
+import { useAuth } from '@djangocfg/api/auth';
+import type { MenuItem } from '@djangocfg/ui-core/components';
+
+import type { UserMenuGroup, UserMenuLocaleConfig } from '../../layouts/types';
+import { useAccountMenuItems } from './useAccountMenuItems';
+
+export interface AccountView {
+  source: 'user' | 'dev-fallback';
+  displayName: string;
+  email: string | null;
+  avatarUrl: string;
+  plan: string | null;
+}
+
+export interface UseAccountModelOptions {
+  /** App link groups. */
+  groups?: UserMenuGroup[];
+  /** Plan shown after the name in the footer trigger. */
+  plan?: string | null;
+  i18n?: UserMenuLocaleConfig;
+  /** Extra items between the groups and Sign out (language, app links). */
+  extra?: MenuItem[];
+  /** Settings rows in the menu. @default true */
+  settings?: boolean;
+  /** Identity block above the items: the `email` (default) or a name + email `card`. */
+  identity?: 'email' | 'card';
+}
+
+export function useAccountModel({ groups, plan = null, i18n, settings = true, extra, identity = 'email' }: UseAccountModelOptions = {}) {
+  const { user } = useAuth();
+
+  /**
+   * When `useAuth` returns a real user we use it; otherwise (dev only) a placeholder keeps the menu reachable for
+   * debugging. Production stays strict: callers render nothing without a user.
+   */
+  const account = React.useMemo<AccountView>(() => {
+    if (user) {
+      return {
+        source: 'user',
+        displayName: user.display_username || user.email || 'User',
+        email: user.email ?? null,
+        avatarUrl: user.avatar ?? '',
+        plan,
+      };
+    }
+    return {
+      source: 'dev-fallback',
+      displayName: 'Guest (dev)',
+      email: null,
+      avatarUrl: '',
+      plan: plan ?? 'No session',
+    };
+  }, [user, plan]);
+
+  const headerLabel: React.ReactNode =
+    identity === 'card' ? (
+      <div className="flex flex-col space-y-1">
+        <p className="text-sm font-medium leading-none">{account.displayName}</p>
+        <p className="text-xs leading-none text-muted-foreground">{account.email}</p>
+      </div>
+    ) : (
+      account.email ?? (account.source === 'dev-fallback' ? 'No active session' : null)
+    );
+  const menuItems = useAccountMenuItems({ groups, label: headerLabel, i18n, settings, extra });
+
+  return { user, account, menuItems };
+}

package/src/components/errors/AppErrorFallback.test.tsx

@@ -0,0 +1,33 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AppErrorFallback } from './AppErrorFallback';
+
+vi.mock('@djangocfg/i18n', () => ({
+  getT: (key: string) => key,
+}));
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function render(props = {}) {
+  const host = document.createElement('div');
+  act(() => createRoot(host).render(<AppErrorFallback {...props} />));
+  return host;
+}
+
+describe('AppErrorFallback', () => {
+  it('renders exactly one action button', () => {
+    const host = render();
+    const buttons = host.querySelectorAll('button');
+    expect(buttons).toHaveLength(1);
+    expect(buttons[0]!.textContent).toBe('layouts.errors.refreshPage');
+  });
+
+  it('keeps one button when a support email is shown', () => {
+    const host = render({ supportEmail: 'help@example.com' });
+    expect(host.querySelectorAll('button')).toHaveLength(1);
+    expect(host.querySelector('a[href="mailto:help@example.com"]')).not.toBeNull();
+  });
+});

package/src/components/errors/AppErrorFallback.tsx

@@ -0,0 +1,42 @@
+/**
+ * AppErrorFallback — the one localized crash screen for Next app layouts.
+ *
+ * Exactly ONE action: "Refresh Page" (hard reload). A soft `reset()` re-mounts
+ * the same broken tree and usually crashes again, so it is not offered as a
+ * second near-identical button. Used by `BaseApp` (via UiProviders) and
+ * `ErrorBoundary`.
+ */
+
+'use client';
+
+import { getT } from '@djangocfg/i18n';
+
+export interface AppErrorFallbackProps {
+  supportEmail?: string;
+}
+
+export function AppErrorFallback({ supportEmail }: AppErrorFallbackProps) {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-background p-4">
+      <div className="max-w-md w-full space-y-4 text-center">
+        <h1 className="text-2xl font-bold text-foreground">{getT('layouts.errors.somethingWentWrong')}</h1>
+        <p className="text-muted-foreground">{getT('layouts.errors.tryRefreshing')}</p>
+        {supportEmail && (
+          <p className="text-sm text-muted-foreground">
+            {getT('layouts.errors.persistsContact', { email: '' })}{' '}
+            <a href={`mailto:${supportEmail}`} className="text-primary hover:underline">
+              {supportEmail}
+            </a>
+          </p>
+        )}
+        <button
+          type="button"
+          onClick={() => window.location.reload()}
+          className="rounded-md bg-primary px-4 py-2 text-primary-foreground hover:bg-primary/90"
+        >
+          {getT('layouts.errors.refreshPage')}
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/errors/ErrorBoundary.tsx

@@ -13,7 +13,7 @@
 import { useMemo, type ComponentType, type ErrorInfo, type ReactNode } from 'react';
 
 import { Boundary, type BoundaryRenderProps } from '@djangocfg/ui-core/components';
-import { getT } from '@djangocfg/i18n';
+import { AppErrorFallback } from './AppErrorFallback';
 
 interface ErrorBoundaryProps {
   children: ReactNode;
@@ -21,50 +21,13 @@ interface ErrorBoundaryProps {
   onError?: (error: Error, errorInfo: ErrorInfo) => void;
 }
 
-/** Localized fullscreen fallback. `reset()` re-mounts the tree (ui-core); we
- *  also offer a hard reload, matching the prior behavior. */
-function makeFallback(supportEmail?: string) {
-  return function ErrorFallback({ reset }: BoundaryRenderProps) {
-    const title = getT('layouts.errors.somethingWentWrong');
-    const description = getT('layouts.errors.tryRefreshing');
-    const refreshButton = getT('layouts.errors.refreshPage');
-    return (
-      <div className="flex min-h-screen items-center justify-center bg-background p-4">
-        <div className="max-w-md w-full space-y-4 text-center">
-          <h1 className="text-2xl font-bold text-foreground">{title}</h1>
-          <p className="text-muted-foreground">{description}</p>
-          {supportEmail && (
-            <p className="text-sm text-muted-foreground">
-              {getT('layouts.errors.persistsContact', { email: '' })}{' '}
-              <a
-                href={`mailto:${supportEmail}`}
-                className="text-primary hover:underline"
-              >
-                {supportEmail}
-              </a>
-            </p>
-          )}
-          <button
-            onClick={() => {
-              reset();
-              // Hard reload as a fallback if a pure reset can't recover.
-              window.location.reload();
-            }}
-            className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
-          >
-            {refreshButton}
-          </button>
-        </div>
-      </div>
-    );
-  };
-}
-
 export function ErrorBoundary({ children, supportEmail, onError }: ErrorBoundaryProps) {
   // Memoize so the boundary's FallbackComponent identity is stable across
   // renders (no remount churn).
   const Fallback = useMemo<ComponentType<BoundaryRenderProps>>(
-    () => makeFallback(supportEmail),
+    () => function ErrorFallback() {
+      return <AppErrorFallback supportEmail={supportEmail} />;
+    },
     [supportEmail],
   );
   return (

package/src/components/errors/ErrorLayout.tsx

@@ -17,9 +17,10 @@
 
 'use client';
 
-import React, { useMemo } from 'react';
+import React, { useEffect, useMemo } from 'react';
 
 import { Button } from '@djangocfg/ui-core/components';
+import { canAutoReloadForChunk, isChunkLoadError, reloadForChunkError } from '@djangocfg/ui-core/lib';
 import { useAppT } from '@djangocfg/i18n';
 
 import { getErrorContent } from './errorConfig';
@@ -54,6 +55,14 @@ export interface ErrorLayoutProps {
    * it finally matters.
    */
   statusUrl?: string;
+  /**
+   * The caught error (`global-error.tsx` / `error.tsx` receive it as `error`).
+   * When it is a stale-chunk failure (ChunkLoadError, cancelled `/_next/static`
+   * fetch after a deploy) the page reloads ONCE (sessionStorage loop guard) and
+   * renders nothing meanwhile; if the reload already happened, the normal error
+   * screen is shown.
+   */
+  error?: unknown;
 }
 
 /**
@@ -82,8 +91,13 @@ export function ErrorLayout({
   illustration,
   supportEmail = 'support@example.com',
   statusUrl,
+  error,
 }: ErrorLayoutProps) {
   const t = useAppT();
+  const staleChunk = error !== undefined && isChunkLoadError(error);
+  useEffect(() => {
+    if (staleChunk) reloadForChunkError();
+  }, [staleChunk]);
 
   const labels = useMemo(() => ({
     goBack: t('layouts.errors.goBack'),
@@ -121,6 +135,8 @@ export function ErrorLayout({
     window.location.href = '/';
   };
 
+  if (staleChunk && canAutoReloadForChunk()) return null;
+
   return (
     <div className="min-h-screen flex items-center justify-center px-4 bg-background">
       <div className="max-w-2xl w-full text-center space-y-8">

package/src/components/errors/README.md

@@ -11,11 +11,16 @@ All boundaries here build on the single `Boundary` primitive in
 
 | File | What it does |
 |------|--------------|
-| `ErrorBoundary.tsx` | Thin wrapper over ui-core `Boundary` — i18n fallback + support email (for direct use; `BaseApp` no longer wraps it). |
+| `AppErrorFallback.tsx` | The one localized crash screen: title, text, support email, ONE "Refresh Page" button (hard reload). Used by `BaseApp` and `ErrorBoundary`. |
+| `ErrorBoundary.tsx` | Thin wrapper over ui-core `Boundary` — renders `AppErrorFallback` (for direct use; `BaseApp` no longer wraps it). |
 | `MonitorBoundary.tsx` | ui-core `Boundary` that also reports to `@djangocfg/devtools`. |
 | `ErrorLayout.tsx` | Full-page error layout (`getErrorContent` / `ERROR_CODES`). |
 | `ErrorsTracker/` | Global runtime tracker — listens for error CustomEvents and shows toasts. |
 
+## Stale chunks after a deploy
+
+A chunk-load failure (ChunkLoadError, "Loading chunk N failed", dynamic import failure, cancelled fetch of `/_next/static/...`) is a stale tab, not a crash: the page reloads ONCE instead of showing the error screen. Logic lives in `@djangocfg/ui-core/lib` (`chunk-reload.ts`), wired in `Boundary` (render errors), `UiProviders` (window `error` + `unhandledrejection`) and `ErrorLayout error={error}` (`global-error.tsx`). Loop guard: `sessionStorage` key `djangocfg:chunk-reload-at`, 30 s window; with storage blocked no auto reload. Tests: `chunkReload.test.ts`, `AppErrorFallback.test.tsx`.
+
 ## ErrorLayout — `statusUrl`
 
 `ErrorLayout` takes an optional `statusUrl`, rendered as a secondary link beside

package/src/components/errors/chunkReload.test.ts

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  CHUNK_RELOAD_STORAGE_KEY,
+  CHUNK_RELOAD_WINDOW_MS,
+  canAutoReloadForChunk,
+  installChunkReloadListeners,
+  isChunkLoadError,
+  isStaticAssetLoadEvent,
+  reloadForChunkError,
+} from '@djangocfg/ui-core/lib';
+
+describe('isChunkLoadError', () => {
+  it.each([
+    ['ChunkLoadError by name', Object.assign(new Error('x'), { name: 'ChunkLoadError' })],
+    ['webpack JS chunk', new Error('Loading chunk 123 failed.\n(error: /_next/static/chunks/123.js)')],
+    ['webpack CSS chunk', new Error('Loading CSS chunk 45 failed.')],
+    ['Chrome dynamic import', new TypeError('Failed to fetch dynamically imported module: /_next/static/a.js')],
+    ['Firefox dynamic import', new TypeError('error loading dynamically imported module')],
+    ['Safari module script', new TypeError('Importing a module script failed.')],
+    ['cancelled fetch of static asset', new TypeError('Failed to fetch /_next/static/chunks/app/page-abc.js')],
+    ['aborted static asset via stack', Object.assign(new Error('signal is aborted'), { stack: 'at https://x.io/_next/static/chunks/1.js:1' })],
+    ['string reason', 'Loading chunk 9 failed.'],
+  ])('detects %s', (_n, err) => expect(isChunkLoadError(err)).toBe(true));
+
+  it.each([
+    ['ordinary error', new Error('Cannot read properties of undefined')],
+    ['API fetch failure', new TypeError('Failed to fetch https://api.example.com/items')],
+    ['null', null],
+    ['undefined', undefined],
+  ])('ignores %s', (_n, err) => expect(isChunkLoadError(err)).toBe(false));
+});
+
+describe('isStaticAssetLoadEvent', () => {
+  it('matches failed script/link under /_next/static and nothing else', () => {
+    const script = document.createElement('script');
+    script.src = 'https://x.io/_next/static/chunks/1.js';
+    const other = document.createElement('script');
+    other.src = 'https://cdn.io/lib.js';
+    const link = document.createElement('link');
+    link.href = 'https://x.io/_next/static/css/a.css';
+    const mk = (target: Element) => Object.defineProperty(new Event('error'), 'target', { value: target });
+    expect(isStaticAssetLoadEvent(mk(script))).toBe(true);
+    expect(isStaticAssetLoadEvent(mk(link))).toBe(true);
+    expect(isStaticAssetLoadEvent(mk(other))).toBe(false);
+  });
+});
+
+describe('reload guard', () => {
+  const reload = vi.fn();
+  beforeEach(() => {
+    sessionStorage.clear();
+    reload.mockClear();
+    Object.defineProperty(window, 'location', { configurable: true, value: { ...window.location, reload } });
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it('reloads once, then blocks a second reload inside the window', () => {
+    expect(reloadForChunkError(1_000)).toBe(true);
+    expect(sessionStorage.getItem(CHUNK_RELOAD_STORAGE_KEY)).toBe('1000');
+    expect(reloadForChunkError(1_000 + 5_000)).toBe(false);
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows another reload after the window passes', () => {
+    reloadForChunkError(1_000);
+    expect(canAutoReloadForChunk(1_000 + CHUNK_RELOAD_WINDOW_MS + 1)).toBe(true);
+  });
+
+  it('never reloads when sessionStorage is unusable (no loop risk)', () => {
+    vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new Error('denied');
+    });
+    expect(canAutoReloadForChunk()).toBe(false);
+    expect(reloadForChunkError()).toBe(false);
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it('window listeners reload once for an unhandled chunk rejection', () => {
+    const off = installChunkReloadListeners();
+    const ev = new Event('unhandledrejection') as Event & { reason?: unknown };
+    ev.reason = new Error('Loading chunk 7 failed.');
+    window.dispatchEvent(ev);
+    window.dispatchEvent(ev);
+    expect(reload).toHaveBeenCalledTimes(1);
+    off();
+  });
+});

package/src/components/errors/index.ts

@@ -3,6 +3,8 @@
  */
 
 export { ErrorBoundary } from './ErrorBoundary';
+export { AppErrorFallback } from './AppErrorFallback';
+export type { AppErrorFallbackProps } from './AppErrorFallback';
 export { MonitorBoundary } from './MonitorBoundary';
 export type { MonitorBoundaryProps } from './MonitorBoundary';
 export { ErrorLayout } from './ErrorLayout';

package/src/layouts/AppLayout/BaseApp.tsx

@@ -54,65 +54,21 @@ import { useScrollToTop } from '@djangocfg/ui-core/hooks';
 import { NextRouterAdapter, NextLinkProvider } from '@djangocfg/ui-core/adapters/nextjs';
 import { NextIntlLinkBridge } from './NextIntlLinkBridge';
 import { ThemeProvider } from '@djangocfg/ui-core/theme';
-import type { BoundaryRenderProps } from '@djangocfg/ui-core/components';
-import { getT } from '@djangocfg/i18n';
+import { AppErrorFallback } from '../../components/errors/AppErrorFallback';
 import { ErrorTrackingProvider } from '../../components/errors/ErrorsTracker';
 import { AnalyticsProvider } from '../../snippets/Analytics';
 import { AuthDialog } from '../../snippets/AuthDialog';
 
 import type { BaseLayoutProps } from '../types/layout.types';
 import { LayoutI18nProvider } from '../../shared/LayoutI18nProvider';
+import { ProjectNameProvider } from '../../shared/ProjectContext';
+import { PwaMetaGuard } from './pwaMeta';
 
 import React from 'react';
 
 // For backwards compatibility, re-export as BaseAppProps
 export type BaseAppProps = BaseLayoutProps;
 
-/**
- * Localized crash fallback fed into UiProviders' built-in Boundary. Renders the
- * i18n'd "something went wrong" screen + optional support email. `reset()`
- * re-mounts (soft recover); the Reload button hard-reloads when a soft reset
- * can't recover (e.g. the crash is in a provider above the boundary's subtree).
- */
-function AppErrorFallback({
-  reset,
-  supportEmail,
-}: BoundaryRenderProps & { supportEmail?: string }) {
-  const title = getT('layouts.errors.somethingWentWrong');
-  const description = getT('layouts.errors.tryRefreshing');
-  const retry = getT('layouts.errors.refreshPage');
-  return (
-    <div className="flex min-h-screen items-center justify-center bg-background p-4">
-      <div className="max-w-md w-full space-y-4 text-center">
-        <h1 className="text-2xl font-bold text-foreground">{title}</h1>
-        <p className="text-muted-foreground">{description}</p>
-        {supportEmail && (
-          <p className="text-sm text-muted-foreground">
-            {getT('layouts.errors.persistsContact', { email: '' })}{' '}
-            <a href={`mailto:${supportEmail}`} className="text-primary hover:underline">
-              {supportEmail}
-            </a>
-          </p>
-        )}
-        <div className="flex items-center justify-center gap-2">
-          <button
-            onClick={reset}
-            className="rounded-md bg-primary px-4 py-2 text-primary-foreground hover:bg-primary/90"
-          >
-            {retry}
-          </button>
-          <button
-            onClick={() => window.location.reload()}
-            className="rounded-md border border-border px-4 py-2 text-foreground hover:bg-muted"
-          >
-            {getT('layouts.errors.refreshPage')}
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-}
-
 /**
  * Lands every forward navigation at the top of the page.
  *
@@ -150,6 +106,7 @@ export function BaseApp({
   swr,
   devtools: devtoolsConfig,
   i18n,
+  pwaMeta = true,
 }: BaseAppProps) {
   // auth=false disables AuthProvider entirely (public apps with no login)
   const authEnabled = auth !== false;
@@ -167,6 +124,8 @@ export function BaseApp({
   };
 
   const content = (
+    <>
+    {pwaMeta && <PwaMetaGuard />}
     <ThemeProvider
       defaultTheme={theme?.defaultTheme || 'system'}
       storageKey={theme?.storageKey}
@@ -189,9 +148,7 @@ export function BaseApp({
         onError={errorBoundary?.onError}
         errorFallback={
           enableErrorBoundary
-            ? (props) => (
-                <AppErrorFallback {...props} supportEmail={errorBoundary?.supportEmail} />
-              )
+            ? () => <AppErrorFallback supportEmail={errorBoundary?.supportEmail} />
             : undefined
         }
       >
@@ -214,11 +171,13 @@ export function BaseApp({
                 <ScrollToTop />
                 <Devtools {...devtoolsProps} />
                 <LayoutI18nProvider value={i18n}>
-                  {i18n?.routing ? (
-                    <NextIntlLinkBridge routing={i18n.routing}>{children}</NextIntlLinkBridge>
-                  ) : (
-                    children
-                  )}
+                  <ProjectNameProvider value={project}>
+                    {i18n?.routing ? (
+                      <NextIntlLinkBridge routing={i18n.routing}>{children}</NextIntlLinkBridge>
+                    ) : (
+                      children
+                    )}
+                  </ProjectNameProvider>
                 </LayoutI18nProvider>
                 <NextTopLoader
                   color="var(--primary)"
@@ -237,6 +196,7 @@ export function BaseApp({
       </NextLinkProvider>
       </NextRouterAdapter>
     </ThemeProvider>
+    </>
   );
 
   // The error boundary is now UiProviders' built-in one (fed our i18n fallback

package/src/layouts/AppLayout/index.ts

@@ -13,6 +13,7 @@ export type { BaseAppProps } from './BaseApp';
 
 export type { I18nLayoutConfig } from '../types';
 
+export { ProjectNameProvider, useProjectName } from '../../shared/ProjectContext';
 export {
   LayoutI18nProvider,
   useLayoutI18n,

package/src/layouts/AppLayout/pwaMeta.test.ts

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { PWA_META_SCRIPT } from './pwaMeta';
+
+const meta = (n: string) => document.head.querySelector(`meta[name="${n}"]`)?.getAttribute('content');
+const run = () => new Function(PWA_META_SCRIPT)();
+
+describe('PWA_META_SCRIPT', () => {
+  beforeEach(() => {
+    document.head.innerHTML = '';
+  });
+
+  it('adds viewport-fit=cover to an existing viewport and the iOS app tags', () => {
+    document.head.innerHTML = '<meta name="viewport" content="width=device-width, initial-scale=1">';
+    run();
+    expect(meta('viewport')).toBe('width=device-width, initial-scale=1, viewport-fit=cover');
+    expect(meta('apple-mobile-web-app-capable')).toBe('yes');
+    expect(meta('mobile-web-app-capable')).toBe('yes');
+    expect(meta('apple-mobile-web-app-status-bar-style')).toBe('black-translucent');
+  });
+
+  it('creates a viewport when none exists', () => {
+    run();
+    expect(meta('viewport')).toContain('viewport-fit=cover');
+  });
+
+  it('never overrides what the app set', () => {
+    document.head.innerHTML =
+      '<meta name="viewport" content="width=device-width, viewport-fit=contain">' +
+      '<meta name="apple-mobile-web-app-status-bar-style" content="default">';
+    run();
+    expect(meta('viewport')).toBe('width=device-width, viewport-fit=contain');
+    expect(meta('apple-mobile-web-app-status-bar-style')).toBe('default');
+  });
+});

package/src/layouts/AppLayout/pwaMeta.tsx

@@ -0,0 +1,40 @@
+/**
+ * Installed-app `<meta>` tags, applied by `BaseApp` so an app does not have to remember them.
+ *
+ * Next's App Router builds `<head>` from the server `viewport` / `metadata` exports; a client component such as
+ * `BaseApp` cannot contribute to them, and a second `<meta name="viewport">` would fight Next's own. So this is a tiny
+ * inline script (it runs while the HTML is parsed, before first paint) that completes what is missing in `<head>`:
+ *
+ *   viewport                              + `viewport-fit=cover` (without it every `--safe-*` inset is 0 and the
+ *                                           installed iOS app letterboxes)
+ *   apple-mobile-web-app-capable          yes   (Next 16 only emits `mobile-web-app-capable`; iOS < 26 needs the apple tag)
+ *   mobile-web-app-capable                yes
+ *   apple-mobile-web-app-status-bar-style black-translucent
+ *
+ * Existing tags are never overridden (an app's own `appleWebApp.statusBarStyle` wins); only `viewport-fit` is added to
+ * an existing viewport that lacks it. A MutationObserver re-applies it if a client navigation rewrites the viewport tag.
+ * Prefer exporting `viewport = createViewport(...)` (default `viewportFit: 'cover'`): that puts it in the server HTML;
+ * this is the safety net for apps that forgot.
+ */
+
+import * as React from 'react';
+
+export const PWA_META_SCRIPT = `(function(){try{
+var d=document,h=d.head;if(!h)return;
+function q(n){return h.querySelector('meta[name="'+n+'"]')}
+function ensure(n,c){if(!q(n)){var m=d.createElement('meta');m.name=n;m.content=c;h.appendChild(m)}}
+function fit(){var v=q('viewport');
+if(!v){v=d.createElement('meta');v.name='viewport';v.content='width=device-width, initial-scale=1, viewport-fit=cover';h.appendChild(v);return}
+var c=v.getAttribute('content')||'';
+if(!/viewport-fit\\s*=/.test(c))v.setAttribute('content',(c?c+', ':'')+'viewport-fit=cover')}
+fit();
+ensure('apple-mobile-web-app-capable','yes');
+ensure('mobile-web-app-capable','yes');
+ensure('apple-mobile-web-app-status-bar-style','black-translucent');
+if(window.MutationObserver){new MutationObserver(function(){var v=q('viewport');if(!v||!/viewport-fit\\s*=\\s*cover/.test(v.getAttribute('content')||''))fit()}).observe(h,{subtree:true,childList:true,attributes:true,attributeFilter:['content']})}
+}catch(e){}})();`;
+
+/** Renders the inline script. Server-rendered into the HTML; React does not re-run it on hydration. */
+export function PwaMetaGuard() {
+  return <script dangerouslySetInnerHTML={{ __html: PWA_META_SCRIPT }} suppressHydrationWarning />;
+}