@djangocfg/ui-core 2.1.607 → 2.1.608

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.607",
+  "version": "2.1.608",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -133,8 +133,8 @@
     "check:docs": "node scripts/check-docs.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.607",
-    "@djangocfg/i18n": "^2.1.607",
+    "@djangocfg/api": "^2.1.608",
+    "@djangocfg/i18n": "^2.1.608",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -210,10 +210,10 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.607",
-    "@djangocfg/eslint-config": "^2.1.607",
-    "@djangocfg/i18n": "^2.1.607",
-    "@djangocfg/typescript-config": "^2.1.607",
+    "@djangocfg/api": "^2.1.608",
+    "@djangocfg/eslint-config": "^2.1.608",
+    "@djangocfg/i18n": "^2.1.608",
+    "@djangocfg/typescript-config": "^2.1.608",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

package/src/components/boundary/Boundary.tsx

@@ -10,6 +10,7 @@ import {
   type ReactNode,
 } from 'react';
 
+import { canAutoReloadForChunk, isChunkLoadError, reloadForChunkError } from '../../lib/chunk-reload';
 import { isDev } from '../../lib/env';
 import { cn } from '../../lib/utils';
 import { Button } from '../forms/button';
@@ -155,12 +156,17 @@ export class Boundary extends Component<BoundaryProps, BoundaryState> {
   /** Prevents `onError` from firing twice for the same error instance. */
   private lastReportedError: Error | null = null;
 
+  /** True once a stale-chunk auto-reload was triggered; the fallback stays hidden meanwhile. */
+  private chunkReloading = false;
+
   static getDerivedStateFromError(error: unknown): BoundaryState {
     return { error: toError(error), errorInfo: null };
   }
 
   override componentDidCatch(error: Error, info: ErrorInfo) {
     const normalized = toError(error);
+    // Stale chunk after a deploy: one guarded hard reload instead of the crash screen.
+    if (isChunkLoadError(normalized) && reloadForChunkError()) this.chunkReloading = true;
     this.setState({ errorInfo: info });
 
     if (this.lastReportedError === normalized) return;
@@ -224,6 +230,7 @@ export class Boundary extends Component<BoundaryProps, BoundaryState> {
   private safeRenderFallback(): ReactNode {
     const { error, errorInfo } = this.state;
     if (!error) return null;
+    if (isChunkLoadError(error) && (this.chunkReloading || canAutoReloadForChunk())) return null;
 
     const { fallback, FallbackComponent, variant = 'card', className } = this.props;
 
@@ -314,7 +321,7 @@ function renderVariant(
       <div
         role="alert"
         aria-live="assertive"
-        className={cn('flex min-h-screen items-center justify-center bg-background p-4', className)}
+        className={cn('flex min-h-[var(--app-height,100dvh)] items-center justify-center bg-background p-4', className)}
       >
         <div className="max-w-md w-full space-y-4 text-center">
           <AlertTriangle className="mx-auto h-10 w-10 text-destructive" />

package/src/components/feedback/sonner/index.tsx

@@ -12,6 +12,9 @@ const Toaster = ({ ...props }: ToasterProps) => {
     <Sonner
       theme={theme as ToasterProps["theme"]}
       className="toaster group"
+      // Keep toasts clear of the notch / home indicator (tokens are 0 without viewport-fit=cover).
+      offset={{ top: 'max(24px, var(--safe-top, 0px))', bottom: 'max(24px, var(--safe-bottom, 0px))', left: 'max(24px, var(--safe-left, 0px))', right: 'max(24px, var(--safe-right, 0px))' }}
+      mobileOffset={{ top: 'max(16px, var(--safe-top, 0px))', bottom: 'max(16px, var(--safe-bottom, 0px))', left: 'max(16px, var(--safe-left, 0px))', right: 'max(16px, var(--safe-right, 0px))' }}
       richColors
       toastOptions={{
         classNames: {

package/src/components/index.ts

@@ -179,6 +179,7 @@ export {
   SidebarRail,
   SidebarSeparator,
   SidebarTrigger,
+  SIDEBAR_KEYBOARD_SHORTCUT,
   useSidebar,
 } from './navigation/sidebar';
 export { Stepper, StepperContent, StepperDescription, StepperIndicator, StepperItem, StepperList, StepperNext, StepperPrev, StepperSeparator, StepperTitle, StepperTrigger, useStepper } from './navigation/stepper';

package/src/components/navigation/sidebar/index.ts

@@ -22,5 +22,6 @@ export {
   SidebarRail,
   SidebarSeparator,
   SidebarTrigger,
+  SIDEBAR_KEYBOARD_SHORTCUT,
   useSidebar,
 } from './sidebar';

package/src/components/navigation/sidebar/sidebar.tsx

@@ -21,7 +21,8 @@ const SIDEBAR_COOKIE_NAME = "sidebar_state"
 const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7
 const SIDEBAR_WIDTH = "16rem"
 const SIDEBAR_WIDTH_ICON = "3rem"
-const SIDEBAR_KEYBOARD_SHORTCUT = "b"
+/** Key of the sidebar toggle (with Cmd or Ctrl). Exported so labels cannot diverge from the binding. */
+export const SIDEBAR_KEYBOARD_SHORTCUT = "b"
 
 type SidebarContextProps = {
   state: "expanded" | "collapsed"
@@ -195,8 +196,12 @@ const Sidebar = React.forwardRef<
               direction={drawerSide}
               data-sidebar="sidebar"
               data-mobile="true"
+              bare
               className={cn(
-                "flex h-[100dvh] max-h-[100dvh] min-h-0 !w-[min(88vw,22rem)] max-w-[min(88vw,22rem)] flex-col gap-0 border-sidebar-border/60 p-0 text-sidebar-foreground shadow-xl",
+                // Height pinned to the top and bottom edges of the fixed viewport (`inset-y-0`, `h-auto`) rather
+                // than `h-[100dvh]`, so it equals the real visible area in a browser tab AND in an iOS standalone
+                // PWA (where 100dvh/100vh can disagree). Width stays 88vw (max 22rem): the dimmed strip closes it.
+                "flex !inset-y-0 !h-auto max-h-none min-h-0 overflow-hidden !w-[min(88vw,22rem)] max-w-[min(88vw,22rem)] flex-col gap-0 border-sidebar-border/60 p-0 text-sidebar-foreground shadow-xl",
                 drawerSide === "left" ? "border-r" : "border-l",
               )}
               style={

package/src/components/overlay/dialog/index.tsx

@@ -93,7 +93,7 @@ const DialogContent = React.forwardRef<
           // A child sizing itself with `h-full` then measures that overgrown
           // row, its own `min-h-0`/`overflow-y-auto` never receive a bound, and
           // a long list (e.g. the locale picker) runs off-screen unscrollable.
-          ? "left-0 top-0 grid grid-rows-[minmax(0,1fr)] h-[100dvh] w-screen max-w-none gap-0 border-0 p-0 shadow-none data-[state=closed]:zoom-out-[0.98] data-[state=open]:zoom-in-[0.98]"
+          ? "left-0 top-0 grid grid-rows-[minmax(0,1fr)] h-[var(--app-height,100dvh)] w-screen max-w-none gap-0 border-0 p-0 pt-[var(--safe-top,0px)] pb-[var(--safe-bottom,0px)] shadow-none data-[state=closed]:zoom-out-[0.98] data-[state=open]:zoom-in-[0.98]"
           // Rounded on ALL sizes — the radius used to be `sm:`-gated, which left
           // phone dialogs with hard square corners. Centered, soft-cornered card.
           // Width by MEASUREMENT, not breakpoint: `min()` keeps the card off
@@ -123,7 +123,7 @@ const DialogContent = React.forwardRef<
           // scrolls. The cap is only a ceiling — a card that must scroll adds
           // `overflow-y-auto`, and one laying out its own regions overrides
           // `max-h` as before.
-          : "left-1/2 top-1/2 grid max-h-[calc(100dvh-2rem)] grid-cols-[minmax(0,1fr)] [aspect-ratio:var(--aspect-dialog,auto)] w-[min(var(--width-dialog),calc(100vw-2rem),calc((100dvh-2rem)*var(--aspect-dialog,1000)))] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-[var(--radius-dialog)] border p-6 shadow-lg data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+          : "left-1/2 top-1/2 grid max-h-[calc(var(--app-height,100dvh)-2rem-var(--safe-top,0px)-var(--safe-bottom,0px))] grid-cols-[minmax(0,1fr)] [aspect-ratio:var(--aspect-dialog,auto)] w-[min(var(--width-dialog),calc(100vw-2rem),calc((100dvh-2rem)*var(--aspect-dialog,1000)))] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-[var(--radius-dialog)] border p-6 shadow-lg data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
         className
       )}
       {...props}

package/src/components/overlay/drawer/index.tsx

@@ -105,11 +105,11 @@ const horizontalSizePresets: Record<DrawerSize, string> = {
 };
 
 const verticalSizePresets: Record<DrawerSize, string> = {
-  sm: 'min(100vh, 240px)',
-  md: 'min(100vh, 360px)',
-  lg: 'min(100vh, 480px)',
-  xl: 'min(100vh, 640px)',
-  full: '100vh',
+  sm: 'min(var(--app-height, 100dvh), 240px)',
+  md: 'min(var(--app-height, 100dvh), 360px)',
+  lg: 'min(var(--app-height, 100dvh), 480px)',
+  xl: 'min(var(--app-height, 100dvh), 640px)',
+  full: 'var(--app-height, 100dvh)',
 };
 
 // Numeric fallbacks used as initial size when resize starts and the
@@ -137,10 +137,10 @@ const directionStyles = {
   // a tall panel would otherwise run off the top of a phone. A caller's own
   // `max-h` cannot do this job — as a flex column the panel FILLS it, so the
   // cap becomes a fixed height around short content.
-  bottom: "inset-x-0 bottom-0 mt-24 max-h-[85dvh] rounded-t-lg border-t",
+  bottom: "inset-x-0 bottom-0 mt-24 max-h-[min(85dvh,calc(var(--app-height,100dvh)-var(--safe-top,0px)-1rem))] rounded-t-lg border-t",
   top: "inset-x-0 top-0 mb-24 rounded-b-lg border-b",
-  right: "inset-y-0 right-0 h-full border-l",
-  left: "inset-y-0 left-0 h-full border-r",
+  right: "inset-y-0 right-0 h-auto border-l",
+  left: "inset-y-0 left-0 h-auto border-r",
 } as const;
 
 // The snap-point variant of the above. A snapped panel is FULL height and vaul
@@ -182,6 +182,11 @@ export interface DrawerContentProps
   width?: string | number;
   /** CSS length for height — applies to top/bottom drawers. Overrides `size`. */
   height?: string | number;
+  /**
+   * Render children directly, with no grab handle and no padded scroll wrapper. For app-shell surfaces
+   * (the sidebar drawer) that lay out their own header / scrolling body / footer inside the panel.
+   */
+  bare?: boolean;
   /** Allow user to resize the drawer by dragging its inner edge. */
   resizable?: boolean;
   /** Disable resize on mobile viewports (< 768px). Default `true`. */
@@ -208,6 +213,7 @@ const DrawerContent = React.forwardRef<
   children,
   direction: directionProp,
   size = 'md',
+  bare = false,
   width,
   height,
   style,
@@ -311,7 +317,7 @@ const DrawerContent = React.forwardRef<
     ? (currentPx != null ? `${currentPx}px` : (toCssLength(height) ?? verticalSizePresets[size]))
     : undefined;
   const resolvedWidth = rawWidth ? `min(100vw, ${rawWidth})` : undefined;
-  const resolvedHeight = rawHeight ? `min(100vh, ${rawHeight})` : undefined;
+  const resolvedHeight = rawHeight ? `min(var(--app-height, 100dvh), ${rawHeight})` : undefined;
 
   const handlePosition: Record<typeof direction, string> = {
     right: 'left-0 top-0 h-full w-1.5 -translate-x-1/2 cursor-ew-resize',
@@ -382,7 +388,7 @@ const DrawerContent = React.forwardRef<
             affordance, not an element of the design.
             `aria-hidden` because the drag it hints at is not a keyboard
             affordance — Escape and the close button are. */}
-        {isVertical && (
+        {isVertical && !bare && (
           <div
             aria-hidden
             className="mx-auto mt-3 h-1.5 w-10 shrink-0 rounded-full bg-border"
@@ -409,14 +415,16 @@ const DrawerContent = React.forwardRef<
           leave the rest of the sheet empty and unscrollable — there `flex-1`
           is what makes the body fill the snapped height.
         */}
+        {bare ? children : (
         <div
           className={cn(
-            "min-h-0 overflow-y-auto overscroll-contain px-5 pb-[max(1.25rem,env(safe-area-inset-bottom))]",
+            "min-h-0 overflow-y-auto overscroll-contain px-5 pb-[max(1.25rem,var(--safe-bottom,env(safe-area-inset-bottom,0px)))]",
             hasSnapPoints && "flex-1"
           )}
         >
           {children}
         </div>
+        )}
         </div>
       </DrawerPrimitive.Content>
     </DrawerPortal>

package/src/components/overlay/sheet/index.tsx

@@ -37,12 +37,12 @@ const sheetVariants = cva(
   {
     variants: {
       side: {
-        top: "inset-x-0 top-0 border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
+        top: "inset-x-0 top-0 pt-[max(1.5rem,var(--safe-top,0px))] border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
         bottom:
-          "inset-x-0 bottom-0 border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
-        left: "inset-y-0 left-0 h-full w-3/4 border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm",
+          "inset-x-0 bottom-0 pb-[max(1.5rem,var(--safe-bottom,0px))] border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+        left: "inset-y-0 left-0 h-auto w-3/4 pt-[max(1.5rem,var(--safe-top,0px))] pb-[max(1.5rem,var(--safe-bottom,0px))] border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm",
         right:
-          "inset-y-0 right-0 h-full w-3/4 border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm",
+          "inset-y-0 right-0 h-auto w-3/4 pt-[max(1.5rem,var(--safe-top,0px))] pb-[max(1.5rem,var(--safe-bottom,0px))] border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm",
       },
     },
     defaultVariants: {
@@ -67,7 +67,7 @@ const SheetContent = React.forwardRef<
       className={cn(sheetVariants({ side }), className)}
       {...props}
     >
-      <SheetPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 transition-opacity hover:opacity-100 focus:outline-none focus:ring-1 focus:ring-ring disabled:pointer-events-none data-[state=open]:bg-secondary">
+      <SheetPrimitive.Close className="absolute right-4 top-[max(1rem,var(--safe-top,0px))] rounded-sm opacity-70 transition-opacity hover:opacity-100 focus:outline-none focus:ring-1 focus:ring-ring disabled:pointer-events-none data-[state=open]:bg-secondary">
         <Cross2Icon className="h-4 w-4" />
         <span className="sr-only">Close</span>
       </SheetPrimitive.Close>

package/src/hooks/media/displayMode.ts

@@ -0,0 +1,47 @@
+/**
+ * Display mode of the page: running in a browser tab or as an installed app (PWA).
+ *
+ * One module-level store, so any number of components share ONE set of media-query listeners.
+ * Detection covers the standard `display-mode` media query (standalone, fullscreen, minimal-ui,
+ * window-controls-overlay), legacy iOS `navigator.standalone` ("Add to Home Screen" does not always
+ * match the media query) and the Android TWA referrer.
+ */
+
+export type DisplayMode = 'browser' | 'standalone' | 'fullscreen' | 'minimal-ui' | 'window-controls-overlay';
+
+const MODES = ['window-controls-overlay', 'fullscreen', 'standalone', 'minimal-ui'] as const;
+
+/** Server and hydration value. */
+export const SERVER_DISPLAY_MODE: DisplayMode = 'browser';
+
+export function detectDisplayMode(): DisplayMode {
+  if (typeof window === 'undefined') return SERVER_DISPLAY_MODE;
+  if (window.matchMedia) {
+    for (const mode of MODES) {
+      if (window.matchMedia(`(display-mode: ${mode})`).matches) return mode;
+    }
+  }
+  if ((window.navigator as Navigator & { standalone?: boolean }).standalone === true) return 'standalone';
+  if (typeof document !== 'undefined' && document.referrer.startsWith('android-app://')) return 'standalone';
+  return 'browser';
+}
+
+/** True for every mode where the browser UI is gone (installed app). */
+export function isInstalledMode(mode: DisplayMode): boolean {
+  return mode !== 'browser';
+}
+
+export function subscribeDisplayMode(onChange: () => void): () => void {
+  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
+  const lists = MODES.map((m) => window.matchMedia(`(display-mode: ${m})`));
+  lists.forEach((l) => l.addEventListener('change', onChange));
+  return () => lists.forEach((l) => l.removeEventListener('change', onChange));
+}
+
+/** Sets `<html data-display-mode="browser|standalone|…">` so CSS can react without JS. Returns a cleanup. */
+export function syncDisplayModeAttribute(): () => void {
+  if (typeof document === 'undefined') return () => {};
+  const apply = () => document.documentElement.setAttribute('data-display-mode', detectDisplayMode());
+  apply();
+  return subscribeDisplayMode(apply);
+}

package/src/hooks/media/index.ts

@@ -4,3 +4,7 @@ export { useMediaQuery, BREAKPOINTS as MEDIA_BREAKPOINTS } from './useMediaQuery
 export { useIsMobile, useIsPhone, useIsTabletOrBelow, BREAKPOINTS } from './useMobile';
 export type { Breakpoint } from './useMobile';
 export { useIsTouch } from './useIsTouch';
+export { useDisplayMode, useIsPwa } from './useDisplayMode';
+export { detectDisplayMode, syncDisplayModeAttribute } from './displayMode';
+export type { DisplayMode } from './displayMode';
+export { useBlockGestureZoom } from './useBlockGestureZoom';

package/src/hooks/media/useBlockGestureZoom.ts

@@ -0,0 +1,26 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import { detectDisplayMode, isInstalledMode } from './displayMode';
+
+/**
+ * OPT-IN, off by default: blocks iOS pinch/gesture zoom while running as an installed app.
+ *
+ * Trade-off: it removes the only zoom some people can use (WCAG 1.4.4). The default recipe already disables
+ * double-tap zoom with `touch-action: manipulation` and leaves pinch-zoom alone; use this only for an app whose UI is
+ * a fixed canvas and say so in its accessibility notes. Only acts in an installed display mode, never in a browser tab.
+ */
+export function useBlockGestureZoom(enabled = true): void {
+  useEffect(() => {
+    if (!enabled || typeof document === 'undefined' || !isInstalledMode(detectDisplayMode())) return;
+    const block = (event: Event) => event.preventDefault();
+    // `gesturestart` is a WebKit-only event; other engines never fire it.
+    document.addEventListener('gesturestart', block);
+    document.addEventListener('gesturechange', block);
+    return () => {
+      document.removeEventListener('gesturestart', block);
+      document.removeEventListener('gesturechange', block);
+    };
+  }, [enabled]);
+}

package/src/hooks/media/useDisplayMode.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+import {
+  detectDisplayMode,
+  isInstalledMode,
+  SERVER_DISPLAY_MODE,
+  subscribeDisplayMode,
+  type DisplayMode,
+} from './displayMode';
+
+/**
+ * Current display mode. The server and the hydration render report `'browser'`, the real value
+ * arrives right after (same contract as `useMediaQuery`); let CSS decide where a flash matters:
+ * `:root[data-display-mode='standalone'] { ... }`.
+ */
+export function useDisplayMode(): DisplayMode {
+  return useSyncExternalStore(subscribeDisplayMode, detectDisplayMode, () => SERVER_DISPLAY_MODE);
+}
+
+/** True when the app runs installed (PWA: standalone, fullscreen, minimal-ui, window-controls-overlay). */
+export function useIsPwa(): boolean {
+  return isInstalledMode(useDisplayMode());
+}

package/src/lib/chunk-reload.ts

@@ -0,0 +1,132 @@
+/**
+ * Stale-chunk recovery.
+ *
+ * After a deploy the old tab still points at hashed `/_next/static/...` assets
+ * that no longer exist. The next lazy import / route navigation fails with a
+ * ChunkLoadError (or a cancelled fetch), which is a transient condition, not an
+ * app bug. The right response is ONE hard reload, not the crash screen.
+ *
+ * Single implementation for the whole stack: `Boundary` (render errors),
+ * `UiProviders` (window `error` / `unhandledrejection`) and `ErrorLayout`
+ * (`global-error.tsx`) all call into this module. Loop guard: a timestamp in
+ * `sessionStorage`; a second chunk failure inside the window shows the real
+ * fallback. Without a usable `sessionStorage` we never auto-reload (a reload
+ * would lose any in-memory guard and could loop).
+ */
+
+export const CHUNK_RELOAD_STORAGE_KEY = 'djangocfg:chunk-reload-at';
+/** Minimum gap between two automatic reloads in one tab session. */
+export const CHUNK_RELOAD_WINDOW_MS = 30_000;
+
+const CHUNK_MESSAGE_PATTERNS: RegExp[] = [
+  /loading chunk [\w./-]+ failed/i, // webpack
+  /loading css chunk [\w./-]+ failed/i, // webpack CSS chunk
+  /failed to fetch dynamically imported module/i, // Chrome / Turbopack
+  /error loading dynamically imported module/i, // Firefox
+  /importing a module script failed/i, // Safari
+  /unable to preload css/i, // Vite
+];
+
+const STATIC_ASSET_RE = /\/_next\/static\//;
+const FETCH_FAILURE_RE = /failed to fetch|load failed|networkerror|aborted|canceled|cancelled|signal is aborted/i;
+
+function asText(value: unknown): { name: string; message: string; stack: string } {
+  if (value && typeof value === 'object') {
+    const v = value as { name?: unknown; message?: unknown; stack?: unknown };
+    return {
+      name: typeof v.name === 'string' ? v.name : '',
+      message: typeof v.message === 'string' ? v.message : '',
+      stack: typeof v.stack === 'string' ? v.stack : '',
+    };
+  }
+  return { name: '', message: typeof value === 'string' ? value : '', stack: '' };
+}
+
+/**
+ * True when `error` is the signature of a missing/cancelled build asset:
+ * ChunkLoadError, "Loading chunk N failed", "Loading CSS chunk", dynamic import
+ * failures, or a failed/aborted fetch that names a `/_next/static/` URL.
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  const { name, message, stack } = asText(error);
+  if (name === 'ChunkLoadError') return true;
+  if (CHUNK_MESSAGE_PATTERNS.some((re) => re.test(message))) return true;
+  // Generic network-ish failure only counts when it concerns a build asset.
+  if (FETCH_FAILURE_RE.test(`${name} ${message}`) && STATIC_ASSET_RE.test(`${message} ${stack}`)) {
+    return true;
+  }
+  return false;
+}
+
+/** Resource-load `error` event from a `<script>`/`<link>` pointing at `/_next/static/`. */
+export function isStaticAssetLoadEvent(event: Event): boolean {
+  const target = event.target as { tagName?: string; src?: string; href?: string } | null;
+  if (!target || typeof target.tagName !== 'string') return false;
+  const tag = target.tagName.toUpperCase();
+  if (tag !== 'SCRIPT' && tag !== 'LINK') return false;
+  return STATIC_ASSET_RE.test(target.src || target.href || '');
+}
+
+function readStamp(): number | null | 'unavailable' {
+  try {
+    const raw = window.sessionStorage.getItem(CHUNK_RELOAD_STORAGE_KEY);
+    if (!raw) return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return 'unavailable';
+  }
+}
+
+/** Read-only check: would an automatic reload be allowed right now? */
+export function canAutoReloadForChunk(now: number = Date.now()): boolean {
+  if (typeof window === 'undefined') return false;
+  const stamp = readStamp();
+  if (stamp === 'unavailable') return false;
+  return stamp === null || now - stamp > CHUNK_RELOAD_WINDOW_MS || now < stamp;
+}
+
+/**
+ * Reload once if the guard allows. Returns true when a reload was triggered
+ * (callers should render nothing meanwhile), false when the guard blocked it
+ * (callers show their normal error UI).
+ */
+export function reloadForChunkError(now: number = Date.now()): boolean {
+  if (!canAutoReloadForChunk(now)) return false;
+  try {
+    window.sessionStorage.setItem(CHUNK_RELOAD_STORAGE_KEY, String(now));
+  } catch {
+    return false;
+  }
+  window.location.reload();
+  return true;
+}
+
+/**
+ * Install window-level listeners that catch chunk failures outside React
+ * (route-change imports, failed `<script>`/`<link>` tags, rejected promises).
+ * Idempotent; returns a cleanup function.
+ */
+export function installChunkReloadListeners(): () => void {
+  if (typeof window === 'undefined') return () => {};
+  const w = window as unknown as { __djangocfgChunkReload?: boolean };
+  if (w.__djangocfgChunkReload) return () => {};
+  w.__djangocfgChunkReload = true;
+
+  const onError = (event: Event) => {
+    if (event instanceof ErrorEvent ? isChunkLoadError(event.error ?? event.message) : isStaticAssetLoadEvent(event)) {
+      reloadForChunkError();
+    }
+  };
+  const onRejection = (event: PromiseRejectionEvent) => {
+    if (isChunkLoadError(event.reason)) reloadForChunkError();
+  };
+  // capture=true: resource errors do not bubble.
+  window.addEventListener('error', onError, true);
+  window.addEventListener('unhandledrejection', onRejection);
+  return () => {
+    window.removeEventListener('error', onError, true);
+    window.removeEventListener('unhandledrejection', onRejection);
+    w.__djangocfgChunkReload = false;
+  };
+}

package/src/lib/index.ts

@@ -18,3 +18,4 @@ export * from "./compose-event-handlers";
 export { copyText } from "./clipboard";
 export { createContext } from "./create-context";
 export { getIntensity } from "./intensity";
+export * from "./chunk-reload";

package/src/providers/UiProviders.tsx

@@ -6,6 +6,8 @@ import type { ErrorInfo } from 'react';
 import { TooltipProvider } from '../components/overlay/tooltip';
 import { Toaster } from '../components/feedback/sonner';
 import { Boundary, type BoundaryProps } from '../components/boundary';
+import { syncDisplayModeAttribute } from '../hooks/media/displayMode';
+import { installChunkReloadListeners } from '../lib/chunk-reload';
 import { DialogProvider } from '../lib/dialog-service/DialogProvider';
 
 export interface UiProvidersProps {
@@ -82,6 +84,10 @@ export function UiProviders({
   errorBoundary,
   errorFallback,
 }: UiProvidersProps) {
+  // Stale tab after a deploy: reload once on chunk-load failures outside React.
+  React.useEffect(() => installChunkReloadListeners(), []);
+  // `<html data-display-mode="browser|standalone|...">` for CSS (see styles/css/base.css tokens).
+  React.useEffect(() => syncDisplayModeAttribute(), []);
   // No SSR-skip on purpose: any nested library component that renders
   // `<Tooltip>` on its first paint expects to find `<TooltipProvider>`
   // already in the tree. Skipping the provider during SSR caused

package/src/styles/css/base.css

@@ -6,6 +6,17 @@
 
 /* Radius scale — theme-independent, shared by light and dark */
 :root {
+  /* Safe-area and viewport tokens. env() is 0 unless the host sets viewport-fit=cover, so these are
+   * safe in every mode. UiProviders also sets <html data-display-mode="browser|standalone|...">:
+   * use it for rules that differ in an installed app, e.g.
+   *   :root[data-display-mode='standalone'] .my-header { padding-top: var(--safe-top); }
+   * --app-safe-* are optional overrides (Storybook's safe-area toolbar sets them). --app-height is the dynamic viewport; prefer `inset-0` on fixed full-screen surfaces. */
+  --safe-top: var(--app-safe-top, env(safe-area-inset-top, 0px));
+  --safe-right: var(--app-safe-right, env(safe-area-inset-right, 0px));
+  --safe-bottom: var(--app-safe-bottom, env(safe-area-inset-bottom, 0px));
+  --safe-left: var(--app-safe-left, env(safe-area-inset-left, 0px));
+  --app-height: 100dvh;
+
   --radius: 0.625rem;
   --radius-sm: 0.375rem;
   /* Control corner — shared by interactive controls (nav items, inputs,
@@ -102,6 +113,72 @@ html {
   font-weight: 400;
 }
 
+/* ---------------------------------------------------------------------------
+ * App-like touch behaviour (PWA-ready by default)
+ *
+ * - `touch-action: manipulation` turns off double-tap-to-zoom (and its ~300ms click delay) but keeps
+ *   pinch-zoom, so WCAG 1.4.4 (resize text) still holds. This is the default recipe; viewport
+ *   `user-scalable=no` is NOT used (iOS ignores it, and it blocks accessibility zoom).
+ * - `text-size-adjust: 100%` stops iOS from inflating text after rotation.
+ * - Tap highlight flash is removed on controls.
+ * ------------------------------------------------------------------------- */
+html {
+  touch-action: manipulation;
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+:where(a, button, [role="button"], [role="tab"], [role="menuitem"], summary, label, select, input) {
+  -webkit-tap-highlight-color: transparent;
+}
+
+/* iOS Safari zooms into any focused field whose font-size is below 16px. On touch devices, floor text
+ * fields at 16px; desktop density is untouched. `!important` because component size classes
+ * (`text-sm`, `text-xs`) would otherwise win; add `.input-compact` to opt a field out. */
+@media (pointer: coarse) {
+  :where(
+    input:not([type="checkbox"], [type="radio"], [type="range"], [type="file"], [type="color"], [type="button"], [type="submit"], [type="reset"], [type="image"], .input-compact),
+    textarea:not(.input-compact),
+    select:not(.input-compact)
+  ) {
+    font-size: max(16px, 1em) !important;
+  }
+}
+
+/* Installed app (any display mode the display-mode hook treats as a PWA): behave like a native shell.
+ * `data-display-mode` is set on <html> by UiProviders. */
+:root:is([data-display-mode="standalone"], [data-display-mode="fullscreen"], [data-display-mode="minimal-ui"], [data-display-mode="window-controls-overlay"]),
+:root:is([data-display-mode="standalone"], [data-display-mode="fullscreen"], [data-display-mode="minimal-ui"], [data-display-mode="window-controls-overlay"]) body {
+  /* No rubber-band and no pull-to-refresh at the shell level; inner scrollers keep their own behaviour. */
+  overscroll-behavior: none;
+}
+
+/* Private app shell (PrivateLayout sets `data-private-shell` on <html> while mounted): the shell is exactly one
+ * viewport tall and owns its scrolling, so in an installed app lock the document itself. Public pages never carry the
+ * attribute and stay scrollable. */
+:root[data-private-shell]:is([data-display-mode="standalone"], [data-display-mode="fullscreen"], [data-display-mode="minimal-ui"], [data-display-mode="window-controls-overlay"]),
+:root[data-private-shell]:is([data-display-mode="standalone"], [data-display-mode="fullscreen"], [data-display-mode="minimal-ui"], [data-display-mode="window-controls-overlay"]) body {
+  height: 100%;
+  overflow: hidden;
+}
+
+/* Chrome UI is not selectable and has no long-press callout. Content stays selectable. */
+:root:is([data-display-mode="standalone"], [data-display-mode="fullscreen"], [data-display-mode="minimal-ui"], [data-display-mode="window-controls-overlay"]) :where(button, [role="button"], [role="tab"], [role="menuitem"], nav, header, [data-sidebar], .app-chrome) {
+  -webkit-touch-callout: none;
+  -webkit-user-select: none;
+  user-select: none;
+}
+:root:is([data-display-mode="standalone"], [data-display-mode="fullscreen"], [data-display-mode="minimal-ui"], [data-display-mode="window-controls-overlay"]) :where(button, [role="button"], nav, header, [data-sidebar], .app-chrome) :where(img, svg) {
+  -webkit-user-drag: none;
+}
+
+/* Opt back in: form fields, code, tables and anything marked `.selectable`. */
+:root:is([data-display-mode="standalone"], [data-display-mode="fullscreen"], [data-display-mode="minimal-ui"], [data-display-mode="window-controls-overlay"]) :where(.selectable, input, textarea, [contenteditable], [contenteditable] *, pre, code, table, td, th) {
+  -webkit-touch-callout: default;
+  -webkit-user-select: text;
+  user-select: text;
+}
+
 body {
   background-color: var(--background);
   color: var(--foreground);

package/src/styles/css/utilities/touch-safe.css

@@ -164,3 +164,34 @@
     min-width: 44px;
   }
 }
+
+/* Private layout phone bar actions: compact (e.g. 36px) controls with air above and below inside the 48px row.
+ * The visual box is not inflated by the rule above; the 44px hit area comes from an invisible ::after. */
+@media (max-width: 768px) {
+  [data-sidebar="topbar-actions"] :where(button, [role="button"]) {
+    min-height: 0;
+    min-width: 0;
+    position: relative;
+  }
+  [data-sidebar="topbar-actions"] :where(button, [role="button"])::after {
+    content: "";
+    position: absolute;
+    inset: -4px;
+  }
+}
+
+/* Phone drawer nav rows (PrivateLayout): 40px rows; the 44px hit area is an invisible ::after, like the bar actions. */
+@media (max-width: 768px) {
+  [data-sidebar="content"] :where(button, [role="button"], a) {
+    min-height: 0;
+    min-width: 0;
+  }
+  [data-sidebar="content"] [data-sidebar="menu-button"] {
+    position: relative;
+  }
+  [data-sidebar="content"] [data-sidebar="menu-button"]::after {
+    content: "";
+    position: absolute;
+    inset: -2px 0;
+  }
+}