@meginhufr/brua-web 0.2.0 → 0.4.0

package/dist/BruaPicture.svelte

@@ -1,30 +1,42 @@
 <!-- Brua for Svelte 5: the asset as a picture element (SPEC.md 7.2). The browser picks the format, density
      and color scheme, and follows dark mode live. Animations show their still. Import from "@meginhufr/brua-web/svelte".
      Given an id instead of an asset, the current release is read from the edge through the Brua set with
-     setBrua(); the last release it read shows at once, else the children until it has loaded, and when nothing is released under the id. -->
+     setBrua(); the last release it read shows at once, else the children until it has loaded. The error snippet, given the
+     reason, shows when there is no picture: nothing released, the edge unreachable, or the file failed; without it, the
+     children show then. -->
 <script>
   import { getContext } from "svelte";
-  import { pictureModel } from "./picture.ts";
+  import { fillStyle, pictureModel } from "./picture.ts";
+  import { assetOrError } from "./brua.ts";
 
-  /** @type {{ asset?: import("./types.ts").AssetResponse, id?: string, brua?: import("./brua.ts").Brua, sizes?: string, loading?: "lazy" | "eager", class?: string, colorScheme?: "light" | "dark", children?: import("svelte").Snippet }} */
-  let { asset: given, id, brua = getContext("brua"), sizes, loading, class: imgClass, colorScheme, children } = $props();
+  /** @type {{ asset?: import("./types.ts").AssetResponse, id?: string, brua?: import("./brua.ts").Brua, sizes?: string, loading?: "lazy" | "eager", class?: string, colorScheme?: "light" | "dark", objectFit?: "contain" | "cover" | "none", objectPosition?: string, children?: import("svelte").Snippet, error?: import("svelte").Snippet<[import("./types.ts").BruaImageError]> }} */
+  let { asset: given, id, brua = getContext("brua"), sizes, loading, class: imgClass, colorScheme, objectFit, objectPosition, children, error } = $props();
   // The last release the Brua read renders at once, so a remounted picture doesn't flash its children.
   let fetched = $state(id === undefined ? undefined : brua?.cachedAsset(id));
+  /** @type {import("./types.ts").BruaImageError | undefined} */
+  let reason = $state();
+  /** @type {string | undefined} */
+  let failed = $state();
 
   $effect(() => {
     if (given || id === undefined) return;
     if (!brua) throw new Error("BruaPicture with an id needs setBrua() in a parent, or a brua prop.");
     let live = true;
     fetched = brua.cachedAsset(id);
-    brua.asset(id).then((loaded) => { if (live) fetched = loaded; }, () => {});
+    reason = undefined;
+    assetOrError(brua, id).then((read) => { if (live) { fetched = read.asset; reason = read.error; } });
     return () => { live = false; };
   });
 
   let asset = $derived(given ?? fetched);
-  let model = $derived(asset ? pictureModel(asset, { sizes, loading, className: imgClass, colorScheme }) : undefined);
+  let model = $derived(asset ? pictureModel(asset, { sizes, loading, className: imgClass, colorScheme, objectFit, objectPosition }) : undefined);
+  // The img's own error event: the file failed. Another file (a merge, another size) tries again.
+  let failure = $derived(model && failed === model.img.src ? { reason: "file", url: model.img.src } : !asset ? reason : undefined);
 </script>
 
