@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/image/ContentAdmission.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext } from 'react';
+import { imageRequestKey, imageDecodeFailed, peekDecodedImage, decodedImage, retainDecodedImage, } from './resource.js';
+/** A replacement owns its requests until it commits or a newer replacement retires it.
+ * Failure is a settled content outcome: Image renders its placeholder, not an error boundary. */
+export class ImagePreparation {
+    active = false;
+    committed = false;
+    requests = new Map();
+    read(source, request) {
+        const key = imageRequestKey(source, request);
+        let selected = this.requests.get(key);
+        if (!selected) {
+            const failed = imageDecodeFailed(source, request);
+            selected = {
+                source,
+                request,
+                image: peekDecodedImage(source, request),
+                failed,
+                settled: failed
+                    ? Promise.resolve()
+                    : decodedImage(source, request).then(image => {
+                        selected.image = image;
+                    }, () => {
+                        selected.failed = true;
+                    }),
+            };
+            this.requests.set(key, selected);
+            if (this.active && !failed) {
+                const retained = retainDecodedImage(source, request);
+                void retained.ready.catch(() => { });
+                selected.release = retained.release;
+            }
+        }
+        if (selected.failed)
+            return null;
+        if (selected.image)
+            return selected.image;
+        throw selected.settled;
+    }
+    activate() {
+        if (this.committed)
+            return;
+        this.active = true;
+        for (const selected of this.requests.values()) {
+            if (selected.failed || selected.release)
+                continue;
+            const retained = retainDecodedImage(selected.source, selected.request);
+            void retained.ready.catch(() => { });
+            selected.release = retained.release;
+        }
+    }
+    commit() {
+        this.committed = true;
+        this.release();
+    }
+    release() {
+        this.active = false;
+        for (const selected of this.requests.values()) {
+            selected.release?.();
+            selected.release = undefined;
+        }
+    }
+}
+export const ContentImageContext = createContext(false);
+/** Enable image-only admission without scheduling surrounding content. Nested
+ * screen/scroll boundaries carry the same policy; controls always commit urgently. */
+export function ContentAdmission({ children }) {
+    return _jsx(ContentImageContext, { value: true, children: children });
+}

package/dist/image/Image.d.ts

@@ -0,0 +1,30 @@
+import { type Ref, type CSSProperties, type ImgHTMLAttributes } from 'react';
+import type { ImageAsset } from './asset.js';
+/** An image's source, required alt text and aspect-ratio content mode. */
+export interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'alt' | 'srcSet' | 'loading'> {
+    readonly ref?: Ref<HTMLImageElement>;
+    readonly src: string | ImageAsset;
+    readonly alt: string;
+    readonly contentMode?: 'fit' | 'fill';
+    readonly aspectRatio?: CSSProperties['aspectRatio'];
+    readonly priority?: boolean;
+}
+export type AsyncImagePhase = {
+    readonly phase: 'empty';
+} | {
+    readonly phase: 'success';
+    readonly image: HTMLImageElement;
+} | {
+    readonly phase: 'failure';
+    readonly error: Error;
+};
+/** `Image` for a bundled or local asset: it reserves its size so layout never jumps, and
+ * `priority` loads it ahead of other images. Use `alt=""` for decoration. */
+export declare function Image(props: ImageProps): import("react").JSX.Element;
+/** An `ImageProps` whose source is a remote URL. */
+export interface AsyncImageProps extends Omit<ImageProps, 'src'> {
+    readonly src: string;
+    readonly onPhaseChange?: (phase: AsyncImagePhase) => void;
+}
+/** Remote artwork keeps its placeholder on failure and never blocks navigation. */
+export declare function AsyncImage(props: AsyncImageProps): import("react").JSX.Element;

package/dist/image/Image.js

