@octane-xplat/ui 0.9.0 → 0.11.0

package/src/HStack.tsrx

@@ -0,0 +1,14 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { HStackProps } from './props';
+import { Stack } from './Stack';
+
+/** Horizontal flow stack — `Stack` with `direction="horizontal"`.
+ *  `hAlign` is the main axis (justify-content), `vAlign` the cross axis. */
+export function HStack(props: HStackProps) @{
+	return <Stack
+		{...props}
+		direction="horizontal"
+		hAlign={props.hAlign ?? props.justify}
+		vAlign={props.vAlign ?? props.align}
+	/>;
+}

package/src/Heading.macos.tsrx

@@ -1,4 +1,4 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
 import type { HeadingProps } from './props'
 
 export function Heading(props: HeadingProps) @{

package/src/HoverCard.mobile.tsrx

@@ -0,0 +1,36 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { HoverCardProps } from './props';
+import { useHoverCard } from './use-hover-card.mobile.tsrx';
+import { cx } from './cx';
+
+/** Touch-leaf HoverCard: a tap on the trigger opens the anchored card
+ *  (`touchTrigger` 'auto'/'tap'; 'none' disables it). There is no hover
+ *  or focus traversal on iOS/Android, so `delay`/`hideDelay`/
+ *  `focusTrigger` are inert — documented deviations. */
+export function HoverCard(props: HoverCardProps) @{
+	const card = useHoverCard({
+		placement: props.placement,
+		alignment: props.alignment,
+		touchTrigger: props.touchTrigger,
+		isEnabled: props.isEnabled,
+		label: props.label,
+		isOpen: props.isOpen,
+		isDefaultOpen: props.isDefaultOpen,
+		onShow: () => props.onOpenChange?.(true),
+		onHide: () => props.onOpenChange?.(false),
+	});
+
+	<>
+		<flexboxlayout
+			id={props.id}
+			ref={card.ref}
+			className={cx('vx-hovercard-trigger', props.className)}
+			style={props.style}
+			ios={props.ios as any}
+			android={props.android as any}
+		>
+			{props.children}
+		</flexboxlayout>
+		{card.renderHoverCard(props.content, { className: props.className })}
+	</>
+}

package/src/HoverCard.tsrx

@@ -0,0 +1,41 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { HoverCardProps } from './props';
+import { useHoverCard } from './use-hover-card.tsrx';
+import { cx } from './cx';
+import { View } from './View';
+
+/** Default (macOS) leaf — pointer intent comes from the AppKit host
+ *  bridge (tracking areas + anchored NSPopover); iOS/Android resolve the
+ *  `.mobile` leaf (tap-to-open). Bridge-absent targets render the
+ *  trigger only. `focusTrigger` has no native focus traversal to key on
+ *  — inert here (documented deviation). */
+export function HoverCard(props: HoverCardProps) @{
+	const card = useHoverCard({
+		placement: props.placement,
+		alignment: props.alignment,
+		delay: props.delay,
+		hideDelay: props.hideDelay,
+		focusTrigger: props.focusTrigger,
+		touchTrigger: props.touchTrigger,
+		isEnabled: props.isEnabled,
+		label: props.label,
+		isOpen: props.isOpen,
+		isDefaultOpen: props.isDefaultOpen,
+		onShow: () => props.onOpenChange?.(true),
+		onHide: () => props.onOpenChange?.(false),
+	});
+
+	<>
+		<View
+			id={props.id}
+			ref={card.ref}
+			className={cx('vx-hovercard-trigger', props.className)}
+			style={props.style}
+			ios={props.ios}
+			android={props.android}
+		>
+			{props.children}
+		</View>
+		{card.renderHoverCard(props.content, { className: props.className })}
+	</>
+}

package/src/HoverCard.web.tsrx

@@ -0,0 +1,99 @@
+import { useEffect, useRef } from 'octane';
+import type { HoverCardProps } from './props';
+import { useHoverCard } from './use-hover-card.web.tsrx';
+import { cx } from './cx';
+
+const isTextOnly = (children: any) =>
+	typeof children === 'string' || typeof children === 'number';
+
+/**
+ * Hover/focus/tap-triggered floating card (Astryx `HoverCard`), web leaf.
+ * The trigger is `children`; the card floats via the shared Popover
+ * layer. Element children keep their own refs — listeners and position
+ * anchor land on the first element child through a display:contents
+ * wrapper.
+ */
+export function HoverCard(props: HoverCardProps) @{
+	const card = useHoverCard({
+		placement: props.placement,
+		alignment: props.alignment,
+		delay: props.delay,
+		hideDelay: props.hideDelay,
+		focusTrigger: props.focusTrigger,
+		touchTrigger: props.touchTrigger,
+		isEnabled: props.isEnabled,
+		label: props.label,
+		isOpen: props.isOpen,
+		isDefaultOpen: props.isDefaultOpen,
+		onShow: () => props.onOpenChange?.(true),
+		onHide: () => props.onOpenChange?.(false),
+	});
+
+	const wrapper = useRef<HTMLElement | null>(null);
+	const textOnly = isTextOnly(props.children);
+	const showIndication =
+		props.hasHoverIndication === true ||
+		((props.hasHoverIndication ?? 'auto') === 'auto' && textOnly);
+
+	// Position + interaction land on the first element child (the
+	// display:contents wrapper has no box to anchor against).
+	useEffect(() => {
+		if (textOnly) return;
+		const el = wrapper.current?.firstElementChild as HTMLElement | null;
+		card.ref(el);
+		if (!el || !props.label) {
+			return;
+		}
+
+		const prevHaspopup = el.getAttribute('aria-haspopup');
+		el.setAttribute('aria-haspopup', 'dialog');
+		if (card.isOpen) {
+			el.setAttribute('aria-controls', card.id);
+		}
+
+		return () => {
+			card.ref(null);
+			if (prevHaspopup == null) {
+				el.removeAttribute('aria-haspopup');
+			} else {
+				el.setAttribute('aria-haspopup', prevHaspopup);
+			}
+
+			el.removeAttribute('aria-controls');
+		};
+	}, [textOnly, card.isOpen, props.label, card.id]);
+
+	const rendered = card.renderHoverCard(props.content, {
+		className: props.className,
+		style: props.style,
+	});
+
+	<>
+		{textOnly ? (
+			<span
+				ref={card.ref}
+				id={props.id}
+				tabIndex={0}
+				className={cx(showIndication && 'vx-hovercard-indication')}
+				aria-haspopup={props.label ? 'dialog' : undefined}
+				aria-controls={props.label && card.isOpen ? card.id : undefined}
+				aria-describedby={props.label ? undefined : card.describedBy}
+				{...props.web}
+			>
+				{props.children}
+			</span>
+		) : (
+			<span
+				ref={(el: HTMLElement | null) => {
+					wrapper.current = el;
+				}}
+				id={props.id}
+				style={{ display: 'contents' }}
+				{...props.web}
+			>
+				{props.children}
+			</span>
+		)}
+		{rendered}
+	</>;
+}

package/src/Icon.macos.tsrx

@@ -1,18 +1,22 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
 import type { IconProps } from './props'
+import { Image } from './Image.macos'
+import { glyphSvgMarkup } from './svg-glyph'
 import { getIcon } from './icons'
 
-/** Icon — no svgview/NSImage glyph path on the AppKit host yet, so the
- *  registered glyph name renders as text. `size` still sizes the frame so
- *  layouts and the parity sweep measure the declared box. */
 export function Icon(props: IconProps) @{
 	const size = props.size ?? 24
 	const glyph = getIcon(props.name)
+	const markup = glyph && glyphSvgMarkup(glyph, props.color ?? '#000000')
+	if (markup) return <Image src={markup} id={props.id} className={props.className}
+		alt={props.name}
+		style={{ width: size, height: size }} />
 
 	<label
+		id={props.id}
 		className={props.className}
-		style={{ width: size, height: size, fontSize: size * 0.75, ...props.style }}
-		accessibilityLabel={props.accessibilityLabel ?? props.name}
+		style={{ width: size, height: size, fontSize: size * 0.75 }}
+		accessibilityLabel={props.name}
 	>
 		{glyph?.font?.glyph ?? props.name}
 	</label>

package/src/Icon.tsrx

@@ -3,7 +3,7 @@ import type { IconProps } from './props';
 import { getIcon } from './icons';
 import { cx } from './cx';
 import { applyNativeProps } from './platformProps';
-import { glyphSvgMarkup, isSvgSrc, svgSource } from './svg.mobile';
+import { glyphSvgMarkup, isSvgSrc, svgSource } from './svg';
 
 export function Icon(props: IconProps) @{
 	const glyph = getIcon(props.name);

package/src/IconButton.macos.tsrx

@@ -0,0 +1,11 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import type { IconButtonProps } from './props'
+import { Pressable } from './Pressable.macos.tsrx'
+import { Icon } from './Icon.macos.tsrx'
+import { Text } from './Text.macos.tsrx'
+import { cx } from './cx'
+export function IconButton(props: IconButtonProps) @{
+	<Pressable id={props.id} className={cx('vx-button','vx-button--icon',`vx-button--${props.variant??'secondary'}`,props.className)} style={props.style} disabled={props.isDisabled||props.disabled} onPress={props.onPress} accessibilityLabel={props.accessibilityLabel??props.label} accessibilityRole="button">
+		{typeof props.icon==='string'?<Icon name={props.icon}/>:props.icon}{props.label?<Text className="vx-visually-hidden">{props.label}</Text>:null}
+	</Pressable>
+}

package/src/IconButton.tsrx

@@ -0,0 +1,7 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { IconButtonProps } from './props'
+import { Button } from './Button.tsrx'
+
+export function IconButton(props: IconButtonProps) @{
+	<Button {...props} isIconOnly={true} />
+}

package/src/IconButton.web.tsrx

@@ -0,0 +1,5 @@
+import type { IconButtonProps } from './props'
+import { Button } from './Button.web.tsrx'
+export function IconButton(props: IconButtonProps) @{
+	<Button {...props} isIconOnly={true} />
+}

package/src/Image.macos.tsrx

@@ -1,12 +1,25 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useMemo } from 'octane'
+import { appKitImageSource } from './svg-image.macos'
 import type { ImageProps } from './props'
 
 export function Image(props: ImageProps) @{
+	const srcString = (Array.isArray(props.src) ? props.src[0]?.uri : props.src) ?? ''
+	const src = useMemo(() => appKitImageSource(srcString), [srcString])
+	// contentFit → style.objectFit (the renderer maps contain/scale-down/
+	// fill/none; 'cover' degrades to scale-down — AppKit has no cover
+	// scaling mode). contentPosition is unimplemented on this leaf.
+	// `decoding` is ignored — AppKit image loads are synchronous.
+	const style = {
+		objectFit: props.contentFit ?? 'cover',
+		...props.style,
+	}
+
 	<image
 		id={props.id}
-		src={props.src}
+		src={src}
 		className={props.className}
-		style={props.style}
-		accessibilityLabel={props.accessibilityLabel}
+		{style}
+		accessibilityLabel={props.alt ?? ''}
 	/>
 }

package/src/Image.tsrx

@@ -1,30 +1,182 @@
 /** @jsxImportSource @nativescript-community/octane */
-import { ImageSource } from '@nativescript/core';
-import { useMemo } from 'octane';
-import type { ImageProps } from './props';
+import { isAndroid, isIOS, ImageSource, knownFolders, Screen } from '@nativescript/core';
+import { useLayoutEffect, useMemo, useRef } from 'octane';
+import type { ImageProps, ImageSourceLike } from './props';
 import { cx } from './cx';
 import { applyEscapeProps } from './escape-props';
+import { rememberGridChildPlacement } from './grid-placement';
 import { layoutChildProps } from './layout-child';
-import { isSvgSrc, svgSource } from './svg.mobile';
+import { isSvgSrc, svgSource } from './svg';
+import { createSizedImageBinding } from './image-sizing';
+import { contentFitToStretch, needsContentRect, resolveContentFit, resolveContentPosition } from './image-content';
+import { createImageContentBinding } from './image-content-binding';
+import { hashToPngBase64 } from './hash-image';
+
+/** Resolves `placeholder` to an ImageSource synchronously — a placeholder
+ *  that must fetch first defeats its purpose, so remote URLs are ignored.
+ *  Accepts `blurhash:`/`thumbhash:` (decoded to PNG bytes in JS — see
+ *  ./hash-image), `data:` base64, `res://`, `~/`, and plain file paths. */
+function placeholderSource(placeholder: string): ImageSource | null {
+	const png = hashToPngBase64(placeholder);
+	if (png) {
+		return ImageSource.fromBase64Sync(png);
+	}
+
+	const comma = placeholder.indexOf(',');
+	if (
+		placeholder.startsWith('data:') &&
+		comma > 0 &&
+		placeholder.slice(0, comma).endsWith(';base64')
+	) {
+		return ImageSource.fromBase64Sync(placeholder.slice(comma + 1));
+	}
+
+	if (placeholder.startsWith('res://')) {
+		return ImageSource.fromResourceSync(placeholder.slice('res://'.length));
+	}
+
+	if (placeholder.startsWith('~/')) {
+		return ImageSource.fromFileSync(
+			knownFolders.currentApp().path + '/' + placeholder.slice(2),
+		);
+	}
+
+	if (!/^https?:\/\//.test(placeholder)) {
+		return ImageSource.fromFileSync(placeholder);
+	}
+
+	return null;
+}
+
+/** Re-resolves on every call — iOS disposes the previous ImageSource's
+ *  native image each time `src` is assigned. Only writes when a load is
+ *  pending (or nothing is showing), so a completed final image is never
+ *  clobbered. */
+function applyPlaceholder(view: any, placeholder: string | undefined): void {
+	if (!placeholder || !(view.isLoading || !view.imageSource)) {
+		return;
+	}
+
+	const ph = placeholderSource(placeholder);
+	if (ph) {
+		view.imageSource = ph;
+	}
+}
+
 /** Image — NS <image>. `src` accepts the NS ImageSource grammar:
- *  res://name, ~/bundle-path, file path, remote URL, or data: URI. SVG srcs
- *  (inline markup, svg data URIs, .svg paths/URLs) route to <svgview> —
- *  remote .svg URLs fetch to markup since SVGView has no fetch of its own.
- *  `alt` maps to accessibilityLabel (RN calls it `alt` on web parity). */
+ *  res://name, ~/bundle-path, file path, remote URL, or data: URI; an
+ *  ImageSourceLike[] picks the closest pixel count to the laid-out view
+ *  (srcset for native — study L8). SVG srcs (inline markup, svg data URIs,
+ *  .svg paths/URLs) route to <svgview> — remote .svg URLs fetch to markup
+ *  since SVGView has no fetch of its own. `alt` maps to accessibilityLabel
+ *  (RN calls it `alt` on web parity).
+ *  `contentFit` maps to stretch for the centered contain/cover/fill cases.
+ *  'none'/'scale-down'/positioned content takes the computed path: the
+ *  binding measures the host box, computes the CSS content rect, and lays
+ *  out an inner fill-stretched <image> inside a clipped absolutelayout —
+ *  the view-level equivalent of expo's matrix (the stock NS widget owns
+ *  its own draw matrix; see image-content-binding.ts).
+ *  `src` never goes through JSX: the content binding resolves WHICH source
+ *  (the array pick, or the prop as-is) and hands it to the sized binding,
+ *  which holds it until first layout then sets decodeWidth/decodeHeight in
+ *  device px before assigning — an eager src would decode at full source
+ *  resolution on Android (study L1).
+ *  `placeholder` rides the same view: NS nulls `imageSource` whenever a new
+ *  `src` is applied, so the leaf (re)assigns the placeholder bitmap whenever
+ *  the pipeline reports a pending load (`isLoadingChange`) and after every
+ *  binding src write (`afterIssue` — a same-src re-issue mid-load fires no
+ *  event). Placeholder → final inside one view; on the computed-rect path
+ *  the inner stretch='fill' image scales it with the same content math, so
+ *  fit/position match the final (expo-image study L5). A failed load leaves
+ *  the placeholder standing — failure-image semantics for free.
+ *  `decoding` maps to NS `loadMode` (default 'async' — the binding defers
+ *  src to first layout, so loadMode is always on the view before src is
+ *  issued); 'sync' blocks the UI thread at decode for must-paint-now
+ *  bitmaps. Remote URLs decode async and font-icon srcs sync regardless —
+ *  NS honors loadMode only on the file/resource/data paths. */
+function clipImageHost(host: any): void {
+	host?.on?.('loaded', () => {
+		// iOS UIView clipsToBounds defaults false (DOM/NS overflow:visible);
+		// cover/positioned rects must clip at the component box. Android
+		// ViewGroups clip children by default — and the host never receives
+		// escape props, which would unclip it.
+		if (isIOS && host.ios) {
+			host.ios.clipsToBounds = true;
+		}
+	});
+}
+
 export function Image(props: ImageProps) @{
-	const svg = useMemo(() => (isSvgSrc(props.src) ? svgSource(props.src) : null), [props.src]);
+	const sources = Array.isArray(props.src) ? (props.src as ImageSourceLike[]) : null;
+	const srcString = sources ? '' : (props.src as string);
+	const fit = resolveContentFit(props.contentFit);
+	const position = resolveContentPosition(props.contentPosition);
+	const computed = needsContentRect(fit, position);
+	const imageRef = useRef<any>(null);
+	const placeholderRef = useRef(props.placeholder);
+	placeholderRef.current = props.placeholder;
+	const sizing = useMemo(
+		() =>
+			createSizedImageBinding({
+				afterIssue: (v: any) => applyPlaceholder(v, placeholderRef.current),
+			}),
+		[],
+	);
+
+	const binding = useMemo(
+		() =>
+			createImageContentBinding({
+				isAndroid,
+				screenScale: () => Screen.mainScreen?.scale ?? 1,
+				issue: (view: any, src: any, gate?: string) => sizing.update(view, src, gate),
+			}),
+		[],
+	);
+
+	const boundRef = useRef({ key: props.recyclingKey, src: props.src });
+	const bound = boundRef.current;
+	boundRef.current = { key: props.recyclingKey, src: props.src };
+	// expo-image `recyclingKey`: platform-list cells rebind the same view, and
+	// Android's setUri keeps drawing the previous bitmap until the new fetch
+	// resolves. Clear it before the ref re-binds the next src — only when
+	// identity AND source both changed (same src = same bitmap).
+	if (
+		bound.key != null &&
+		props.recyclingKey != null &&
+		bound.key !== props.recyclingKey &&
+		bound.src !== props.src &&
+		imageRef.current
+	) {
+		imageRef.current.imageSource = null;
+	}
+
+	const svg = useMemo(() => (srcString && isSvgSrc(srcString) ? svgSource(srcString) : null), [srcString]);
 	const source = useMemo(() => {
-		const comma = props.src.indexOf(',');
+		const comma = srcString.indexOf(',');
 		if (
-			props.src.startsWith('data:') &&
+			srcString.startsWith('data:') &&
 			comma > 0 &&
-			props.src.slice(0, comma).endsWith(';base64')
+			srcString.slice(0, comma).endsWith(';base64')
 		) {
-			return ImageSource.fromBase64Sync(props.src.slice(comma + 1));
+			return ImageSource.fromBase64Sync(srcString.slice(comma + 1));
 		}
 
-		return props.src;
-	}, [props.src]);
+		return srcString;
+	}, [srcString]);
+
+	const update = { source: sources ? null : source, sources, fit, position, computed };
+
+	useLayoutEffect(() => {
+		const view = imageRef.current;
+		if (!view || !props.placeholder || svg != null) {
+			return;
+		}
+
+		const show = () => applyPlaceholder(view, props.placeholder);
+		show();
+		view.on?.('isLoadingChange', show);
+		return () => view.off?.('isLoadingChange', show);
+	}, [props.src, props.placeholder, svg]);
 
 	@if (svg != null) {
 		<svgview
@@ -34,17 +186,51 @@ export function Image(props: ImageProps) @{
 			className={cx(props.className)}
 			style={props.style}
 			src={svg}
-			stretch="aspectFit"
+			stretch={fit === 'none' ? 'none' : contentFitToStretch(fit === 'scale-down' ? 'contain' : fit)}
 			accessibilityLabel={props.alt}
 		/>
+	} @else if (computed) {
+		<absolutelayout
+			ref={(v: any) => {
+				clipImageHost(v);
+				rememberGridChildPlacement(v, props);
+				if (v) {
+					binding.update(v, null, update);
+				}
+			}}
+			id={props.id}
+			{...layoutChildProps(props)}
+			className={cx(props.className)}
+			style={props.style}
+		>
+			<image
+				ref={(v: any) => {
+					imageRef.current = v;
+					applyEscapeProps(v, props);
+					if (v) {
+						binding.update(null, v, update);
+					}
+				}}
+				stretch="fill"
+				loadMode={props.decoding ?? 'async'}
+				accessibilityLabel={props.alt}
+			/>
+		</absolutelayout>
 	} @else {
 		<image
-			ref={(v: any) => applyEscapeProps(v, props)}
+			ref={(v: any) => {
+				imageRef.current = v;
+				applyEscapeProps(v, props);
+				if (v) {
+					binding.update(v, v, update);
+				}
+			}}
 			id={props.id}
 			{...layoutChildProps(props)}
 			className={cx(props.className)}
 			style={props.style}
-			src={source}
+			stretch={contentFitToStretch(fit)}
+			loadMode={props.decoding ?? 'async'}
 			accessibilityLabel={props.alt}
 		/>
 	}

package/src/Image.web.tsrx

@@ -1,14 +1,100 @@
-import type { ImageProps } from "./props";
+import type { ImageProps, ImageSourceLike } from "./props";
 import { applyEscapeProps } from "./escape-props";
-import { layoutChildProps } from './layout-child.web';
-/** Image — a plain <img>. `src` takes any URL or data: URI. */
+import { layoutChildProps, normStyle } from './layout-child.web';
+import { useLayoutEffect, useRef } from 'octane'
+import { imageSrcSet, objectPositionCSSValue, resolveContentFit, resolveContentPosition } from './image-content';
+import { hashToPngBase64 } from './hash-image'
+
+/** `blurhash:`/`thumbhash:` decode to a data: PNG (./hash-image); every
+ *  other value passes through as an ordinary <img> URL (a low-res source
+ *  URL is a fine placeholder on web). */
+function placeholderUrl(placeholder: string): string {
+	const png = hashToPngBase64(placeholder)
+	return png ? `data:image/png;base64,${png}` : placeholder
+}
+
+/** Image — a plain <img>. `src` takes any URL or data: URI; a source array
+ *  becomes a real `srcset` (w descriptors from width·scale, x from scale —
+ *  the browser owns selection, the same role bestImageSource plays on
+ *  native). `contentFit`/`contentPosition` map 1:1 to object-fit/
+ *  object-position; explicit props win over style, style wins over the
+ *  'cover'/'50% 50%' defaults. `placeholder` rides the same element: the
+ *  img keeps showing its last decoded image while a new src fetches, so
+ *  assigning placeholder → src swaps placeholder → final in one view —
+ *  never a blank frame and no parallel loader (expo-image study L5). A
+ *  hidden prefetch keeps the final fetch running while the placeholder
+ *  paints. `decoding` writes the HTML `decoding` attribute 1:1 (default
+ *  'async' — the shared contract's default, not the browser's 'auto'). */
 export function Image(props: ImageProps) @{
+	const imgRef = useRef<HTMLImageElement | null>(null)
+	const sources = Array.isArray(props.src) ? (props.src as ImageSourceLike[]) : null;
+	const selected = sources
+		? imageSrcSet(sources)
+		: { src: props.src as string, srcSet: undefined };
+
+	useLayoutEffect(() => {
+		const img = imgRef.current
+		// complete = the current src already resolved (cache/sync data URI) —
+		// showing the placeholder would flash backwards.
+		if (!img || !props.placeholder || img.complete) return
+		const placeholder = placeholderUrl(props.placeholder)
+		const { src: final, srcSet: finalSrcSet } = selected
+		// (document.createElement — `Image` here is this component, not the
+		// global HTMLImageElement constructor)
+		const warm = document.createElement('img')
+		warm.src = final
+		if (finalSrcSet) {
+			warm.srcset = finalSrcSet
+		}
+
+		const swap = () => {
+			img.src = final
+			if (finalSrcSet) {
+				// srcset overrides src while present — restore it after the
+				// src write so both point at the final selection.
+				img.srcset = finalSrcSet
+			}
+		}
+
+		img.addEventListener('load', swap, { once: true })
+		img.addEventListener('error', swap, { once: true })
+		if (finalSrcSet) {
+			// While srcset is set it wins over src — clear it or the
+			// placeholder assignment below is inert.
+			img.srcset = ''
+		}
+
+		img.src = placeholder
+		return () => {
+			img.removeEventListener('load', swap)
+			img.removeEventListener('error', swap)
+		}
+	}, [props.src, props.placeholder])
+
+	const style = {
+		objectFit: 'cover',
+		objectPosition: '50% 50%',
+		...normStyle(props.style),
+		...(props.contentFit !== undefined
+			? { objectFit: resolveContentFit(props.contentFit) }
+			: null),
+		...(props.contentPosition !== undefined
+			? { objectPosition: objectPositionCSSValue(resolveContentPosition(props.contentPosition)) }
+			: null),
+	};
+
 	<img
-		ref={(e: any) => applyEscapeProps(e, props)}
+		ref={(e: any) => {
+			imgRef.current = e
+			applyEscapeProps(e, props)
+		}}
 		id={props.id}
 		className={props.className}
 		{...layoutChildProps(props)}
-		src={props.src}
+		src={selected.src}
+		srcSet={selected.srcSet}
+		decoding={props.decoding ?? 'async'}
 		alt={props.alt}
+		style={style}
 	/>
 }