@classic-homes/theme-svelte 1.25.0 → 1.26.0

package/dist/lib/components/internal/TriggerChild.svelte.d.ts

@@ -0,0 +1,32 @@
+/** What a trigger snippet receives: spread `props` on the focusable element */
+export type TriggerSnippetProps = {
+    props: Record<string, unknown>;
+};
+import type { Snippet } from 'svelte';
+interface Props {
+    /** The props bits-ui hands to its `child` snippet */
+    props: Record<string, unknown>;
+    /** The consumer's trigger snippet */
+    trigger: Snippet<[TriggerSnippetProps]>;
+    /** Class for the fallback wrapper span */
+    fallbackClass?: string;
+    /** Called once when the snippet ignored the props */
+    onfallback?: () => void;
+}
+/**
+ * Renders a consumer's trigger snippet inside a bits-ui `child` snippet.
+ *
+ * The snippet receives the trigger props (`{ props }`) and should spread them
+ * on its own focusable element (`<Button {...props}>`), so that element is the
+ * real trigger: it carries aria-expanded/aria-describedby and gets focus back
+ * when a dialog closes.
+ *
+ * Snippets written before the props were passed ignore them. Those are
+ * detected after mount (no element inside carries the trigger id) and the
+ * props move to a wrapping span, the old behaviour. `onfallback` tells the
+ * parent so it can change the trigger id, which makes bits-ui look the
+ * trigger node up again.
+ */
+declare const TriggerChild: import("svelte").Component<Props, {}, "">;
+type TriggerChild = ReturnType<typeof TriggerChild>;
+export default TriggerChild;

package/dist/lib/components/layout/Sidebar.svelte

@@ -12,7 +12,7 @@
    * - Optional stronger border styling
    * - Quick links section at bottom
    */
-  import type { Snippet } from 'svelte';
+  import { untrack, type Snippet } from 'svelte';
   import type { NavSection, NavItem, QuickLink } from '../../types/layout.js';
   import { cn } from '../../utils.js';
   import { filterNavItems } from '../../utils/nav-access.js';
@@ -388,6 +388,34 @@
   // Focus management for mobile sidebar
   let mobileCloseButton = $state<HTMLButtonElement | null>(null);
 
