@sumaq/site-kit 0.4.1 → 0.5.0

package/README.md

@@ -69,13 +69,15 @@ Nothing serves `/media/portrait-a3f9c1d2.webp`. `Media` looks the key up in a bu
 
 | `src` | What happens |
 |---|---|
-| `/media/x.webp` present in `./media/` | `<Image>` with `srcset` at 640/960/1280/2000 (clamped to the original) plus the manifest's LQIP as a background |
+| `/media/x.webp` present in `./media/` | `<Image>` with `srcset` at 640/960/1280/1600/1920 (clamped to the original) plus the manifest's LQIP as a background |
 | `/media/x.svg` | `<img>` with the emitted URL — imported SVGs become components in Astro 7, and this keeps them images |
 | `https://…` or any `public/` path | plain `<img>`, untouched |
 | an `ImageMetadata` import | `<Image>`, as before |
 | empty | nothing — unless `fallback` is set |
 
-`media/manifest.json`, written by the CMS, carries `{ alt, width, height, lqip }` per key. A site without one simply renders without LQIP.
+`media/manifest.json`, written by the CMS, carries `{ alt, width, height, lqip, alpha }` per key. A site without one simply renders without LQIP.
+
+The LQIP is painted as the `<img>`'s own background and **removed as soon as the real image loads**. It has to be: the blur sits behind the picture, so anything the foreground does not cover keeps showing it — through the transparent pixels of a cut-out, or beside the picture when the CSS box and the file disagree on aspect ratio, where it reads as a shadow under the subject. An image the manifest marks `alpha: true` gets no LQIP at all.
 
 ### Placeholder
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sumaq/site-kit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Layouts, blocks, helpers and Astro config factory for Sumaq client sites.",
   "license": "UNLICENSED",
   "author": "elingan",

package/src/components/Media.astro

@@ -105,13 +105,30 @@ const asset: ImageMetadata | null = usePlaceholder
 /** Content images get the full srcset; a hand-passed import keeps its own props. */
 const assetWidths = widths ?? (localAsset || usePlaceholder ? DEFAULT_WIDTHS : undefined);
 
-/** LQIP from the manifest, shown behind the image while it loads. */
-const lqipStyle = meta?.lqip
-	? `background-image:url(${meta.lqip});background-size:cover;background-position:center`
+/**
+ * LQIP from the manifest, painted as the image's own background while it loads
+ * and dropped by the inline script below once it has.
+ *
+ * It has to go once: the blur sits *behind* the picture, so on anything the
+ * foreground does not cover completely it stays visible for the life of the
+ * page — through the transparent pixels of a cut-out, and beside the picture
+ * whenever the CSS box and the file disagree on aspect ratio (there
+ * `background-position` and `object-position` drift apart and the leftover blur
+ * reads as a shadow under the subject).
+ *
+ * An image with an alpha channel gets no LQIP at all: for a cut-out the blurred
+ * rectangle is wrong even while it loads, since the real image will never fill
+ * that shape.
+ */
+const showLqip = Boolean(meta?.lqip) && meta?.alpha !== true;
+const lqipStyle = showLqip
+	? `background-image:url(${meta!.lqip});background-size:cover;background-position:center;background-repeat:no-repeat`
 	: undefined;
 const composedStyle = [style, usePlaceholder ? undefined : lqipStyle]
 	.filter(Boolean)
 	.join(";") || undefined;
+/** Marks the images the cleanup script owns. */
+const lqipFlag = !usePlaceholder && showLqip ? "" : undefined;
 
 /**
  * An SVG gets its dimensions written out by hand (it skips `<Image>`), so a
@@ -145,6 +162,7 @@ const passthrough = !asset && !missing;
 				decoding={decoding}
 				fetchpriority={fetchpriority}
 				data-cms-src={cms}
+				data-lqip={lqipFlag}
 			/>
 		) : (
 			<Image
@@ -161,6 +179,7 @@ const passthrough = !asset && !missing;
 				decoding={decoding}
 				fetchpriority={fetchpriority}
 				data-cms-src={cms}
+				data-lqip={lqipFlag}
 			/>
 		))
 }
@@ -179,6 +198,40 @@ const passthrough = !asset && !missing;
 			decoding={decoding}
 			fetchpriority={fetchpriority}
 			data-cms-src={cms}
+			data-lqip={lqipFlag}
 		/>
 	)
 }
+
+<script>
+	/**
+	 * Removes the LQIP once the real image is on screen — see `lqipStyle` above
+	 * for why leaving it in place is not harmless.
+	 *
+	 * `astro:page-load` fires on the first load and after every navigation made
+	 * by `<ClientRouter />`, which does not re-execute this module on its own.
+	 * Clearing the attribute makes a second pass over the same image a no-op.
+	 */
+	const clear = (img) => {
+		img.style.backgroundImage = "none";
+		img.removeAttribute("data-lqip");
+	};
+
+	const settle = (img) => {
+		if (img.complete && img.naturalWidth > 0) {
+			clear(img);
+			return;
+		}
+		// One frame later: the browser has painted the decoded image by then, so
+		// dropping the background underneath it is invisible.
+		img.addEventListener("load", () => requestAnimationFrame(() => clear(img)), { once: true });
+		img.addEventListener("error", () => clear(img), { once: true });
+	};
+
+	const initLqip = () => {
+		for (const img of document.querySelectorAll("img[data-lqip]")) settle(img);
+	};
+
+	initLqip();
+	document.addEventListener("astro:page-load", initLqip);
+</script>

package/src/lib/media.ts

@@ -20,8 +20,16 @@
  */
 import type { ImageMetadata } from "astro";
 
-/** Widths the CMS master (2000px) is resized to. Astro clamps to the original. */
-export const DEFAULT_WIDTHS = [640, 960, 1280, 2000];
+/**
+ * Widths the CMS master (2000px) is resized to. Astro clamps every entry to the
+ * original, so a small upload still emits only the sizes it really has.
+ *
+ * The steps are ~25% apart on purpose: below that a browser saves too little
+ * bandwidth to pay for one more file in the build. 640 covers a phone at 1x and
+ * a 320px column at 2x, 960 a 480px column at 2x, 1280/1600 laptops, and 1920
+ * the full-bleed desktop case.
+ */
+export const DEFAULT_WIDTHS = [640, 960, 1280, 1600, 1920];
 
 /** The prefix that marks a string as a local key instead of a URL. */
 export const MEDIA_PREFIX = "/media/";
@@ -33,6 +41,12 @@ export interface MediaManifestEntry {
 	height?: number;
 	/** Base64 data URI shown while the real image loads. */
 	lqip?: string;
+	/**
+	 * The image is see-through. A cut-out gets no LQIP: the blur is painted
+	 * *behind* the picture, so transparent pixels would show it instead of the
+	 * page. Absent on entries written before the flag existed.
+	 */
+	alpha?: boolean;
 }
 
 /**

package/src/tokens/class-inventory.json

@@ -1,6 +1,6 @@
 {
 	"$comment": "Generated by scripts/build-class-inventory.mjs — do not edit by hand. `sq-*` is the kit's namespace; site-local components must use their own prefix.",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"classes": [
 		"sq-about",
 		"sq-about__body",