@@ -0,0 +1,341 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLayoutEffect, useSyncExternalStore, useState, useRef, useImperativeHandle, useContext, useCallback, useMemo, useDeferredValue, Suspense, } from 'react';
+import { retainDecodedImage, peekDecodedImage, registerImageCapture, subscribeImageViewport, imageViewport, decodedImage, retryFailedImage, } from './resource.js';
+import { ContentImageContext, ImagePreparation } from './ContentAdmission.js';
+import { useReachability } from '../reachability/react.js';
+import { emptyImageSource } from './resource.js';
+const transparent = emptyImageSource;
+/** A one-pixel placeholder has its own intrinsic size. In a shrink-wrapped flex/grid
+ * hierarchy it can change the parent's width even when the img has width/height
+ * attributes and height:auto. Preserve the declared intrinsic contribution too. */
+function reservedPlaceholder(width, height, colour = transparent) {
+    const w = Number(width);
+    const h = Number(height);
+    if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0)
+        return colour;
+    // Vite emits an inline colour pixel. Never make an SVG load an external placeholder.
+    const pixel = colour.startsWith('data:image/')
+        ? `<image width="${w}" height="${h}" href="${colour.replaceAll('&', '&amp;').replaceAll('"', '&quot;')}" preserveAspectRatio="none"/>`
+        : '';
+    return ('data:image/svg+xml,' +
+        encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${pixel}</svg>`));
+}
+/** Bundled artwork. Intrinsic dimensions and variants come from a ?satin-image import. */
+function Artwork({ remote = false, admitted, ref, src, alt, contentMode = 'fit', aspectRatio, priority = false, style, width, height, sizes, crossOrigin, referrerPolicy, onLoad, onError, onPhaseChange, ...props }) {
+    const element = useRef(null);
+    // Readiness belongs to this displayed node and selected request. The shared cache
+    // avoids fetching/decoding the resource again; it does not authorize a new node.
+    const displayed = useRef(undefined);
+    const [painted, setPainted] = useState();
+    const lastPainted = useRef(undefined);
+    const [failed, setFailed] = useState();
+    const { state: reachability } = useReachability();
+    const status = reachability.status;
+    const previousStatus = useRef(status);
+    const phaseCallback = useRef(onPhaseChange);
+    phaseCallback.current = onPhaseChange;
+    const publishedPhase = useRef(undefined);
+    const reportedError = useRef(undefined);
+    useImperativeHandle(ref, () => element.current, []);
+    const asset = typeof src === 'string' ? undefined : src;
+    const url = typeof src === 'string' ? src : src.src;
+    const reportPhase = useCallback((phase) => {
+        const key = `${url}\0${phase.phase}`;
+        if (publishedPhase.current === key)
+            return;
+        publishedPhase.current = key;
+        phaseCallback.current?.(phase);
+    }, [url]);
+    useLayoutEffect(() => {
+        reportPhase({ phase: 'empty' });
+    }, [reportPhase]);
+    useLayoutEffect(() => {
+        const previous = previousStatus.current;
+        previousStatus.current = status;
+        if (failed?.url === url &&
+            status === 'reachable' &&
+            (previous === 'server-unreachable' || previous === 'device-offline')) {
+            retryFailedImage(url, { srcSet: asset?.srcSet, sizes, priority, crossOrigin, referrerPolicy });
+            displayed.current = undefined;
+            reportedError.current = undefined;
+            reportPhase({ phase: 'empty' });
+            setFailed(undefined);
+        }
+    }, [status, reportPhase, failed, url, asset, sizes, priority, crossOrigin, referrerPolicy]);
+    const intrinsicWidth = width ?? asset?.width;
+    const intrinsicHeight = height ?? asset?.height;
+    const placeholder = reservedPlaceholder(intrinsicWidth, intrinsicHeight, asset?.placeholder);
+    const reservedWidth = Number(intrinsicWidth);
+    const reservedHeight = Number(intrinsicHeight);
+    const reserved = Number.isFinite(reservedWidth) &&
+        reservedWidth > 0 &&
+        Number.isFinite(reservedHeight) &&
+        reservedHeight > 0;
+    // Retained decodes let repeat visits paint immediately, without a placeholder commit.
+    const request = { srcSet: asset?.srcSet, sizes, priority, crossOrigin, referrerPolicy };
+    const viewport = useSyncExternalStore(subscribeImageViewport, imageViewport, () => '');
+    const ready = peekDecodedImage(url, request) ?? admitted;
+    const admissionFailed = admitted === null;
+    // A new node for bytes already in memory decodes synchronously, the way UIKit decodes an
+    // image on its first display. WebKit drops decoded pixels of images whose layer is already
+    // drawn, and an async decode of a new node then paints nothing for several frames: the
+    // owner's Now Playing queue showed 4–7 empty 60 Hz frames per toggle (queue-art clip,
+    // October 11). Cold loads keep async decoding behind the placeholder.
+    const source = admissionFailed
+        ? placeholder
+        : failed?.url === url
+            ? failed.source
+            : ready
+                ? ready.currentSrc || ready.src
+                : painted?.url === url
+                    ? painted.source
+                    : placeholder;
+    // Keep decoded bytes owned across this node's source-selection and paint commits.
+    // Capture effects may retire and re-register without opening an eviction gap.
+    useLayoutEffect(() => {
+        if (admissionFailed || failed?.url === url)
+            return;
+        const retained = retainDecodedImage(url, {
+            srcSet: asset?.srcSet,
+            sizes,
+            priority,
+            crossOrigin,
+            referrerPolicy,
+        });
+        void retained.ready.catch(() => { });
+        return retained.release;
+    }, [
+        url,
+        asset?.srcSet,
+        sizes,
+        priority,
+        crossOrigin,
+        referrerPolicy,
+        viewport,
+        admissionFailed,
+        failed,
+    ]);
+    useLayoutEffect(() => {
+        const target = element.current;
+        if (admissionFailed || failed?.url === url) {
+            target.dataset.satinImageState = 'error';
+            if (admissionFailed && reportedError.current !== url) {
+                reportedError.current = url;
+                reportPhase({ phase: 'failure', error: new Error('Image unavailable') });
+                target.dispatchEvent(new Event('error'));
+            }
+            return;
+        }
+        let current = true;
+        target.dataset.satinImageState =
+            displayed.current?.ready &&
+                displayed.current.source === target.src &&
+                displayed.current.crossOrigin === crossOrigin &&
+                displayed.current.referrerPolicy === referrerPolicy
+                ? 'ready'
+                : 'pending';
+        const resource = decodedImage(url, {
+            srcSet: asset?.srcSet,
+            sizes,
+            priority,
+            crossOrigin,
+            referrerPolicy,
+        });
+        let unregister = () => { };
+        let releaseCommit = () => { };
+        const task = resource
+            .then(async (image) => {
+            if (!current)
+                return image;
+            const source = image.currentSrc || image.src;
+            // React owns src. Assigning it here and then in React's commit restarts the
+            // WebKit load after the decode that authorized reveal. Select first, retire
+            // this capture at the commit, then decode the committed node in the next effect.
+            if (target.src !== source) {
+                await new Promise(resolve => {
+                    releaseCommit = resolve;
+                    setPainted(previous => previous?.url === url && previous.source === source ? previous : { url, source });
+                });
+                if (!current)
+                    return image;
+            }
+            let selected = displayed.current;
+            if (!selected ||
+                selected.source !== source ||
+                selected.crossOrigin !== crossOrigin ||
+                selected.referrerPolicy !== referrerPolicy) {
+                selected = {
+                    source,
+                    crossOrigin,
+                    referrerPolicy,
+                    ready: false,
+                    promise: target.decode(),
+                };
+                displayed.current = selected;
+                const decoding = selected;
+                void decoding.promise.then(() => {
+                    decoding.ready = true;
+                }, () => { });
+            }
+            // Include cached visits. WebKit may load a newly mounted element after the
+            // detached cache image is ready. Reuse this node's promise across rerenders.
+            await selected.promise;
+            if (!current)
+                return image;
+            setPainted(previous => previous?.url === url && previous.source === source ? previous : { url, source });
+            lastPainted.current = { url, source };
+            target.dataset.satinImageState = 'ready';
+            reportPhase({ phase: 'success', image: target });
+            if (remote)
+                unregister = registerImageCapture(target, { source, ready: task });
+            return image;
+        })
+            .catch(async (error) => {
+            if (!current)
+                return decodedImage(placeholder);
+            const fallback = lastPainted.current?.url === url ? lastPainted.current.source : placeholder;
+            setFailed({ url, source: fallback });
+            target.dataset.satinImageState = 'error';
+            reportedError.current = url;
+            reportPhase({
+                phase: 'failure',
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+            target.dispatchEvent(new Event('error'));
+            // Glass measured this request before the failure. Give that measurement the
+            // same placeholder pixels Image owns; a failed asset is not a failed renderer.
+            return decodedImage(fallback);
+        });
+        if (!remote)
+            unregister = registerImageCapture(target, { source: url, ready: task });
+        void task.catch(() => { });
+        return () => {
+            current = false;
+            unregister();
+            releaseCommit();
+        };
+    }, [
+        url,
+        asset,
+        sizes,
+        priority,
+        ready,
+        remote,
+        crossOrigin,
+        referrerPolicy,
+        viewport,
+        painted,
+        placeholder,
+        admissionFailed,
+        failed,
+        reportPhase,
+    ]);
+    return (_jsx("img", { ...props, ref: element, alt: alt, width: intrinsicWidth, height: intrinsicHeight, sizes: sizes, crossOrigin: crossOrigin, referrerPolicy: referrerPolicy, decoding: ready ? 'sync' : 'async', fetchPriority: priority ? 'high' : undefined, draggable: false, src: source, onLoad: event => {
+            if (event.currentTarget.dataset.satinImageState === 'ready')
+                onLoad?.(event);
+        }, onError: onError, "data-satin-image-source": url, "data-satin-image-intrinsic": asset && height === undefined ? 'true' : undefined, "data-satin-row-intrinsic": "true", "data-satin-image-state": admissionFailed || failed?.url === url
+            ? 'error'
+            : displayed.current?.ready &&
+                displayed.current.source === source &&
+                displayed.current.crossOrigin === crossOrigin &&
+                displayed.current.referrerPolicy === referrerPolicy
+                ? 'ready'
+                : 'pending', style: {
+            objectFit: contentMode === 'fill' ? 'cover' : 'contain',
+            ...style,
+            ...(aspectRatio === undefined ? {} : { aspectRatio }),
+            // Reserve intrinsic contributions even before the inline placeholder loads.
+            // Size containment does not add clipping or a new containing block.
+            ...(reserved
+                ? {
+                    contain: 'size',
+                    containIntrinsicSize: `${reservedWidth}px ${reservedHeight}px`,
+                }
+                : {}),
+        } }));
+}
+/** `Image` for a bundled or local asset: it reserves its size so layout never jumps, and
+ * `priority` loads it ahead of other images. Use `alt=""` for decoration. */
+export function Image(props) {
+    const preparation = useContext(ContentImageContext);
+    if (!preparation)
+        return _jsx(Artwork, { ...props });
+    return _jsx(AdmittedImage, { ...props });
+}
+/** Reserve first-mount geometry without painting an undecoded tile. The marker
+ * belongs to this image and is removed when its decoded node can commit. */
+function PendingArtwork({ src, width, height, className, style, aspectRatio, contentMode = 'fit', priority, hidden, }) {
+    const asset = typeof src === 'string' ? undefined : src;
+    const intrinsicWidth = width ?? asset?.width;
+    const intrinsicHeight = height ?? asset?.height;
+    const reservedWidth = Number(intrinsicWidth);
+    const reservedHeight = Number(intrinsicHeight);
+    const reserved = Number.isFinite(reservedWidth) &&
+        reservedWidth > 0 &&
+        Number.isFinite(reservedHeight) &&
+        reservedHeight > 0;
+    return (_jsx("img", { alt: "", "aria-hidden": "true", className: className, width: intrinsicWidth, height: intrinsicHeight, src: reservedPlaceholder(intrinsicWidth, intrinsicHeight, asset?.placeholder), hidden: hidden, "data-satin-content-pending": "", fetchPriority: priority ? 'high' : undefined, "data-satin-row-intrinsic": "true", "data-satin-image-state": "pending", "data-satin-image-intrinsic": asset && height === undefined ? 'true' : undefined, style: {
+            objectFit: contentMode === 'fill' ? 'cover' : 'contain',
+            ...style,
+            ...(aspectRatio === undefined ? {} : { aspectRatio }),
+            ...(reserved
+                ? { contain: 'size', containIntrinsicSize: `${reservedWidth}px ${reservedHeight}px` }
+                : {}),
+            visibility: 'hidden',
+        } }));
+}
+/** Only source selection can defer. Alt text, geometry, handlers and surrounding
+ * controls receive current props even while the previous decoded source stays up.
+ * Initial mounts join the existing launch/navigation/tab readiness marker. */
+function AdmittedImage(props) {
+    const { src, sizes, priority, crossOrigin, referrerPolicy } = props;
+    const { state } = useReachability();
+    const status = state.status !== 'local' ? state.status : 'local';
+    const previousStatus = useRef(status);
+    const [recovery, setRecovery] = useState(0);
+    useLayoutEffect(() => {
+        const previous = previousStatus.current;
+        previousStatus.current = status;
+        if (status === 'reachable' &&
+            (previous === 'server-unreachable' || previous === 'device-offline')) {
+            retryFailedImage(typeof src === 'string' ? src : src.src, {
+                srcSet: typeof src === 'string' ? undefined : src.srcSet,
+                sizes,
+                priority,
+                crossOrigin,
+                referrerPolicy,
+            });
+            setRecovery(value => value + 1);
+        }
+    }, [status, src, sizes, priority, crossOrigin, referrerPolicy]);
+    const candidate = useMemo(() => ({
+        source: { src, sizes, priority, crossOrigin, referrerPolicy },
+        recovery,
+        images: new ImagePreparation(),
+    }), [src, sizes, priority, crossOrigin, referrerPolicy, recovery]);
+    useLayoutEffect(() => {
+        candidate.images.activate();
+        return () => candidate.images.release();
+    }, [candidate]);
+    return (_jsx(Suspense, { fallback: _jsx(PendingArtwork, { ...props }), children: _jsx(PreparedArtwork, { ...props, candidate: candidate }) }));
+}
+function PreparedArtwork({ candidate, ...props }) {
+    const accepted = useDeferredValue(candidate);
+    // A responsive viewport change keeps this accepted decode. Artwork separately
+    // prepares its better-sized variant without suspending an external-store update.
+    const admitted = useMemo(() => accepted.images.read(typeof accepted.source.src === 'string' ? accepted.source.src : accepted.source.src.src, {
+        srcSet: typeof accepted.source.src === 'string' ? undefined : accepted.source.src.srcSet,
+        sizes: accepted.source.sizes,
+        priority: accepted.source.priority,
+        crossOrigin: accepted.source.crossOrigin,
+        referrerPolicy: accepted.source.referrerPolicy,
+    }), [accepted]);
+    // Artwork's layout effect has acquired displayed ownership before this runs.
+    // The parent keeps the settled outcome, but need not pin an old responsive decode.
+    useLayoutEffect(() => accepted.images.commit(), [accepted]);
+    return _jsx(Artwork, { ...props, ...accepted.source, admitted: admitted });
+}
+/** Remote artwork keeps its placeholder on failure and never blocks navigation. */
+export function AsyncImage(props) {
+    return _jsx(Artwork, { ...props, remote: true, "data-satin-async-image": "true" });
+}

package/dist/image/asset.d.ts

@@ -0,0 +1,9 @@
+/** Produced by the Satin Vite plugin for imports ending in ?satin-image. */
+export interface ImageAsset {
+    readonly src: string;
+    readonly width: number;
+    readonly height: number;
+    readonly srcSet: string;
+    /** A tiny, decoded colour image, suitable for reserving the artwork's frame. */
+    readonly placeholder: string;
+}

package/dist/image/asset.js

@@ -0,0 +1 @@
+export {};

package/dist/image/contentReadiness.d.ts

@@ -0,0 +1,7 @@
+/** Reveal eligibility is relative to the destination, which may itself be hidden
+ * or translated while preparing. A declared priority image participates offscreen. */
+export declare function imageRequiredForReveal(root: HTMLElement, image: HTMLImageElement): boolean;
+export declare function hasPendingContent(root: HTMLElement): boolean;
+/** First mounts have no displayed capture. Every reveal pass includes their
+ * visible/priority markers, and the caller owns cancellation of this observer. */
+export declare function prepareMountedContent(root: HTMLElement, signal?: AbortSignal): Promise<void> | undefined;

package/dist/image/contentReadiness.js

@@ -0,0 +1,54 @@
+/** Reveal eligibility is relative to the destination, which may itself be hidden
+ * or translated while preparing. A declared priority image participates offscreen. */
+export function imageRequiredForReveal(root, image) {
+    if (image.getAttribute('fetchpriority') === 'high')
+        return true;
+    const rect = image.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0)
+        return false;
+    const route = root.getBoundingClientRect();
+    if (rect.right <= route.left ||
+        rect.left >= route.right ||
+        rect.bottom <= route.top ||
+        rect.top >= route.bottom)
+        return false;
+    const rootVisibility = getComputedStyle(root).visibility;
+    for (let parent = image; parent && parent !== root; parent = parent.parentElement) {
+        if (parent.hidden ||
+            parent.dataset.satinTabActive === 'false' ||
+            getComputedStyle(parent).display === 'none')
+            return false;
+        // Pending artwork hides its own undecoded pixels. That deliberate guard is
+        // distinct from a hidden ancestor or an author-hidden committed image.
+        const pendingMarker = parent === image && image.hasAttribute('data-satin-content-pending');
+        if (!pendingMarker &&
+            (parent.style.visibility === 'hidden' ||
+                (rootVisibility !== 'hidden' && getComputedStyle(parent).visibility === 'hidden')))
+            return false;
+    }
+    return true;
+}
+export function hasPendingContent(root) {
+    if (!root.querySelector('[data-satin-content-pending]'))
+        return false;
+    return [...root.querySelectorAll('[data-satin-content-pending]')].some(image => imageRequiredForReveal(root, image));
+}
+/** First mounts have no displayed capture. Every reveal pass includes their
+ * visible/priority markers, and the caller owns cancellation of this observer. */
+export function prepareMountedContent(root, signal) {
+    if (signal?.aborted || !hasPendingContent(root))
+        return;
+    return new Promise(resolve => {
+        const finish = () => {
+            observer.disconnect();
+            signal?.removeEventListener('abort', finish);
+            resolve();
+        };
+        const observer = new MutationObserver(() => {
+            if (!hasPendingContent(root))
+                finish();
+        });
+        observer.observe(root, { childList: true, subtree: true, attributes: true });
+        signal?.addEventListener('abort', finish, { once: true });
+    });
+}

package/dist/image/imports.d.ts

@@ -0,0 +1,4 @@
+declare module '*?satin-image' {
+  const asset: import('./asset.js').ImageAsset
+  export default asset
+}

package/dist/image/resource.d.ts

@@ -0,0 +1,53 @@
+export declare const emptyImageSource = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACXBIWXMAAAPoAAAD6AG1e1JrAAAADUlEQVQImWNgYGBgAAAABQABh6FO1AAAAABJRU5ErkJggg==";
+/** One decode cache for artwork and glass rasterization, including responsive candidates. */
+export interface ImageRequest {
+    readonly srcSet?: string;
+    readonly sizes?: string;
+    readonly crossOrigin?: '' | 'anonymous' | 'use-credentials';
+    readonly referrerPolicy?: HTMLImageElement['referrerPolicy'];
+    readonly priority?: boolean;
+}
+export declare function imageRequestKey(url: string, request: ImageRequest): string;
+export declare function peekDecodedImage(url: string, request?: ImageRequest): HTMLImageElement | undefined;
+/** Failed requests settle content admission too. Remember the outcome across
+ * suspended React retries, which may reconstruct a preparation before it commits. */
+export declare function imageDecodeFailed(url: string, request?: ImageRequest): boolean;
+/** A confirmed reconnect may retry a failed bundled request. Keep successful
+ * cached pixels and existing consumers; retire only the remembered failure. */
+export declare function retryFailedImage(url: string, request?: ImageRequest): void;
+export declare function decodedImage(url: string, request?: ImageRequest): Promise<HTMLImageElement>;
+export declare function retainDecodedImage(url: string, request?: ImageRequest): {
+    ready: Promise<HTMLImageElement>;
+    release(): void;
+};
+export type ImageCapture = {
+    source: string;
+    ready: Promise<HTMLImageElement>;
+};
+/** The element changed source or unmounted before its decode finished: not a failure. */
+export declare class SupersededImage extends Error {
+    constructor(source: string);
+}
+export declare const imageCapture: (element: HTMLImageElement) => ImageCapture | undefined;
+/** A failed content request contributes no image pixels. Replacement races still
+ * invalidate the measurement; renderer assets must never use this boundary. */
+export declare function settleContentImage(ready: Promise<HTMLImageElement | undefined>): Promise<HTMLImageElement | undefined>;
+/** Capture the displayed consumer, including raw img, without a second URL request. */
+export declare function paintedImage(element: HTMLImageElement): Promise<HTMLImageElement | undefined>;
+export declare const imageCaptureRevision: () => number;
+/** Waiters on a retired capture (glass preparation, a push) are released at once, never held
+ * until a decode nobody displays any more settles. */
+export declare function registerImageCapture(element: HTMLImageElement, capture: ImageCapture): () => void;
+/** Target preparation budget for visible bundled artwork. A missed budget is a
+ * performance failure, never permission to reveal an undecoded local Image.
+ * Owner correction: the implementation contract October 10. */
+export declare const DESTINATION_IMAGE_BUDGET_MS = 100;
+/** Local Images must be ready before reveal. The entering route is translated offscreen,
+ * so visibility is measured in the route's own coordinates. The budget is a checkpoint:
+ * after a miss, keep the source visible and the destination paused until ready or aborted.
+ * AsyncImage's remote placeholder does not register a pending capture. */
+export declare function prepareDestinationImages(root: HTMLElement, signal: AbortSignal, budget?: number): Promise<void>;
+/** Synchronous empty admission keeps image-free tab selection immediate. */
+export declare function hasDestinationImages(root: HTMLElement): boolean;
+export declare function subscribeImageViewport(notify: () => void): () => void;
+export declare const imageViewport: () => string;