+  // On the open edge remember what had focus (normally the header menu
+  // button); on the closed edge send focus back there. Every close path (the
+  // close button, the scrim, a nav click, a swipe, Escape) makes the drawer
+  // `inert` while it may hold focus, which would drop focus to <body>. Runs
+  // before the DOM update, so focus moves before `inert` is applied.
+  let drawerReturnFocus: HTMLElement | null = null;
+  let wasDrawerOpen = false;
+  $effect.pre(() => {
+    const drawerOpen = isMobile && mobileOpen;
+    untrack(() => {
+      const active = document.activeElement as HTMLElement | null;
+      if (drawerOpen && !wasDrawerOpen) {
+        drawerReturnFocus =
+          active && active !== document.body && !asideElement?.contains(active) ? active : null;
+      } else if (!drawerOpen && wasDrawerOpen) {
+        // Leave focus alone if the host already moved it somewhere else
+        if (!active || active === document.body || asideElement?.contains(active)) {
+          const target = drawerReturnFocus?.isConnected
+            ? drawerReturnFocus
+            : document.querySelector<HTMLElement>('[data-sidebar-trigger]');
+          target?.focus();
+        }
+        drawerReturnFocus = null;
+      }
+      wasDrawerOpen = drawerOpen;
+    });
+  });
+
   $effect(() => {
     if (isMobile && mobileOpen && mobileCloseButton) {
       // Focus the close button when mobile sidebar opens
@@ -445,14 +473,14 @@
   let asideElement = $state<HTMLElement | null>(null);
 
   // Focus trap for the open mobile drawer: Tab cycles within the drawer,
-  // Escape closes it and returns focus to the header menu button.
+  // Escape closes it (focus then returns to the header menu button).
   function handleDrawerKeydown(event: KeyboardEvent) {
     if (!isMobile || !mobileOpen) return;
 
     if (event.key === 'Escape') {
       event.preventDefault();
+      // Focus returns to the trigger when the host closes the drawer
       onClose?.();
-      document.querySelector<HTMLElement>('[data-sidebar-trigger]')?.focus();
       return;
     }
 
@@ -538,6 +566,8 @@
     return styles.join('; ');
   })()}
   aria-label="Main navigation"
+  role={isMobile && mobileOpen ? 'dialog' : undefined}
+  aria-modal={isMobile && mobileOpen ? 'true' : undefined}
   bind:this={asideElement}
   inert={isMobile && !mobileOpen}
   onkeydown={handleDrawerKeydown}

package/dist/lib/components/layout/Sidebar.svelte.d.ts

@@ -11,7 +11,7 @@
    * - Optional stronger border styling
    * - Quick links section at bottom
    */
-import type { Snippet } from 'svelte';
+import { type Snippet } from 'svelte';
 import type { NavSection, NavItem, QuickLink } from '../../types/layout.js';
 interface Props {
     /** Navigation sections */

package/dist/lib/components/layout/sidebar/SidebarFlyout.svelte

@@ -5,6 +5,7 @@
    * Features entrance animation and keyboard navigation
    */
   import { fly } from 'svelte/transition';
+  import { useReducedMotion } from '../../../composables/useReducedMotion.svelte.js';
   import type { NavItem } from '../../../types/layout.js';
   import { cn } from '../../../utils.js';
 
@@ -35,6 +36,10 @@
     onMouseLeave,
   }: Props = $props();
 
+  // Svelte transitions run as Web Animations, which the CSS reduced-motion
+  // override does not reach, so gate the duration here
+  const reducedMotion = useReducedMotion();
+
   let flyoutElement = $state<HTMLElement | null>(null);
 
   // Get all focusable elements within the flyout
@@ -171,7 +176,7 @@
   onmouseenter={onMouseEnter}
   onmouseleave={onMouseLeave}
   onkeydown={handleKeydown}
-  transition:fly={{ x: -10, duration: 150 }}
+  transition:fly={{ x: reducedMotion.value ? 0 : -10, duration: reducedMotion.value ? 0 : 150 }}
 >
   <div class="p-2">
     <!-- Item name as header - always clickable unless disabled -->

package/dist/lib/components/layout/sidebar/SidebarNavItem.svelte

@@ -9,6 +9,7 @@
    * - Disabled and loading states
    */
   import { slide } from 'svelte/transition';
+  import { useReducedMotion } from '../../../composables/useReducedMotion.svelte.js';
   import type { Snippet } from 'svelte';
   import type { NavItem } from '../../../types/layout.js';
   import { cn } from '../../../utils.js';
@@ -67,6 +68,10 @@
     nested = false,
   }: Props = $props();
 
+  // Svelte transitions run as Web Animations, which the CSS reduced-motion
+  // override does not reach, so gate the duration here
+  const reducedMotion = useReducedMotion();
+
   // Highlight matching text in item names
   function highlightText(
     text: string,
@@ -387,7 +392,7 @@
           !nested && 'ml-3 rounded-md p-1',
           !nested && (isLight ? 'bg-muted/50' : 'bg-sidebar-accent/30')
         )}
-        transition:slide={{ duration: sidebarStore.animate ? 200 : 0 }}
+        transition:slide={{ duration: sidebarStore.animate && !reducedMotion.value ? 200 : 0 }}
       >
         <ul class={cn('space-y-1', nested && 'ml-3 border-l border-outline/40 pl-1')}>
           {#each item.children ?? [] as child (child.id)}

package/dist/lib/components/layout/sidebar/SidebarSection.svelte

@@ -5,6 +5,7 @@
    * Features animated collapse/expand transitions
    */
   import { slide } from 'svelte/transition';
+  import { useReducedMotion } from '../../../composables/useReducedMotion.svelte.js';
   import type { Snippet } from 'svelte';
   import type { NavSection, NavItem } from '../../../types/layout.js';
   import { cn } from '../../../utils.js';
@@ -59,6 +60,10 @@
     siblingSectionIds = [],
   }: Props = $props();
 
+  // Svelte transitions run as Web Animations, which the CSS reduced-motion
+  // override does not reach, so gate the duration here
+  const reducedMotion = useReducedMotion();
+
   // Items here that can expand: the siblings an expanding item closes under autoCollapse
   const expandableItemIds = $derived(
     autoCollapse ? section.items.filter((i) => i.children?.length).map((i) => i.id) : []
@@ -153,7 +158,7 @@
         'mx-2 overflow-hidden rounded-md p-1',
         isLight ? 'bg-muted/50' : 'bg-sidebar-accent/30'
       )}