-{#if model}
+{#if failure}
+  {#if error}{@render error(failure)}{:else if children}{@render children()}{/if}
+{:else if model}
   <picture>
     {#each model.sources as source (source.type + (source.media ?? ""))}
       <source type={source.type} media={source.media} srcset={source.srcset} sizes={source.sizes} />
@@ -40,6 +52,8 @@
       loading={model.img.loading}
       decoding={model.img.decoding}
       class={model.img.className}
+      style={fillStyle(model.img)}
+      onerror={() => (failed = model.img.src)}
     />
   </picture>
 {:else if children}

package/dist/brua.d.ts

@@ -1,4 +1,4 @@
-import type { AssetResponse } from "./types.ts";
+import type { AssetResponse, BruaImageError } from "./types.ts";
 export interface BruaOptions {
     /** The organization's asset prefix on the edge, such as https://cdn.brua.dev/assets/{org}. */
     base: string;
@@ -28,3 +28,11 @@ export interface Brua {
     prefetch(ids: string[]): Promise<void>;
 }
 export declare function createBrua(options: BruaOptions): Brua;
+/**
+ * The asset with this id, or why there is none: not released, or the edge can't be reached with no release known. The
+ * framework components show their error view from it.
+ */
+export declare function assetOrError(brua: Brua, id: string): Promise<{
+    asset?: AssetResponse;
+    error?: BruaImageError;
+}>;

package/dist/brua.js

@@ -58,3 +58,16 @@ export function createBrua(options) {
     };
     return brua;
 }
+/**
+ * The asset with this id, or why there is none: not released, or the edge can't be reached with no release known. The
+ * framework components show their error view from it.
+ */
+export async function assetOrError(brua, id) {
+    try {
+        const asset = await brua.asset(id);
+        return asset ? { asset } : { error: { reason: "notReleased" } };
+    }
+    catch (cause) {
+        return { error: { reason: "unreachable", cause } };
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export type { AssetResponse, AssetVariant, ClientState } from "./types.ts";
+export type { AssetResponse, AssetVariant, BruaImageError, ClientState } from "./types.ts";
 export { selectUrl, selectVariant } from "./select.ts";
-export { pictureHtml, pictureModel, type PictureOptions, type PictureModel, type PictureSource, type PictureImage } from "./picture.ts";
+export { fillStyle, pictureHtml, pictureModel, type PictureOptions, type PictureModel, type PictureSource, type PictureImage } from "./picture.ts";
+export { objectFitOf, objectPositionOf, targetWidth, type ObjectFit } from "./sizing.ts";
 export { browserClientState, defaultClientState, watchClientState, type ClientOptions } from "./client.ts";
-export { createBrua, type Brua, type BruaOptions } from "./brua.ts";
+export { assetOrError, createBrua, type Brua, type BruaOptions } from "./brua.ts";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { selectUrl, selectVariant } from "./select.js";
-export { pictureHtml, pictureModel } from "./picture.js";
+export { fillStyle, pictureHtml, pictureModel } from "./picture.js";
+export { objectFitOf, objectPositionOf, targetWidth } from "./sizing.js";
 export { browserClientState, defaultClientState, watchClientState } from "./client.js";
-export { createBrua } from "./brua.js";
+export { assetOrError, createBrua } from "./brua.js";

package/dist/picture.d.ts

@@ -9,6 +9,13 @@ export interface PictureOptions {
      * the dark files go behind a media query and the browser follows the system setting.
      */
     colorScheme?: "light" | "dark";
+    /**
+     * How the img fills its box: "contain" or "cover" overrides the asset's own fit, and "none" leaves the fit and
+     * the position to the page's CSS. Left out, the asset's fit is used.
+     */
+    objectFit?: "contain" | "cover" | "none";
+    /** Where the img sits in its box, as "x% y%"; left out, the asset's position. */
+    objectPosition?: string;
 }
 /** A `<source>` of the picture: one format, optionally one color scheme. */
 export interface PictureSource {
@@ -29,6 +36,9 @@ export interface PictureImage {
     loading: "lazy" | "eager";
     decoding: "async";
     className?: string;
+    /** The object-fit and object-position the img is drawn with, when the asset or the call site gives a fill. */
+    objectFit?: "contain" | "cover";
+    objectPosition?: string;
 }
 /** What a picture element for the asset consists of; the HTML renderer and the framework components build from it. */
 export interface PictureModel {
@@ -41,5 +51,7 @@ export interface PictureModel {
  * without client hints and switches live with the color scheme. Animations aren't rendered; their stills are.
  */
 export declare function pictureModel(asset: AssetResponse, options?: PictureOptions): PictureModel;
+/** The img's fill as a style attribute's value. */
+export declare function fillStyle(img: PictureImage): string | undefined;
 /** The picture as an HTML string, for innerHTML or server-rendered pages. */
 export declare function pictureHtml(asset: AssetResponse, options?: PictureOptions): string;

package/dist/picture.js

@@ -1,3 +1,4 @@
+import { objectFitOf, objectPositionOf } from "./sizing.js";
 const SVG = "image/svg+xml";
 /** Formats offered as <source> elements, best first; anything else becomes the <img> fallback. */
 const SOURCE_TYPES = ["image/avif", "image/webp"];
@@ -51,9 +52,25 @@ export function pictureModel(asset, options = {}) {
             loading: options.loading ?? "lazy",
             decoding: "async",
             className: options.className,
+            ...fill(asset, options),
         },
     };
 }
+/**
+ * The fill to put on the img: the call site's or the asset's, cleaned to what CSS takes. A response from before the
+ * fill, with no override either, gets none, so the page draws it as it always has.
+ */
+function fill(asset, options) {
+    if (options.objectFit === "none")
+        return {};
+    if (asset.objectFit === undefined && asset.objectPosition === undefined && options.objectFit === undefined && options.objectPosition === undefined)
+        return {};
+    return { objectFit: objectFitOf(asset, options.objectFit), objectPosition: objectPositionOf(asset, options.objectPosition) };
+}
+/** The img's fill as a style attribute's value. */
+export function fillStyle(img) {
+    return img.objectFit === undefined ? undefined : `object-fit: ${img.objectFit}; object-position: ${img.objectPosition}`;
+}
 /** The picture as an HTML string, for innerHTML or server-rendered pages. */
 export function pictureHtml(asset, options = {}) {
     const { sources, img } = pictureModel(asset, options);
@@ -69,6 +86,7 @@ export function pictureHtml(asset, options = {}) {
         loading: img.loading,
         decoding: img.decoding,
         class: img.className,
+        style: fillStyle(img),
     }));
     return `<picture>${rendered.join("")}</picture>`;
 }

package/dist/react.d.ts

@@ -2,7 +2,7 @@ import { type ReactElement, type ReactNode } from "react";
 import { type PictureOptions } from "./picture.ts";
 import { type ClientOptions } from "./client.ts";
 import { type Brua, type BruaOptions } from "./brua.ts";
-import type { AssetResponse } from "./types.ts";
+import type { AssetResponse, BruaImageError } from "./types.ts";
 export type BruaProviderProps = {
     children?: ReactNode;
 } & ({
@@ -15,6 +15,14 @@ export declare function BruaProvider(props: BruaProviderProps): ReactElement;
  * undefined until it has loaded, and when nothing is released under the id. Loads only in the browser; a server render shows the fallback.
  */
 export declare function useBruaAsset(id: string | undefined, brua?: Brua): AssetResponse | undefined;
+/**
+ * The asset's current release for an id, as useBruaAsset gives it, or the error when there is none: not released, or
+ * the edge can't be reached with no release known. Both undefined while it loads.
+ */
+export declare function useBruaAssetState(id: string | undefined, brua?: Brua): {
+    asset?: AssetResponse;
+    error?: BruaImageError;
+};
 export interface BruaPictureProps extends PictureOptions {
     /** The asset as your backend embedded it: a snapshot of one release. */
     asset?: AssetResponse;
@@ -22,14 +30,16 @@ export interface BruaPictureProps extends PictureOptions {
     id?: string;
     /** The Brua to read the id through, instead of the provider's. */
     brua?: Brua;
-    /** What shows until the id has loaded, and when nothing is released under it. */
+    /** What shows until the id has loaded, and on failure when no error view is given. */
     fallback?: ReactNode;
+    /** What shows when there is no picture, with the reason: nothing released, the edge unreachable, or the file failed. */
+    error?: ReactNode | ((error: BruaImageError) => ReactNode);
 }
 /**
  * The asset as a picture element (SPEC.md 7.2): the browser picks the format, density and color scheme,
  * and follows dark mode live. Animations show their still.
  */
-export declare function BruaPicture({ asset, id, brua, fallback, sizes, loading, className, colorScheme }: BruaPictureProps): ReactElement | null;
+export declare function BruaPicture({ asset, id, brua, fallback, error, sizes, loading, className, colorScheme, objectFit, objectPosition }: BruaPictureProps): ReactElement | null;
 /**
  * One variant URL for the asset, chosen for this browser and kept current as its appearance, motion setting
  * or pixel density changes: for a CSS background, a canvas or an animation player. Renders light at 1x on

package/dist/react.js

@@ -3,7 +3,7 @@ import { createContext, createElement, useContext, useEffect, useMemo, useState
 import { pictureModel } from "./picture.js";
 import { selectUrl } from "./select.js";
 import { defaultClientState, watchClientState } from "./client.js";
-import { createBrua } from "./brua.js";
+import { assetOrError, createBrua } from "./brua.js";
 const BruaContext = createContext(undefined);
 /** Where the app's assets are read from by id: wrap the app once, then <BruaPicture id="…"> anywhere below. */
 export function BruaProvider(props) {
@@ -17,33 +17,45 @@ export function BruaProvider(props) {
  * undefined until it has loaded, and when nothing is released under the id. Loads only in the browser; a server render shows the fallback.
  */
 export function useBruaAsset(id, brua) {
+    return useBruaAssetState(id, brua).asset;
+}
+/**
+ * The asset's current release for an id, as useBruaAsset gives it, or the error when there is none: not released, or
+ * the edge can't be reached with no release known. Both undefined while it loads.
+ */
+export function useBruaAssetState(id, brua) {
     const fromContext = useContext(BruaContext);
     const client = brua ?? fromContext;
     // The last release the Brua read renders at once, so a remounted picture doesn't flash its fallback.
-    const [asset, setAsset] = useState(() => (id === undefined ? undefined : client?.cachedAsset(id)));
+    const [state, setState] = useState(() => ({ asset: id === undefined ? undefined : client?.cachedAsset(id) }));
     if (id !== undefined && !client)
         throw new Error("useBruaAsset needs a <BruaProvider> above it, or a Brua passed in.");
     useEffect(() => {
         if (id === undefined || !client)
             return;
         let live = true;
-        setAsset(client.cachedAsset(id));
-        client.asset(id).then((loaded) => { if (live)
-            setAsset(loaded); }, () => { });
+        setState({ asset: client.cachedAsset(id) });
+        assetOrError(client, id).then((read) => { if (live)
+            setState(read); });
         return () => { live = false; };
     }, [client, id]);
-    return id === undefined ? undefined : asset;
+    return id === undefined ? {} : state;
 }
 /**
  * The asset as a picture element (SPEC.md 7.2): the browser picks the format, density and color scheme,
  * and follows dark mode live. Animations show their still.
  */
-export function BruaPicture({ asset, id, brua, fallback = null, sizes, loading, className, colorScheme }) {
-    const fetched = useBruaAsset(asset ? undefined : id, brua);
-    const shown = asset ?? fetched;
+export function BruaPicture({ asset, id, brua, fallback = null, error, sizes, loading, className, colorScheme, objectFit, objectPosition }) {
+    const fetched = useBruaAssetState(asset ? undefined : id, brua);
+    const [failed, setFailed] = useState();
+    const shown = asset ?? fetched.asset;
+    const failure = (reason) => (error === undefined ? fallback : typeof error === "function" ? error(reason) : error);
     if (!shown)
-        return fallback;
-    const { sources, img } = pictureModel(shown, { sizes, loading, className, colorScheme });
+        return fetched.error ? failure(fetched.error) : fallback;
+    const { sources, img } = pictureModel(shown, { sizes, loading, className, colorScheme, objectFit, objectPosition });
+    // The img's own error event: the file failed. Another file (a merge, another size) tries again.
+    if (failed === img.src)
+        return failure({ reason: "file", url: img.src });
     return createElement("picture", null, ...sources.map((s) => createElement("source", { key: `${s.type}${s.media ?? ""}`, type: s.type, media: s.media, srcSet: s.srcset, sizes: s.sizes })), createElement("img", {
         src: img.src,
         srcSet: img.srcset,
@@ -55,6 +67,8 @@ export function BruaPicture({ asset, id, brua, fallback = null, sizes, loading,
         loading: img.loading,
         decoding: img.decoding,
         className: img.className,
+        style: img.objectFit === undefined ? undefined : { objectFit: img.objectFit, objectPosition: img.objectPosition },
+        onError: () => setFailed(img.src),
     }));
 }
 /**

package/dist/sizing.d.ts

@@ -0,0 +1,12 @@
+import type { AssetResponse } from "./types.ts";
+export type ObjectFit = "contain" | "cover";
+/** The fit to draw with: the call site's override, else the asset's, else contain. Unknown values are contain. */
+export declare function objectFitOf(asset: Pick<AssetResponse, "objectFit">, override?: string): ObjectFit;
+/** Where the picture sits in its box, as "x% y%": the call site's, else the asset's, else the centre. */
+export declare function objectPositionOf(asset: Pick<AssetResponse, "objectPosition">, override?: string): string;
+/**
+ * How wide the picture is drawn in a box of this size, in CSS pixels or points, for the selection rule's
+ * `targetWidth`. Contain, or a box without a height yet, draws it at the box width; cover at the larger of the box
+ * width and the box height times the asset's proportions.
+ */
+export declare function targetWidth(asset: Pick<AssetResponse, "width" | "height" | "objectFit">, boxWidth: number, boxHeight?: number, objectFit?: string): number;

package/dist/sizing.js

@@ -0,0 +1,21 @@
+const POSITION = /^(100|[1-9]?[0-9])% (100|[1-9]?[0-9])%$/;
+/** The fit to draw with: the call site's override, else the asset's, else contain. Unknown values are contain. */
+export function objectFitOf(asset, override) {
+    const fit = override ?? asset.objectFit;
+    return fit === "cover" ? "cover" : "contain";
+}
+/** Where the picture sits in its box, as "x% y%": the call site's, else the asset's, else the centre. */
+export function objectPositionOf(asset, override) {
+    const position = override ?? asset.objectPosition;
+    return position !== undefined && POSITION.test(position) ? position : "50% 50%";
+}
+/**
+ * How wide the picture is drawn in a box of this size, in CSS pixels or points, for the selection rule's
+ * `targetWidth`. Contain, or a box without a height yet, draws it at the box width; cover at the larger of the box
+ * width and the box height times the asset's proportions.
+ */
+export function targetWidth(asset, boxWidth, boxHeight, objectFit) {
+    if (objectFitOf(asset, objectFit) !== "cover" || boxHeight === undefined || boxHeight <= 0 || asset.height <= 0)
+        return boxWidth;
+    return Math.max(boxWidth, boxHeight * (asset.width / asset.height));
+}

package/dist/types.d.ts

@@ -8,7 +8,24 @@ export interface AssetResponse {
     alt: string;
     lang?: string;
     variants: AssetVariant[];
+    /** How a layout's box of another shape holds the asset, as CSS object-fit: "contain" or "cover". */
+    objectFit?: string;
+    /** Where it sits in the box, as CSS object-position: "50% 35%", the point a cover crop keeps in view. */
+    objectPosition?: string;
 }
+/**
+ * Why a picture has none to show, with the same reasons on every platform's SDK: nothing is released under the id (the
+ * edge answered 404, usually draw nothing), the edge can't be reached and no release is known, or the file failed.
+ */
+export type BruaImageError = {
+    reason: "notReleased";
+} | {
+    reason: "unreachable";
+    cause: unknown;
+} | {
+    reason: "file";
+    url: string;
+};
 /** Value fields are plain strings, not unions, so new values from the API never break decoding (SPEC.md 14). */
 export interface AssetVariant {
     type: string;

package/dist/vue.d.ts

@@ -1,7 +1,7 @@
 import { type ComputedRef, type InjectionKey, type MaybeRef, type MaybeRefOrGetter, type PropType, type Ref } from "vue";
 import { type ClientOptions } from "./client.ts";
 import { type Brua, type BruaOptions } from "./brua.ts";
-import type { AssetResponse } from "./types.ts";
+import type { AssetResponse, BruaImageError } from "./types.ts";
 export declare const bruaKey: InjectionKey<Brua>;
 /** Where the app's assets are read from by id: call once in the root component, then <BruaPicture id="…"> anywhere below. */
 export declare function provideBrua(options: Brua | BruaOptions): Brua;
@@ -10,10 +10,19 @@ export declare function provideBrua(options: Brua | BruaOptions): Brua;
  * undefined until it has loaded, and when nothing is released under the id. A server render shows the fallback.
  */
 export declare function useBruaAsset(id: MaybeRefOrGetter<string | undefined>, brua?: Brua): Ref<AssetResponse | undefined>;
+/**
+ * The asset's current release for an id, as useBruaAsset gives it, or the error when there is none: not released, or
+ * the edge can't be reached with no release known. Both undefined while it loads.
+ */
+export declare function useBruaAssetState(id: MaybeRefOrGetter<string | undefined>, brua?: Brua): Ref<{
+    asset?: AssetResponse;
+    error?: BruaImageError;
+}>;
 /**
  * The asset as a picture element (SPEC.md 7.2): the browser picks the format, density and color scheme,
  * and follows dark mode live. Animations show their still. Attributes such as class go on the img.
- * The default slot shows until an id has loaded, and when nothing is released under it.
+ * The default slot shows until an id has loaded; the error slot, given the reason as `error`, when there is no picture:
+ * nothing released, the edge unreachable, or the file failed. Without an error slot the default one shows then.
  */
 export declare const BruaPicture: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** The asset as your backend embedded it: a snapshot of one release. */
@@ -45,6 +54,16 @@ export declare const BruaPicture: import("vue").DefineComponent<import("vue").Ex
         type: PropType<"light" | "dark">;
         required: false;
     };
+    /** "contain" or "cover" to override the asset's fit, or "none" to leave the fit to the page's CSS. */
+    objectFit: {
+        type: PropType<"contain" | "cover" | "none">;
+        required: false;
+    };
+    /** Where the img sits in its box, as "x% y%", instead of the asset's position. */
+    objectPosition: {
+        type: StringConstructor;
+        required: false;
+    };
 }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
     [key: string]: any;
 }> | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
@@ -79,6 +98,16 @@ export declare const BruaPicture: import("vue").DefineComponent<import("vue").Ex
         type: PropType<"light" | "dark">;
         required: false;
     };
+    /** "contain" or "cover" to override the asset's fit, or "none" to leave the fit to the page's CSS. */
+    objectFit: {
+        type: PropType<"contain" | "cover" | "none">;
+        required: false;
+    };
+    /** Where the img sits in its box, as "x% y%", instead of the asset's position. */
+    objectPosition: {
+        type: StringConstructor;
+        required: false;
+    };
 }>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 /**
  * One variant URL for the asset, chosen for this browser and kept current as its appearance, motion setting

package/dist/vue.js

@@ -1,9 +1,9 @@
 // Brua for Vue 3: provideBrua, <BruaPicture>, useBruaAsset and useBruaUrl. Import from "@meginhufr/brua-web/vue".
 import { computed, defineComponent, h, inject, onBeforeUnmount, onMounted, provide, ref, toValue, unref, watchEffect, } from "vue";
-import { pictureModel } from "./picture.js";
+import { fillStyle, pictureModel } from "./picture.js";
 import { selectUrl } from "./select.js";
 import { defaultClientState, watchClientState } from "./client.js";
-import { createBrua } from "./brua.js";
+import { assetOrError, createBrua } from "./brua.js";
 export const bruaKey = Symbol("brua");
 /** Where the app's assets are read from by id: call once in the root component, then <BruaPicture id="…"> anywhere below. */
 export function provideBrua(options) {
@@ -16,28 +16,37 @@ export function provideBrua(options) {
  * undefined until it has loaded, and when nothing is released under the id. A server render shows the fallback.
  */
 export function useBruaAsset(id, brua) {
+    const state = useBruaAssetState(id, brua);
+    return computed(() => state.value.asset);
+}
+/**
+ * The asset's current release for an id, as useBruaAsset gives it, or the error when there is none: not released, or
+ * the edge can't be reached with no release known. Both undefined while it loads.
+ */
+export function useBruaAssetState(id, brua) {
     const client = brua ?? inject(bruaKey, undefined);
-    const asset = ref();
+    const state = ref({});
     watchEffect((onCleanup) => {
         const wanted = toValue(id);
         if (wanted === undefined) {
-            asset.value = undefined;
+            state.value = {};
             return;
         }
         if (!client)
             throw new Error("useBruaAsset needs provideBrua() in a parent, or a Brua passed in.");
         let live = true;
         onCleanup(() => { live = false; });
-        asset.value = client.cachedAsset(wanted);
-        client.asset(wanted).then((loaded) => { if (live)
-            asset.value = loaded; }, () => { });
+        state.value = { asset: client.cachedAsset(wanted) };
+        assetOrError(client, wanted).then((read) => { if (live)
+            state.value = read; });
     });
-    return asset;
+    return state;
 }
 /**
  * The asset as a picture element (SPEC.md 7.2): the browser picks the format, density and color scheme,
  * and follows dark mode live. Animations show their still. Attributes such as class go on the img.
- * The default slot shows until an id has loaded, and when nothing is released under it.
+ * The default slot shows until an id has loaded; the error slot, given the reason as `error`, when there is no picture:
+ * nothing released, the edge unreachable, or the file failed. Without an error slot the default one shows then.
  */
 export const BruaPicture = defineComponent({
     name: "BruaPicture",
@@ -54,14 +63,25 @@ export const BruaPicture = defineComponent({
         loading: { type: String, required: false },
         /** "light" or "dark" to show that scheme's files only, for apps that switch themes themselves. */
         colorScheme: { type: String, required: false },
+        /** "contain" or "cover" to override the asset's fit, or "none" to leave the fit to the page's CSS. */
+        objectFit: { type: String, required: false },
+        /** Where the img sits in its box, as "x% y%", instead of the asset's position. */
+        objectPosition: { type: String, required: false },
     },
     setup(props, { attrs, slots }) {
-        const fetched = useBruaAsset(() => (props.asset ? undefined : props.id), props.brua);
+        const fetched = useBruaAssetState(() => (props.asset ? undefined : props.id), props.brua);
+        const failed = ref();
+        const failure = (error) => (slots.error ?? slots.default)?.({ error }) ?? null;
         return () => {
-            const asset = props.asset ?? fetched.value;
+            const asset = props.asset ?? fetched.value.asset;
             if (!asset)
-                return slots.default?.() ?? null;
-            const { sources, img } = pictureModel(asset, { sizes: props.sizes, loading: props.loading, colorScheme: props.colorScheme });
+                return fetched.value.error ? failure(fetched.value.error) : slots.default?.() ?? null;
+            const { sources, img } = pictureModel(asset, {
+                sizes: props.sizes, loading: props.loading, colorScheme: props.colorScheme, objectFit: props.objectFit, objectPosition: props.objectPosition,
+            });
+            // The img's own error event: the file failed. Another file (a merge, another size) tries again.
+            if (failed.value === img.src)
+                return failure({ reason: "file", url: img.src });
             return h("picture", [
                 ...sources.map((s) => h("source", { key: `${s.type}${s.media ?? ""}`, type: s.type, media: s.media, srcset: s.srcset, sizes: s.sizes })),
                 h("img", {
@@ -75,6 +95,9 @@ export const BruaPicture = defineComponent({
                     lang: img.lang,
                     loading: img.loading,
                     decoding: img.decoding,
+                    // The fill first, so a style the page gives the component still wins.
+                    style: [fillStyle(img), attrs.style],
+                    onError: () => { failed.value = img.src; },
                 }),
             ]);
         };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@meginhufr/brua-web",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Brua for the web: AssetResponse types, the variant selection rule, <picture> rendering, and components for React, Vue and Svelte.",
   "author": "Meginhufr AS <hello@brua.dev> (https://brua.dev)",
   "license": "MIT",
   "homepage": "https://brua.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Meginhufr/brua-web.git"
+    "url": "git+https://github.com/Meginhufr/brua-web.git"
   },
   "type": "module",
   "sideEffects": false,