@meginhufr/brua-web 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meginhufr AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,7 +10,7 @@ Your backend passes asset ids on, and the page reads each asset's current releas
 
 ## From an id
 
-Configure once where your organization's assets live, then render by id. The asset is fetched from `{base}/{id}.json` with no key, reused for a minute (the edge's own lifetime) by everyone who asks, and a merge in Brua reaches the page within that minute with no deploy of yours.
+Configure once where your organization's assets live, then render by id. The asset is fetched from `{base}/{id}.json` with no key, and remembered by everyone who asks: answered from memory for the edge's minute, read again after that, and kept when the edge can't be reached. A merge in Brua reaches the page within that minute with no deploy of yours; `brua.cachedAsset(id)` gives the last release read at once, and `brua.prefetch(ids)` reads a list's ids before it renders.
 
 ```ts
 import { createBrua } from "@meginhufr/brua-web";

package/dist/BruaPicture.svelte

@@ -1,20 +1,22 @@
 <!-- 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 children show 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, and when nothing is released under the id. -->
 <script>
   import { getContext } from "svelte";
   import { pictureModel } from "./picture.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();
-  let fetched = $state();
+  // 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));
 
   $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;
-    brua.asset(id).then((loaded) => { if (live) fetched = loaded; });
+    fetched = brua.cachedAsset(id);
+    brua.asset(id).then((loaded) => { if (live) fetched = loaded; }, () => {});
     return () => { live = false; };
   });
 

package/dist/brua.d.ts

@@ -2,18 +2,29 @@ import type { AssetResponse } from "./types.ts";
 export interface BruaOptions {
     /** The organization's asset prefix on the edge, such as https://cdn.brua.dev/assets/{org}. */
     base: string;
-    /** The language for alt text and language-specific files; left out, the browser's Accept-Language decides. */
+    /** The language for alt text and language-specific files; left out, the browser's languages decide. */
     lang?: string;
-    /** How long a fetched asset is reused before it is asked for again, in milliseconds: the edge's own minute by default. */
+    /** How long a fetched asset is reused before it is asked for again, in milliseconds; by default the edge's max-age. */
     maxAge?: number;
     /** The fetch to use; the global one by default. */
     fetch?: typeof fetch;
 }
-/** Assets by id from the edge, with no key and no backend: each id costs one small request a minute at most. */
+/**
+ * Assets by id from the edge, with no key and no backend. Every release read is remembered: answered from memory for
+ * the edge's minute, asked for again after that, and kept when the edge can't be reached, so a merge lands within
+ * the minute and a page that loses its connection keeps its images.
+ */
 export interface Brua {
     /** The JSON URL of the asset's current release. */
     url(id: string): string;
-    /** The asset's current release, or undefined when the id is unknown or nothing is released. */
+    /**
+     * The asset's current release, or undefined when the id is unknown or nothing is released. Reads of one id at the
+     * same time share a request. Rejects only when the edge can't be reached and no release of the id is known.
+     */
     asset(id: string): Promise<AssetResponse | undefined>;
+    /** The last release of the id this Brua has read, however old, or undefined: for a component's first render. */
+    cachedAsset(id: string): AssetResponse | undefined;
+    /** Reads these ids at the same time, so a list's pictures render at once when it appears. */
+    prefetch(ids: string[]): Promise<void>;
 }
 export declare function createBrua(options: BruaOptions): Brua;

package/dist/brua.js

@@ -1,31 +1,60 @@
+/** "nb-NO, en;q=0.9": the browser's languages in order, with falling quality values, as the edge reads ?lang=. */
+function acceptLanguage(languages) {
+    return languages.slice(0, 5).map((language, index) => (index === 0 ? language : `${language};q=${(1 - index * 0.1).toFixed(1)}`)).join(", ");
+}
+/** The edge's max-age in milliseconds, or undefined when the response doesn't say. */
+function maxAgeOf(response) {
+    const match = /(?:^|,)\s*max-age\s*=\s*(\d+)/i.exec(response.headers.get("Cache-Control") ?? "");
+    return match ? Number(match[1]) * 1000 : undefined;
+}
 export function createBrua(options) {
     const base = options.base.replace(/\/+$/, "");
-    const maxAge = options.maxAge ?? 60_000;
-    const query = options.lang ? `?lang=${encodeURIComponent(options.lang)}` : "";
-    const held = new Map();
-    const url = (id) => `${base}/${encodeURIComponent(id)}.json${query}`;
-    return {
+    const entries = new Map();
+    const reads = new Map();
+    // Without a language, the browser's languages go in the query (in a browser only, not on a server), so each has
+    // its own entry here and in the HTTP cache, the same as the other SDKs.
+    const languages = () => options.lang ?? (typeof window !== "undefined" && typeof navigator !== "undefined" ? acceptLanguage(navigator.languages ?? []) : "");
+    const url = (id) => {
+        const lang = languages();
+        return `${base}/${encodeURIComponent(id)}.json${lang ? `?lang=${encodeURIComponent(lang)}` : ""}`;
+    };
+    const read = async (id, at) => {
+        const response = await (options.fetch ?? fetch)(at);
+        const freshFor = options.maxAge ?? maxAgeOf(response) ?? 60_000;
+        if (response.status === 404)
+            return { asset: undefined, freshUntil: Date.now() + freshFor };
+        if (!response.ok)
+            throw new Error(`Brua: ${id} answered ${response.status}`);
+        return { asset: (await response.json()), freshUntil: Date.now() + freshFor };
+    };
+    const brua = {
         url,
-        asset(id) {
-            const now = Date.now();
-            const have = held.get(id);
-            if (have && now - have.at < maxAge)
-                return have.result;
-            const request = options.fetch ?? fetch;
-            const result = request(url(id)).then(async (response) => {
-                if (response.status === 404)
-                    return undefined;
-                if (!response.ok)
-                    throw new Error(`Brua: ${id} answered ${response.status}`);
-                return (await response.json());
-            });
-            held.set(id, { at: now, result });
-            // A failure is asked again next time, not remembered for a minute.
-            result.catch(() => {
-                if (held.get(id)?.result === result)
-                    held.delete(id);
-            });
-            return result;
+        async asset(id) {
+            const at = url(id);
+            const known = entries.get(at);
+            if (known && Date.now() < known.freshUntil)
+                return known.asset;
+            let running = reads.get(at);
+            if (!running) {
+                running = read(id, at).then((entry) => { entries.set(at, entry); return entry; }).finally(() => reads.delete(at));
+                reads.set(at, running);
+            }
+            try {
+                return (await running).asset;
+            }
+            catch (error) {
+                const kept = entries.get(at);
+                if (kept)
+                    return kept.asset;
+                throw error;
+            }
+        },
+        cachedAsset(id) {
+            return entries.get(url(id))?.asset;
+        },
+        async prefetch(ids) {
+            await Promise.all([...new Set(ids)].map((id) => brua.asset(id).catch(() => undefined)));
         },
     };
+    return brua;
 }

package/dist/react.d.ts

@@ -11,8 +11,8 @@ export type BruaProviderProps = {
 /** Where the app's assets are read from by id: wrap the app once, then <BruaPicture id="…"> anywhere below. */
 export declare function BruaProvider(props: BruaProviderProps): ReactElement;
 /**
- * The asset's current release for an id, from the provider's Brua or the one given: undefined until it has loaded,
- * and when nothing is released under the id. Loads only in the browser; a server render shows the fallback.
+ * The asset's current release for an id, from the provider's Brua or the one given: the last release it read at once, else
+ * 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;
 export interface BruaPictureProps extends PictureOptions {

package/dist/react.js

@@ -13,21 +13,23 @@ export function BruaProvider(props) {
     return createElement(BruaContext.Provider, { value: brua }, props.children);
 }
 /**
- * The asset's current release for an id, from the provider's Brua or the one given: undefined until it has loaded,
- * and when nothing is released under the id. Loads only in the browser; a server render shows the fallback.
+ * The asset's current release for an id, from the provider's Brua or the one given: the last release it read at once, else
+ * 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) {
     const fromContext = useContext(BruaContext);
     const client = brua ?? fromContext;
-    const [asset, setAsset] = useState();
+    // 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)));
     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); });
+            setAsset(loaded); }, () => { });
         return () => { live = false; };
     }, [client, id]);
     return id === undefined ? undefined : asset;

package/dist/svelte.d.ts

@@ -9,8 +9,8 @@ export declare const bruaContext = "brua";
 export declare function setBrua(options: Brua | BruaOptions): Brua;
 export declare function getBrua(): Brua | undefined;
 /**
- * A store of the asset's current release for an id: undefined until it has loaded, and when nothing is released
- * under the id. Reads through the context's Brua unless one is given; call it during component setup.
+ * A store of the asset's current release for an id: the last release the Brua read at once, else undefined until it
+ * has loaded, and when nothing is released under the id. Reads through the context's Brua unless one is given; call it during component setup.
  */
 export declare function bruaAsset(id: string, brua?: Brua | undefined): Readable<AssetResponse | undefined>;
 /**

package/dist/svelte.js

@@ -17,16 +17,16 @@ export function getBrua() {
     return getContext(bruaContext);
 }
 /**
- * A store of the asset's current release for an id: undefined until it has loaded, and when nothing is released
- * under the id. Reads through the context's Brua unless one is given; call it during component setup.
+ * A store of the asset's current release for an id: the last release the Brua read at once, else undefined until it
+ * has loaded, and when nothing is released under the id. Reads through the context's Brua unless one is given; call it during component setup.
  */
 export function bruaAsset(id, brua = getBrua()) {
     if (!brua)
         throw new Error("bruaAsset needs setBrua() in a parent, or a Brua passed in.");
-    return readable(undefined, (set) => {
+    return readable(brua.cachedAsset(id), (set) => {
         let live = true;
         brua.asset(id).then((loaded) => { if (live)
-            set(loaded); });
+            set(loaded); }, () => { });
         return () => { live = false; };
     });
 }

package/dist/vue.d.ts

@@ -6,8 +6,8 @@ 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;
 /**
- * The asset's current release for an id, from the provided Brua or the one given: undefined until it has loaded,
- * and when nothing is released under the id. A server render shows the fallback.
+ * The asset's current release for an id, from the provided Brua or the one given: the last release it read at once, else
+ * 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>;
 /**

package/dist/vue.js

@@ -12,8 +12,8 @@ export function provideBrua(options) {
     return brua;
 }
 /**
- * The asset's current release for an id, from the provided Brua or the one given: undefined until it has loaded,
- * and when nothing is released under the id. A server render shows the fallback.
+ * The asset's current release for an id, from the provided Brua or the one given: the last release it read at once, else
+ * 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 client = brua ?? inject(bruaKey, undefined);
@@ -28,8 +28,9 @@ export function useBruaAsset(id, brua) {
             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; });
+            asset.value = loaded; }, () => { });
     });
     return asset;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meginhufr/brua-web",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -36,7 +36,7 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/BruaPicture.svelte dist/",
-    "test": "node --test test/"
+    "test": "node --test \"test/**/*.test.ts\""
   },
   "publishConfig": {
     "access": "public",