-      transition:slide={{ duration: sidebarStore.animate ? 200 : 0 }}
+      transition:slide={{ duration: sidebarStore.animate && !reducedMotion.value ? 200 : 0 }}
     >
       <ul class="space-y-1" id={`sidebar-section-${section.id}`}>
         {#each section.items as item}

package/dist/lib/components/media/Audio.svelte

@@ -89,11 +89,27 @@
     );
   }
 
+  /**
+   * Space on a control inside the player (Mute, Speed, CC...) must activate
+   * that control, not toggle playback.
+   */
+  function isInnerControl(event: KeyboardEvent): boolean {
+    const target = event.target;
+    if (!(target instanceof Element) || target === event.currentTarget) return false;
+    return !!target.closest(
+      'button, a[href], summary, [role="button"], [role="checkbox"], [role="radio"], [role="switch"], [role="menuitem"], [role="tab"]'
+    );
+  }
+
   function handleKeyDown(event: KeyboardEvent) {
     if (isTextEntry(event.target) || event.metaKey || event.ctrlKey || event.altKey) return;
 
     switch (event.key) {
       case ' ':
+        if (isInnerControl(event)) return;
+        event.preventDefault();
+        player.toggle();
+        break;
       case 'k':
       case 'K':
         event.preventDefault();

package/dist/lib/components/media/Lightbox.svelte

@@ -84,6 +84,10 @@
   let swipeStartX = 0;
   let swipeStartY = 0;
   let swipeActive = false;
+  /** The one pointer a swipe follows; a second finger means a pinch. */
+  let swipePointerId: number | null = null;
+  let swipeStartScale = 1;
+  const downPointers = new Set<number>();
 
   const reducedMotion = useReducedMotion();
   const zoom = useMediaZoom();
@@ -218,16 +222,37 @@
     }
   }
 
