@djangocfg/ui-core 2.1.540 → 2.1.542

package/src/components/navigation/command/index.tsx

@@ -28,7 +28,7 @@ const CommandDialog = ({ children, ...props }: DialogProps) => {
   return (
     <Dialog {...props}>
       <DialogContent className="overflow-hidden p-0">
-        <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
+        <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[data-cmdk-input-wrapper]_svg]:h-5 [&_[data-cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
           {children}
         </Command>
       </DialogContent>
@@ -36,11 +36,15 @@ const CommandDialog = ({ children, ...props }: DialogProps) => {
   )
 }
 
+// The wrapper is marked with `data-cmdk-input-wrapper` rather than the bare
+// `cmdk-input-wrapper`: this div is ours, not cmdk's, and React only forwards
+// unknown attributes to the DOM under a `data-` prefix. CommandDialog's
+// `[&_[data-cmdk-input-wrapper]_svg]` sizing selector matches this same name.
 const CommandInput = React.forwardRef<
   React.ElementRef<typeof CommandPrimitive.Input>,
   React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
 >(({ className, ...props }, ref) => (
-  <div className="flex items-center border-b px-3" cmdk-input-wrapper="">
+  <div className="flex items-center border-b px-3" data-cmdk-input-wrapper="">
     <MagnifyingGlassIcon className="mr-2 h-4 w-4 shrink-0 opacity-50" />
     <CommandPrimitive.Input
       ref={ref}
@@ -59,9 +63,23 @@ const CommandList = React.forwardRef<
   React.ElementRef<typeof CommandPrimitive.List>,
   React.ComponentPropsWithoutRef<typeof CommandPrimitive.List>
 >(({ className, style, ...props }, ref) => {
-  const listRef = React.useRef<HTMLDivElement>(null)
-
-  React.useImperativeHandle(ref, () => listRef.current as HTMLDivElement)
+  const listRef = React.useRef<React.ElementRef<typeof CommandPrimitive.List> | null>(null)
+
+  // The element is needed locally (for the cssText fix below) AND by the
+  // caller, so it is captured and forwarded in one callback. useImperativeHandle
+  // cannot be used here: it must produce a non-null handle, and the element is
+  // genuinely null until the primitive mounts.
+  const setRef = React.useCallback(
+    (node: React.ElementRef<typeof CommandPrimitive.List> | null) => {
+      listRef.current = node
+      if (typeof ref === 'function') {
+        ref(node)
+      } else if (ref) {
+        ref.current = node
+      }
+    },
+    [ref]
+  )
 
   React.useEffect(() => {
     if (listRef.current) {
@@ -71,7 +89,7 @@ const CommandList = React.forwardRef<
 
   return (
     <CommandPrimitive.List
-      ref={listRef as any}
+      ref={setRef}
       className={cn("max-h-[300px] overflow-y-auto overflow-x-hidden", className)}
       style={{
         maxHeight: '300px',

package/src/components/navigation/link/LinkContext.tsx

@@ -46,7 +46,9 @@ export type LinkComponent = ComponentType<LinkComponentProps>;
  * makes the two instances agree whatever the bundler decides.
  */
 const CONTEXT_KEY = Symbol.for('@djangocfg/ui-core.LinkComponentContext');
-const globalScope = globalThis as unknown as Record<symbol, unknown>;
+// `typeof globalThis` carries no index signature, but the object genuinely
+// accepts symbol keys — this asserts a property the runtime has.
+const globalScope = globalThis as Record<symbol, unknown>;
 
 export const LinkComponentContext =
   (globalScope[CONTEXT_KEY] as ReturnType<typeof createContext<LinkComponent | null>> | undefined) ??

package/src/components/navigation/pagination/pagination-static.tsx

@@ -18,7 +18,7 @@ import {
     Pagination, PaginationContent, PaginationEllipsis, PaginationItem
 } from './pagination';
 
-export interface DRFPaginatedResponse<T = any> {
+export interface DRFPaginatedResponse<T = unknown> {
   count: number;
   page: number;
   pages: number;

package/src/components/navigation/tabs/index.tsx

@@ -50,6 +50,17 @@ export interface TabsProps extends React.ComponentPropsWithoutRef<typeof TabsPri
   storageType?: StorageType
 }
 
+/**
+ * The part of a trigger's props the mobile sheet re-writes when it clones one.
+ *
+ * Not the trigger's full prop type: everything else passes through untouched,
+ * and naming more than is read would be a claim this file cannot check.
+ */
+type TriggerProps = {
+  onClick?: (event: React.MouseEvent) => void
+  className?: string
+}
+
 const Tabs = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Root>,
   TabsProps
@@ -67,12 +78,13 @@ const Tabs = React.forwardRef<
   );
 
   // Wrap onValueChange to persist tab changes
+  const { onValueChange } = props;
   const handleValueChange = React.useCallback(
     (newValue: string) => {
       if (storageKey) setStoredTab(newValue);
-      props.onValueChange?.(newValue);
+      onValueChange?.(newValue);
     },
-    [storageKey, setStoredTab, props.onValueChange],
+    [storageKey, setStoredTab, onValueChange],
   );
 
   // Build enhanced props: inject stored defaultValue when no value/defaultValue given
@@ -123,9 +135,14 @@ const Tabs = React.forwardRef<
     (child) => React.isValidElement(child) && child.type === TabsContent
   )
 
-  // Extract triggers from TabsList children
-  const triggers = React.isValidElement(tabsList)
-    ? React.Children.toArray((tabsList.props as any).children)
+  // Extract triggers from TabsList children.
+  //
+  // `isValidElement` narrows to `ReactElement<unknown>` unless it is told the
+  // prop shape, which is why reading `.props.children` used to need a cast.
+  // Naming the shape is the same assertion, made once and checked: this branch
+  // only runs for an element whose `type === TabsList`.
+  const triggers = React.isValidElement<{ children?: React.ReactNode }>(tabsList)
+    ? React.Children.toArray(tabsList.props.children)
     : []
 
   // Mobile Sheet Navigation
@@ -155,11 +172,15 @@ const Tabs = React.forwardRef<
               <nav className="flex flex-col gap-2 mt-6">
                 <TabsPrimitive.List className="flex flex-col gap-2">
                   {triggers.map((trigger, index) => {
-                    if (!React.isValidElement(trigger)) return null
+                    // Typed here rather than cast at each use: the two props
+                    // this clone actually touches are the two it declares, so
+                    // `cloneElement` checks the override instead of taking it
+                    // on faith.
+                    if (!React.isValidElement<TriggerProps>(trigger)) return null
 
                     // Clone trigger and wrap in mobile-friendly container
-                    const triggerProps = (trigger as any).props || {};
-                    return React.cloneElement(trigger as React.ReactElement, {
+                    const triggerProps = trigger.props
+                    return React.cloneElement(trigger, {
                       key: index,
                       onClick: (e: React.MouseEvent) => {
                         setOpen(false)
@@ -171,7 +192,7 @@ const Tabs = React.forwardRef<
                         "hover:bg-muted",
                         triggerProps.className
                       ),
-                    } as any)
+                    })
                   })}
                 </TabsPrimitive.List>
               </nav>

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

@@ -168,7 +168,7 @@ ResponsiveSheetContent.displayName = "ResponsiveSheetContent"
 // Header
 // ─────────────────────────────────────────────────────────────────────────────
 
-interface ResponsiveSheetHeaderProps extends React.HTMLAttributes<HTMLDivElement> {}
+type ResponsiveSheetHeaderProps = React.HTMLAttributes<HTMLDivElement>;
 
 function ResponsiveSheetHeader({ className, ...props }: ResponsiveSheetHeaderProps) {
   const { isMobile } = React.useContext(ResponsiveSheetContext);
@@ -185,7 +185,7 @@ ResponsiveSheetHeader.displayName = "ResponsiveSheetHeader"
 // Title
 // ─────────────────────────────────────────────────────────────────────────────
 
-interface ResponsiveSheetTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {}
+type ResponsiveSheetTitleProps = React.HTMLAttributes<HTMLHeadingElement>;
 
 function ResponsiveSheetTitle({ className, ...props }: ResponsiveSheetTitleProps) {
   const { isMobile } = React.useContext(ResponsiveSheetContext);
@@ -202,7 +202,7 @@ ResponsiveSheetTitle.displayName = "ResponsiveSheetTitle"
 // Description
 // ─────────────────────────────────────────────────────────────────────────────
 
-interface ResponsiveSheetDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {}
+type ResponsiveSheetDescriptionProps = React.HTMLAttributes<HTMLParagraphElement>;
 
 function ResponsiveSheetDescription({ className, ...props }: ResponsiveSheetDescriptionProps) {
   const { isMobile } = React.useContext(ResponsiveSheetContext);
@@ -219,7 +219,7 @@ ResponsiveSheetDescription.displayName = "ResponsiveSheetDescription"
 // Footer
 // ─────────────────────────────────────────────────────────────────────────────
 
-interface ResponsiveSheetFooterProps extends React.HTMLAttributes<HTMLDivElement> {}
+type ResponsiveSheetFooterProps = React.HTMLAttributes<HTMLDivElement>;
 
 function ResponsiveSheetFooter({ className, ...props }: ResponsiveSheetFooterProps) {
   const { isMobile } = React.useContext(ResponsiveSheetContext);

package/src/components/select/helpers.tsx

@@ -10,7 +10,7 @@ import type { MultiSelectProAsyncOption } from './multi-select-pro-async'
 /**
  * Generic option builder config
  */
-export interface OptionBuilderConfig<T = any> {
+export interface OptionBuilderConfig<T = unknown> {
   /** Extract unique ID/value from item */
   getValue: (item: T) => string
   /** Extract main label text */

package/src/components/select/multi-select-pro-async.tsx

@@ -248,12 +248,19 @@ export const MultiSelectProAsync = React.forwardRef<MultiSelectProAsyncRef, Mult
       [animation, animationConfig]
     )
 
-    // Reset on defaultValue change
+    // Reset on defaultValue change.
+    // Keyed on the serialized contents, not the array identity: callers commonly
+    // pass an inline literal, which would otherwise reset the user's selection on
+    // every render. `defaultValue` itself is read through a ref for the same reason.
+    const defaultValueKey = JSON.stringify(defaultValue)
+    const defaultValueRef = React.useRef(defaultValue)
+    defaultValueRef.current = defaultValue
+
     React.useEffect(() => {
       if (resetOnDefaultValueChange) {
-        setSelectedValues(defaultValue)
+        setSelectedValues(defaultValueRef.current)
       }
-    }, [JSON.stringify(defaultValue), resetOnDefaultValueChange])
+    }, [defaultValueKey, resetOnDefaultValueChange])
 
     // Announce changes for screen readers
     const announce = React.useCallback((message: string) => {
@@ -347,7 +354,7 @@ export const MultiSelectProAsync = React.forwardRef<MultiSelectProAsyncRef, Mult
     )
 
     // Render badge with custom styles
-    const renderBadge = (option: MultiSelectProAsyncOption, index: number) => {
+    const renderBadge = React.useCallback((option: MultiSelectProAsyncOption, index: number) => {
       const { style, icon: Icon } = option
       const badgeStyle: React.CSSProperties = {}
 
@@ -393,7 +400,7 @@ export const MultiSelectProAsync = React.forwardRef<MultiSelectProAsyncRef, Mult
           )}
         </Badge>
       )
-    }
+    }, [animConfig, variant, disabled, toggleOption, translations])
 
     // Display value
     const displayValue = React.useMemo(() => {
@@ -414,7 +421,7 @@ export const MultiSelectProAsync = React.forwardRef<MultiSelectProAsyncRef, Mult
           )}
         </div>
       )
-    }, [selectedOptions, maxCount, translations, singleLine, variant, disabled, animConfig])
+    }, [selectedOptions, maxCount, translations, singleLine, renderBadge])
 
     // Render options
     const renderOptions = () => {

package/src/components/select/multi-select-pro.tsx

@@ -214,7 +214,6 @@ export const MultiSelectPro = React.forwardRef<MultiSelectProRef, MultiSelectPro
     }, [flatOptions, selectedValues])
 
     // Responsive configuration (reserved for future use)
-    // @ts-ignore reserved for future use
     const _responsiveConfig = React.useMemo((): ResponsiveConfig => {
       if (typeof responsive === 'boolean') {
         return responsive
@@ -364,7 +363,7 @@ export const MultiSelectPro = React.forwardRef<MultiSelectProRef, MultiSelectPro
     )
 
     // Render badge with custom styles
-    const renderBadge = (option: MultiSelectProOption, index: number) => {
+    const renderBadge = React.useCallback((option: MultiSelectProOption, index: number) => {
       const { style, icon: Icon } = option
       const badgeStyle: React.CSSProperties = {}
 
@@ -410,7 +409,7 @@ export const MultiSelectPro = React.forwardRef<MultiSelectProRef, MultiSelectPro
           )}
         </Badge>
       )
-    }
+    }, [animConfig, variant, disabled, toggleOption, translations])
 
     // Display value
     const displayValue = React.useMemo(() => {
@@ -431,7 +430,7 @@ export const MultiSelectPro = React.forwardRef<MultiSelectProRef, MultiSelectPro
           )}
         </div>
       )
-    }, [selectedOptions, maxCount, translations, singleLine, variant, disabled, animConfig])
+    }, [selectedOptions, maxCount, translations, singleLine, renderBadge])
 
     // Render options
     const renderOptions = () => {

package/src/components/specialized/flag/Flag.tsx

@@ -7,11 +7,20 @@ import { cn } from '../../../lib/utils';
 import { FLAG_COMPONENTS } from './flag-map';
 import { getLanguageCountryCode } from './language-to-country';
 
-export interface FlagProps extends Omit<React.SVGAttributes<SVGSVGElement>, 'children'> {
+/**
+ * Presentational attributes only. The underlying `country-flag-icons`
+ * components type their handlers against an element that cannot exist, so no
+ * event handler passed here could be given an honest signature.
+ */
+export interface FlagProps {
   /** ISO 3166-1 alpha-2 country code (e.g. `'US'`, `'JP'`). Case-insensitive. */
   countryCode: string;
   /** Optional rounded corners — common for tile / chip presentations. */
   rounded?: boolean;
+  className?: string;
+  width?: number | string;
+  height?: number | string;
+  title?: string;
 }
 
 /**
@@ -22,11 +31,8 @@ export function Flag({ countryCode, rounded, className, ...props }: FlagProps) {
   const code = countryCode?.toUpperCase();
   const Component = code ? FLAG_COMPONENTS[code] : undefined;
   if (!Component) return null;
-  // `country-flag-icons` types its components against an HTML+SVG intersection;
-  // we narrow to plain `SVGAttributes` for our consumers.
-  const Tag = Component as unknown as React.ComponentType<React.SVGAttributes<SVGSVGElement>>;
   return (
-    <Tag
+    <Component
       className={cn(
         'inline-block shrink-0 select-none',
         rounded && 'overflow-hidden rounded-[2px]',

package/src/components/specialized/flag/flag-map.ts

@@ -12,11 +12,18 @@ import type * as React from 'react';
 import * as Flags from 'country-flag-icons/react/3x2';
 
 /**
- * `country-flag-icons` types its components against `HTMLSVGElement`
- * (their custom intersection of HTMLElement + SVGElement). We treat them
- * as opaque components — call sites use `<Flag />` rather than touching
- * the DOM type directly.
+ * `country-flag-icons` declares its components against `HTMLSVGElement` — its
+ * own `HTMLElement & SVGElement` intersection, which no DOM node satisfies. Its
+ * event-handler props are consequently uncallable with a real SVG event, so
+ * `FlagProps` exposes only the presentational attributes `Flag` forwards; a
+ * handler would have to be typed against an element that cannot exist.
  */
-export type FlagSvgComponent = (props: React.SVGProps<SVGSVGElement> & React.HTMLAttributes<SVGSVGElement>) => React.JSX.Element;
+export type FlagSvgComponent = (typeof Flags)[keyof typeof Flags];
 
-export const FLAG_COMPONENTS = Flags as unknown as Record<string, FlagSvgComponent>;
+/**
+ * Keyed by country code rather than indexed off the namespace object, because
+ * the lookup code is a runtime string and a module namespace admits only its
+ * literal export names.
+ */
+export const FLAG_COMPONENTS: Record<string, FlagSvgComponent> =
+  Object.fromEntries(Object.entries(Flags));

package/src/components/specialized/image-with-fallback/index.tsx

@@ -24,9 +24,12 @@ export interface ImageWithFallbackProps extends Omit<React.ImgHTMLAttributes<HTM
   placeholder?: string;
   blurDataURL?: string;
   
-  // Callbacks
-  onLoad?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
-  onError?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+  // Callbacks. Fired from two sources with different event shapes: the
+  // preloader (`useImageLoader`) passes a DOM `Event` from a detached
+  // `new Image()`, the rendered <img> passes a React synthetic event. Narrow
+  // before touching anything beyond `type`/`target`.
+  onLoad?: (event: Event | React.SyntheticEvent<HTMLImageElement>) => void;
+  onError?: (event: Event | React.SyntheticEvent<HTMLImageElement>) => void;
   onLoadStart?: () => void;
   
   // Performance
@@ -55,7 +58,9 @@ export const ImageWithFallback = forwardRef<HTMLImageElement, ImageWithFallbackP
   
   // Performance
   priority = false,
-  unoptimized = false,
+  // Accepted for next/image API parity; a plain <img> has nothing to
+  // optimize. Destructured so it never reaches the DOM as an attribute.
+  unoptimized: _unoptimized = false,
   
   // Standard img attributes
   width,

package/src/components/specialized/presence/index.tsx

@@ -34,9 +34,8 @@ Presence.displayName = "Presence";
 
 function usePresence(present: boolean) {
   const [node, setNode] = React.useState<HTMLElement>();
-  const stylesRef = React.useRef<CSSStyleDeclaration>(
-    {} as unknown as CSSStyleDeclaration,
-  );
+  // Undefined until the node mounts; every read below already tolerates that.
+  const stylesRef = React.useRef<CSSStyleDeclaration | undefined>(undefined);
   const prevPresentRef = React.useRef(present);
   const prevAnimationNameRef = React.useRef<string>("none");
   const initialState = present ? "mounted" : "unmounted";

package/src/components/specialized/token-icon/index.tsx

@@ -80,25 +80,36 @@ export async function getTokensByCategory(): Promise<TokenCategory[]> {
 
 export type TokenSymbol = string
 
+/** The only props this file passes to a resolved @web3icons component. */
+type TokenIconComponent = React.ComponentType<{
+  variant?: 'branded' | 'mono'
+  size?: number
+}>
+
 // Dynamic import for @web3icons/react tokens
-const tokenIconCache = new Map<string, React.ComponentType<any>>()
+const tokenIconCache = new Map<string, TokenIconComponent>()
 
-async function getTokenIcon(symbol: string): Promise<React.ComponentType<any> | null> {
+async function getTokenIcon(symbol: string): Promise<TokenIconComponent | null> {
   const normalizedSymbol = symbol.toUpperCase().replace(/[^A-Z0-9]/g, '_')
   const componentName = `Token${normalizedSymbol}`
 
-  if (tokenIconCache.has(componentName)) {
-    return tokenIconCache.get(componentName)!
+  const cached = tokenIconCache.get(componentName)
+  if (cached) {
+    return cached
   }
 
   try {
-    const module = await import('@web3icons/react')
-    const Component = (module as any)[componentName]
-    if (Component) {
-      tokenIconCache.set(componentName, Component)
-      return Component
+    // The export name is computed at runtime, so the module is read as an
+    // untyped key map and the value is proven to be a component (a function)
+    // before it is used.
+    const namespace: Record<string, unknown> = await import('@web3icons/react')
+    const Component = namespace[componentName]
+    if (typeof Component === 'function') {
+      const IconComponent = Component as TokenIconComponent
+      tokenIconCache.set(componentName, IconComponent)
+      return IconComponent
     }
-  } catch (e) {
+  } catch (_e) {
     // Token not found
   }
 
@@ -110,11 +121,13 @@ export function TokenIcon({
   variant = 'branded',
   size = 24,
   className,
-  network,
-  address,
+  // Destructured, not used: these narrow which icon is resolved upstream
+  // and must not fall through `...props` onto the DOM element below.
+  network: _network,
+  address: _address,
   ...props
 }: TokenIconProps) {
-  const [IconComponent, setIconComponent] = React.useState<React.ComponentType<any> | null>(null)
+  const [IconComponent, setIconComponent] = React.useState<TokenIconComponent | null>(null)
   const [_loading, setLoading] = React.useState(true)
 
   React.useEffect(() => {

package/src/hooks/audio/useAudioPrefs.ts

@@ -32,6 +32,11 @@ const clamp01 = (v: number): number => {
  * Per-key registry so repeated calls with the same `storageKey` return
  * the same store instance — necessary for cross-component state sharing
  * (e.g. ChatHeader audio toggle + ChatLauncher bus reading the same key).
+ *
+ * `E` is phantom — nothing at runtime restricts which event names the store
+ * accepts, so one instance serves callers that name different event unions.
+ * The store is therefore built and stored at the widest instantiation, and
+ * every narrower `AudioPrefsState<E>` is assignable from it.
  */
 const registry = new Map<string, UseBoundStore<StoreApi<AudioPrefsState<string>>>>();
 
@@ -39,9 +44,9 @@ export function createAudioPrefsStore<E extends string = string>(
   storageKey: string,
 ): UseBoundStore<StoreApi<AudioPrefsState<E>>> {
   const cached = registry.get(storageKey);
-  if (cached) return cached as unknown as UseBoundStore<StoreApi<AudioPrefsState<E>>>;
+  if (cached) return cached;
 
-  const store = create<AudioPrefsState<E>>()(
+  const store = create<AudioPrefsState<string>>()(
     persist(
       (set) => ({
         volume: 1,
@@ -70,7 +75,7 @@ export function createAudioPrefsStore<E extends string = string>(
     ),
   );
 
-  registry.set(storageKey, store as unknown as UseBoundStore<StoreApi<AudioPrefsState<string>>>);
+  registry.set(storageKey, store);
   return store;
 }
 

package/src/hooks/device/useBrowserDetect.ts

@@ -139,7 +139,11 @@ export function useBrowserDetect(): BrowserInfo {
     const isEdge = ua.includes('edg/') || ua.includes('edge/');
 
     // Brave (check for Brave-specific API)
-    const isBrave = !!(window.navigator as any).brave;
+    // Boundary: `navigator.brave` is a Brave-only extension absent from lib.dom.
+    // Declaring the one optional field we read keeps the probe honest without
+    // asserting anything about the rest of Navigator.
+    const braveAware: Navigator & { brave?: unknown } = window.navigator;
+    const isBrave = braveAware.brave != null;
 
     // Arc (check for Arc-specific markers in UA)
     const isArc = ua.includes('arc/');

package/src/hooks/dom/useImageLoader.ts

@@ -6,7 +6,7 @@
 
 'use client';
 
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
 export interface ImageLoaderState {
   isLoading: boolean;
@@ -16,8 +16,13 @@ export interface ImageLoaderState {
 
 export interface ImageLoaderCallbacks {
   onLoadStart?: () => void;
-  onLoad?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
-  onError?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+  /**
+   * Receives the DOM `Event` from a detached `new Image()`, NOT a React
+   * synthetic event: there is no React element behind this load, so
+   * `persist`, `nativeEvent` and `isDefaultPrevented` do not exist on it.
+   */
+  onLoad?: (event: Event) => void;
+  onError?: (event: Event) => void;
 }
 
 export const useImageLoader = (
@@ -30,18 +35,23 @@ export const useImageLoader = (
     hasError: false,
   });
 
+  // Callbacks are read through a ref so they never participate in the deps
+  // below. Callers pass `callbacks` as an inline object literal, so depending on
+  // it would re-run the load effect on every render — refetching the image and
+  // re-firing onLoadStart indefinitely. The ref keeps the latest handlers
+  // without tying image loading to render identity.
+  const callbacksRef = useRef(callbacks);
+  callbacksRef.current = callbacks;
+
   const handleLoad = useCallback((event: Event) => {
     setState({
       isLoading: false,
       isLoaded: true,
       hasError: false,
     });
-    
-    // Call user callback if provided
-    if (callbacks?.onLoad) {
-      callbacks.onLoad(event as unknown as React.SyntheticEvent<HTMLImageElement>);
-    }
-  }, [callbacks?.onLoad]);
+
+    callbacksRef.current?.onLoad?.(event);
+  }, []);
 
   const handleError = useCallback((event: Event) => {
     setState({
@@ -49,12 +59,9 @@ export const useImageLoader = (
       isLoaded: false,
       hasError: true,
     });
-    
-    // Call user callback if provided
-    if (callbacks?.onError) {
-      callbacks.onError(event as unknown as React.SyntheticEvent<HTMLImageElement>);
-    }
-  }, [callbacks?.onError]);
+
+    callbacksRef.current?.onError?.(event);
+  }, []);
 
   useEffect(() => {
     if (!src) {
@@ -72,10 +79,7 @@ export const useImageLoader = (
       hasError: false,
     });
 
-    // Call load start callback
-    if (callbacks?.onLoadStart) {
-      callbacks.onLoadStart();
-    }
+    callbacksRef.current?.onLoadStart?.();
 
     const img = new Image();
     
@@ -89,7 +93,7 @@ export const useImageLoader = (
       img.removeEventListener('load', handleLoad);
       img.removeEventListener('error', handleError);
     };
-  }, [src, handleLoad, handleError, callbacks?.onLoadStart]);
+  }, [src, handleLoad, handleError]);
 
   return state;
 };

package/src/hooks/dom/useScroll.ts

@@ -47,7 +47,7 @@
  *   const direction = useScrollDirection();
  */
 
-import { useCallback, useSyncExternalStore, type RefObject } from 'react';
+import { useCallback, useMemo, useSyncExternalStore, type RefObject } from 'react';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -264,8 +264,9 @@ const getServerSnapshot = (): ScrollSnapshot => SSR_SNAPSHOT;
  * underlying store but let React skip re-renders when other fields change.
  */
 export function useScroll(target?: ScrollTarget): ScrollSnapshot {
-  const subscribe = useCallback(subscribeFactory(target), [target]);
-  const getSnapshot = useCallback(getSnapshotFactory(target), [target]);
+  // useMemo, not useCallback: these are factory RESULTS, not inline functions.
+  const subscribe = useMemo(() => subscribeFactory(target), [target]);
+  const getSnapshot = useMemo(() => getSnapshotFactory(target), [target]);
   return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 
@@ -274,7 +275,7 @@ export function useScroll(target?: ScrollTarget): ScrollSnapshot {
  * change — direction flips and isScrolling transitions are ignored.
  */
 export function useScrollPosition(target?: ScrollTarget): { x: number; y: number } {
-  const subscribe = useCallback(subscribeFactory(target), [target]);
+  const subscribe = useMemo(() => subscribeFactory(target), [target]);
   const getServerXY = useCallback(() => SSR_XY, []);
   const getXY = useCallback(() => {
     const snap = getSnapshotFactory(target)();
@@ -298,7 +299,7 @@ function cachePosition(snap: ScrollSnapshot): { x: number; y: number } {
  * flips (e.g. user reverses scroll).
  */
 export function useScrollDirection(target?: ScrollTarget): ScrollDirection {
-  const subscribe = useCallback(subscribeFactory(target), [target]);
+  const subscribe = useMemo(() => subscribeFactory(target), [target]);
   const getDirection = useCallback(
     () => getSnapshotFactory(target)().direction,
     [target]
@@ -312,7 +313,7 @@ export function useScrollDirection(target?: ScrollTarget): ScrollDirection {
  * idle gap. Useful for hiding hover overlays while scrolling.
  */
 export function useIsScrolling(target?: ScrollTarget): boolean {
-  const subscribe = useCallback(subscribeFactory(target), [target]);
+  const subscribe = useMemo(() => subscribeFactory(target), [target]);
   const getIsScrolling = useCallback(
     () => getSnapshotFactory(target)().isScrolling,
     [target]