+  function cancelSwipe() {
+    swipeActive = false;
+    swipePointerId = null;
+  }
+
   function handleSwipeStart(event: PointerEvent) {
+    downPointers.add(event.pointerId);
+    // A second pointer turns the gesture into a pinch, never a swipe
+    if (downPointers.size > 1) {
+      cancelSwipe();
+      return;
+    }
     if (panning || !hasMultiple) return;
     swipeActive = true;
+    swipePointerId = event.pointerId;
     swipeStartX = event.clientX;
     swipeStartY = event.clientY;
+    swipeStartScale = zoom.scale;
+  }
+
+  function handlePointerGone(event: PointerEvent) {
+    downPointers.delete(event.pointerId);
+    if (event.pointerId === swipePointerId) cancelSwipe();
   }
 
   function handleSwipeEnd(event: PointerEvent) {
-    if (!swipeActive) return;
-    swipeActive = false;
+    downPointers.delete(event.pointerId);
+    if (!swipeActive || event.pointerId !== swipePointerId) return;
+    cancelSwipe();
+    // The gesture zoomed (pinch or double-tap): it was not a swipe
+    if (zoom.scale !== swipeStartScale) return;
 
     const dx = event.clientX - swipeStartX;
     const dy = event.clientY - swipeStartY;
@@ -342,7 +367,8 @@
                   use:zoom.action
                   onpointerdown={handleSwipeStart}
                   onpointerup={handleSwipeEnd}
-                  onpointercancel={() => (swipeActive = false)}
+                  onpointercancel={handlePointerGone}
+                  onpointerleave={handlePointerGone}
                 >
                   <img
                     src={activeItem.src}

package/dist/lib/components/media/MediaCarousel.svelte

@@ -18,6 +18,7 @@
    * <MediaCarousel items={photos} label="Project gallery" showThumbnails />
    * ```
    */
+  import { untrack } from 'svelte';
   import { useReducedMotion } from '../../composables/useReducedMotion.svelte.js';
   import type { MediaAspectRatio, MediaItem } from '../../types/components.js';
   import { cn } from '../../utils.js';
@@ -78,6 +79,8 @@
   let interacting = $state(false);
   let scrollSyncTimer: ReturnType<typeof setTimeout> | undefined;
   let autoplayTimer: ReturnType<typeof setInterval> | undefined;
+  /** The index the track was last scrolled to (or scrolled itself to); -1 before mount. */
+  let syncedIndex = -1;
 
   const reducedMotion = useReducedMotion();
 
@@ -98,10 +101,25 @@
     if (target === index) return;
 
     index = target;
+    syncedIndex = target;
     onIndexChange?.(target);
     scrollToSlide(target, smooth);
   }
 
+  // An initial or parent-set `index` must move the track too, or the visible
+  // slide is not the active one (it stays inert and hidden from AT). Only
+  // `index` and the track are tracked; the scroll itself runs untracked.
+  $effect(() => {
+    const target = index;
+    if (!trackElement) return;
+    untrack(() => {
+      if (target === syncedIndex) return;
+      // Jump on mount; animate later changes
+      scrollToSlide(target, syncedIndex !== -1);
+      syncedIndex = target;
+    });
+  });
+
   function scrollToSlide(target: number, smooth: boolean) {
     if (!trackElement) return;
     const slide = trackElement.children[target] as HTMLElement | undefined;
@@ -138,6 +156,7 @@
       }
 
       if (closest !== index) {
+        syncedIndex = closest;
         index = closest;
         onIndexChange?.(closest);
       }

package/dist/lib/components/media/MediaEmbed.svelte

@@ -44,6 +44,7 @@
     MediaAspectRatio,
     MediaEmbedProvider,
   } from '../../types/components.js';
+  import { tick, untrack } from 'svelte';
   import { cn } from '../../utils.js';
   import {
     buildEmbedSrc,
@@ -169,6 +170,33 @@
   /** Matterport's own name for the space, used when no `title` was supplied. */
   const facadeTitle = $derived(title || fetchedName || '');
 
+  // A new video gets its own facade: carrying `activated` over would load and
+  // autoplay it without a click, and the fetched poster belongs to the old one.
+  let source: string | null = null;
+  $effect(() => {
+    const next = `${resolvedProvider}:${resolvedVideoId}`;
+    untrack(() => {
+      if (source !== null && source !== next) {
+        activated = false;
+        fetchedPoster = null;
+        fetchedName = null;
+      }
+      source = next;
+    });
+  });
+
+  let iframeElement = $state<HTMLIFrameElement | null>(null);
+
+  // Activating the facade from the keyboard removes the focused button; move
+  // focus to the player that replaced it rather than dropping it on <body>.
+  async function activate(event: MouseEvent) {
+    const hadFocus = document.activeElement === event.currentTarget;
+    activated = true;
+    if (!hadFocus) return;
+    await tick();
+    iframeElement?.focus();
+  }
+
   // Only reaches the network when the caller opted in, and never when a poster
   // was supplied — there would be nothing to gain.
   $effect(() => {
@@ -193,6 +221,8 @@
         // satisfies the browser's user-gesture requirement.
         autoplay: activated,
         start: resolvedStart,
+        // Unlisted Vimeo hash from `url`, unless `videoId` names another video
+        hash: parsed?.videoId === resolvedVideoId ? parsed?.hash : undefined,
         showRelated,
         primaryColor,
         letterboxColor,
@@ -250,6 +280,7 @@
     </div>
   {:else if showIframe}
     <iframe
+      bind:this={iframeElement}
       src={iframeSrc}
       {title}
       class="h-full w-full border-0"
@@ -264,7 +295,7 @@
     <button
       type="button"
       class="group/facade relative h-full w-full overflow-hidden bg-black outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
-      onclick={() => (activated = true)}
+      onclick={activate}
       aria-label={isMatterport
         ? `Open ${facadeTitle} as a 3D tour on ${providerLabel}`
         : `Play ${facadeTitle} on ${providerLabel}`}

package/dist/lib/components/media/Video.svelte

@@ -225,6 +225,18 @@
     );
   }
 
+  /**
+   * Space on a control inside the player (Mute, Speed, CC...) must activate
+   * that control, not toggle playback.
+   */
+  function isInnerControl(event: KeyboardEvent): boolean {
+    const target = event.target;
+    if (!(target instanceof Element) || target === event.currentTarget) return false;
+    return !!target.closest(
+      'button, a[href], summary, [role="button"], [role="checkbox"], [role="radio"], [role="switch"], [role="menuitem"], [role="tab"]'
+    );
+  }
+
   function handleKeyDown(event: KeyboardEvent) {
     if (isTextEntry(event.target) || event.metaKey || event.ctrlKey || event.altKey) return;
 
@@ -232,6 +244,10 @@
 
     switch (event.key) {
       case ' ':
+        if (isInnerControl(event)) return;
+        event.preventDefault();
+        togglePlayback();
+        break;
       case 'k':
       case 'K':
         event.preventDefault();

package/dist/lib/components/media/internal/MediaControls.svelte

@@ -81,6 +81,14 @@
 
   const hasCaptions = $derived(player.textTracks.length > 0);
   const captionsOn = $derived(player.activeTextTrack !== null);
+  // Firefox (and video elements that opt out) have no picture-in-picture API;
+  // a button there would do nothing. `element` is null during SSR.
+  const pipSupported = $derived(
+    !!player.element &&
+      player.element instanceof HTMLVideoElement &&
+      document.pictureInPictureEnabled === true &&
+      !player.element.disablePictureInPicture
+  );
   const volumeValue = $derived(player.muted ? 0 : Math.round(player.volume * 100));
 
   const volumeIcon = $derived(
@@ -258,7 +266,7 @@
       </button>
     {/if}
 
-    {#if showPictureInPicture}
+    {#if showPictureInPicture && pipSupported}
       <button
         type="button"
         class={buttonClass}

package/dist/lib/components/notifications/NotificationBadge.svelte

@@ -54,7 +54,7 @@
   {#if showBadge}
     <span
       class={cn(
-        'absolute -top-1 -right-1 flex items-center justify-center rounded-full bg-destructive text-white font-medium px-1',
+        'absolute -top-1 -right-1 flex items-center justify-center rounded-full bg-destructive text-destructive-foreground font-medium px-1',
         sizeClasses[size]
       )}
       aria-label={`${count} unread notifications`}

package/dist/lib/components/notifications/NotificationItem.svelte

@@ -60,19 +60,11 @@
   function handleCheckboxChange(checked: boolean) {
     onToggleSelect?.(notification.id, checked);
   }
-
-  function handleKeyDown(e: KeyboardEvent) {
-    // Only keys pressed on the row itself; Enter on the nested action link
-    // must follow the link, not activate the row.
-    if (e.target !== e.currentTarget) return;
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      onClick?.(notification);
-    }
-  }
 </script>
 
-<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<!-- When clickable, the title is the button and its ::after stretches over
+     the whole card, so the card has one tab stop and no interactive element
+     is nested inside another. The checkbox and action link sit above it. -->
 <div
   class={cn(
     'group relative flex gap-3 rounded-lg border p-4',
@@ -82,18 +74,9 @@
     isSelected && 'ring-2 ring-primary ring-offset-2',
     className
   )}
-  role={onClick ? 'button' : undefined}
-  tabindex={onClick ? 0 : undefined}
-  onclick={onClick ? handleClick : undefined}
-  onkeydown={onClick ? handleKeyDown : undefined}
 >
   {#if selectable}
-    <div
-      class="flex items-start pt-0.5"
-      role="presentation"
-      onclick={(e) => e.stopPropagation()}
-      onkeydown={(e) => e.stopPropagation()}
-    >
+    <div class="relative z-10 flex items-start pt-0.5">
       <Checkbox
         checked={isSelected}
         onCheckedChange={handleCheckboxChange}
@@ -118,7 +101,19 @@
       <div class="min-w-0 flex-1">
         <div class="flex items-center gap-2 flex-wrap">
           <h4 class={cn('text-sm font-medium truncate', !notification.read && 'font-semibold')}>
-            {notification.title}
+            {#if onClick}
+              <button
+                type="button"
+                class="block max-w-full truncate text-left font-[inherit] focus-visible:outline-none after:absolute after:inset-0 after:rounded-lg after:content-[''] focus-visible:after:ring-2 focus-visible:after:ring-ring"
+                onclick={handleClick}
+              >
+                {notification.title}
+                {#if !notification.read}<span class="sr-only">(unread)</span>{/if}
+              </button>
+            {:else}
+              {notification.title}
+              {#if !notification.read}<span class="sr-only">(unread)</span>{/if}
+            {/if}
           </h4>
           <Badge variant={typeBadgeVariant} size="sm">
             {#snippet children()}
@@ -142,18 +137,14 @@
           {relativeTime}
         </span>
         {#if !notification.read}
-          <span class="h-2 w-2 rounded-full bg-info" aria-label="Unread"></span>
+          <span class="h-2 w-2 rounded-full bg-info" aria-hidden="true"></span>
         {/if}
       </div>
     </div>
 
     {#if actionHref && notification.actionLabel}
       <div class="mt-2">
-        <a
-          href={actionHref}
-          class="text-sm font-medium text-primary hover:underline"
-          onclick={(e) => e.stopPropagation()}
-        >
+        <a href={actionHref} class="relative z-10 text-sm font-medium text-primary hover:underline">
           {notification.actionLabel}
         </a>
       </div>

package/dist/lib/composables/useEscapeKey.svelte.d.ts

@@ -27,6 +27,10 @@ export interface UseEscapeKeyOptions {
  * Registers a global keydown listener for the Escape key.
  * Useful for closing modals, dialogs, dropdowns, etc.
  *
+ * Escape that something else already handled is ignored: an event whose
+ * default was prevented, or one pressed while a bits-ui layer (an open
+ * Select, Popover, menu or dialog) is open, which closes that layer instead.
+ *
  * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
  *
  * @example

package/dist/lib/composables/useEscapeKey.svelte.js

@@ -1,9 +1,22 @@
+/**
+ * Whether a bits-ui escape layer (an open Select, Popover, Dialog, menu...)
+ * is active. bits-ui registers those in a global map; the topmost one owns
+ * Escape, so a page-level handler must leave the key to it.
+ */
+function hasOpenEscapeLayer() {
+    const layers = globalThis.bitsEscapeLayers;
+    return !!layers && layers.size > 0;
+}
 /**
  * useEscapeKey - Composable for handling Escape key press
  *
  * Registers a global keydown listener for the Escape key.
  * Useful for closing modals, dialogs, dropdowns, etc.
  *
+ * Escape that something else already handled is ignored: an event whose
+ * default was prevented, or one pressed while a bits-ui layer (an open
+ * Select, Popover, menu or dialog) is open, which closes that layer instead.
+ *
  * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
  *
  * @example
@@ -34,6 +47,8 @@ export function useEscapeKey(callback, options) {
             return;
         function handleKeyDown(event) {
             if (event.key === 'Escape') {
+                if (event.defaultPrevented || hasOpenEscapeLayer())
+                    return;
                 if (preventDefault) {
                     event.preventDefault();
                 }

package/dist/lib/composables/useHlsSource.svelte.js

@@ -24,6 +24,18 @@
  * ```
  */
 import { canPlayHlsNatively, loadHls, } from '../utils/hls.js';
+/** Recovery attempts per error type before a fatal error is treated as terminal. */
+const MAX_RECOVERY_ATTEMPTS = 3;
+/**
+ * Fatal network errors that retrying cannot fix: the playlist itself is
+ * missing (404), unreachable, or not a playlist.
+ */
+const TERMINAL_DETAILS = new Set([
+    'manifestLoadError',
+    'manifestLoadTimeOut',
+    'manifestParsingError',
+    'manifestIncompatibleCodecsError',
+]);
 export function useHlsSource(getElement, options) {
     let status = $state('idle');
     let error = $state(null);
@@ -67,16 +79,31 @@ export function useHlsSource(getElement, options) {
                 return;
             }
             instance = new Hls(config);
+            let networkRetries = 0;
+            let mediaRecoveries = 0;
+            // A fragment that loads means playback recovered; a long stream gets a
+            // fresh allowance for its next unrelated hiccup.
+            if (Hls.Events.FRAG_LOADED) {
+                instance.on(Hls.Events.FRAG_LOADED, () => {
+                    networkRetries = 0;
+                    mediaRecoveries = 0;
+                });
+            }
             instance.on(Hls.Events.ERROR, (_event, data) => {
                 if (!data?.fatal)
                     return;
-                // hls.js can recover from network and media errors; only a fatal
-                // error of another type is truly terminal.
-                if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
+                // hls.js can recover from network and media errors, but only so
+                // often: an unbounded retry of a 404 would never report 'error'.
+                const terminal = data.details !== undefined && TERMINAL_DETAILS.has(data.details);
+                if (data.type === Hls.ErrorTypes.NETWORK_ERROR &&
+                    !terminal &&
+                    networkRetries < MAX_RECOVERY_ATTEMPTS) {
+                    networkRetries += 1;
                     instance?.startLoad();
                     return;
                 }
-                if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
+                if (data.type === Hls.ErrorTypes.MEDIA_ERROR && mediaRecoveries < MAX_RECOVERY_ATTEMPTS) {
+                    mediaRecoveries += 1;
                     instance?.recoverMediaError();
                     return;
                 }