@cssints/placeholder 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+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

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @cssints/placeholder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Image placeholders for [cssints](../../README.md): `placeholder(path)` reads an image while the build runs and gives an
+`<image>` to paint until the real one loads, either a gradient of the image's colours laid out as the image is
+(unpic-placeholder's radial gradients) or the image's [ThumbHash](https://evanw.github.io/thumbhash/) as a tiny PNG data
+URL. It is one value member of `cssints/plugin` `scope()`, so it goes into `backgroundImage` (or `maskImage`). No runtime.
+
+```ts
+import { backgroundImage, cn, backgroundSize } from "cssints" with { type: "cssints" };
+import { placeholder } from "@cssints/placeholder" with { type: "cssints" };
+
+// placeholder(path, { mode? }): the path is relative to the working directory
+export const hero = backgroundImage(placeholder("src/hero.jpg"));
+export const card = cn(
+  backgroundImage(placeholder("src/card.png", { mode: "thumbhash" })),
+  backgroundSize("cover"),
+);
+```
+
+For a PNG of four quadrants (red, blue / green, white):
+
+```css
+/* mode "gradient" (the default): a 4 × 3 grid, a radial gradient per cell, brightest on top, over the average colour */
+._11mb38d {
+  background-image:
+    radial-gradient(at 67% 100%, #ffffff, transparent 50%),
+    radial-gradient(at 100% 100%, #ffffff, transparent 50%),
+    radial-gradient(at 67% 50%, #bcbcff, transparent 50%),
+    /* … one per cell, 12 in all … */ radial-gradient(at 100% 0, #0000ff, transparent 50%),
+    linear-gradient(#bc96bc, #bc96bc);
+}
+/* mode "thumbhash": the ThumbHash rendered, 16 px on the long side, about 0.5 kB */
+._179cifn {
+  background-image: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAM…");
+}
+```
+
+## Formats
+
+JPEG (baseline and progressive, through [jpeg-js](https://github.com/jpeg-js/jpeg-js)) and PNG (every colour type and bit
+depth, through [pngjs](https://github.com/pngjs/pngjs)), both plain JavaScript: nothing to compile, no native binary
+(sharp is not used). The format is read from the file's first bytes, not its name. WebP, AVIF, GIF and SVG are build
+errors that name the format (`cssints: placeholder: src/hero.webp: a WebP image: JPEG and PNG are read`): give a JPEG or
+PNG copy of the image (it can be small; only its colours are read).
+
+## Rules
+
+- **Arguments.** `path` is a string, relative to the working directory (`process.cwd()`, the project root under Vite),
+  as the `fs` provider of `@cssints/icons` reads it. `mode` is `"gradient"` (the default) or `"thumbhash"`. Both are
+  checked in the types and at build time.
+- **`gradient`** averages the image to a grid of 4 × 3 cells (3 × 4 for a portrait image), in linear light and weighted
+  by alpha, so a transparent part adds no colour and a cell that straddles red and green is the light's mix, not a muddy
+  sRGB average. Each cell is a `radial-gradient(at x y, colour, transparent 50%)` at its place in the image (corners at
+  `0` and `100%`), sorted by luminance with the brightest on top (as unpic-placeholder does), over one
+  `linear-gradient()` of the whole image's average colour that fills what the gradients leave. A cell that is not opaque
+  is `#rrggbbaa`. The value is a list of 13 images, about 0.7 kB.
+- **`thumbhash`** encodes the image (averaged to at most 100 px a side first) with ThumbHash, renders the hash, averages
+  that to 16 px on the long side and writes it as a deflated PNG: about 0.5 kB, where ThumbHash's own data URL (32 px,
+  uncompressed) is about 5 kB. The browser's smooth upscaling does the blur. It keeps the aspect ratio, so pair it with
+  `backgroundSize("cover")` or `"100% 100%"`.
+- **Deterministic.** The same file gives the same CSS on every build. Results are cached for the process by the SHA-256
+  of the file's content and the mode, so an image used from many modules is decoded once.
+- **Errors**, at the call: a file that cannot be read (`cssints: placeholder: cannot read src/nope.png (paths are
+relative to /app)`), a format it does not read (above), a file that does not decode (`cssints: placeholder:
+src/broken.png: …`, the decoder's message), a mode outside the grammar (`placeholder(2).mode: unexpected "blurhash"
+…`), and a placeholder where an image does not go (`css.color(placeholder(…))`, an error in the types and at build
+  time).
+
+## Limits
+
+- In dev, an edited image updates the CSS of the modules that use it (`dependsOn` of `cssints/plugin`); a missing image
+  that you add after the build error needs an edit of the module or a reload.
+- The `gradient` value is a list of images, so it fits a property that takes a list (`background-image`, `mask-image`);
+  a property that takes one `<image>` (`list-style-image`, `border-image-source`) rejects it at build time: use
+  `thumbhash` there.
+- No WebP or AVIF decoder (a WASM one would add a few hundred kB to the build); the grid size and the thumbhash size are
+  fixed; no blurhash mode.
+- The image is decoded whole: a very large JPEG (tens of megapixels) costs its pixels in memory once per build.
+
+```bash
+cd packages/placeholder && bun run test        # colour extraction on synthetic pixels, fixtures through the engine (output, errors)
+cd packages/placeholder && bun run typecheck   # and the type test, test/types/placeholder.ts
+```
+
+## Credits
+
+The gradient layout follows [unpic-placeholder](https://github.com/ascorbic/unpic-placeholder) (MIT, Matt Kane).
+The thumbhash mode uses [thumbhash](https://github.com/evanw/thumbhash) (MIT, Evan Wallace), [jpeg-js](https://github.com/jpeg-js/jpeg-js)
+(BSD-3-Clause) and [pngjs](https://github.com/pngjs/pngjs) (MIT), dependencies. No code is copied.

package/dist/index.d.mts

@@ -0,0 +1,21 @@
+import { CSSImageValue } from "cssints";
+//#region src/index.d.ts
+/** How the placeholder is drawn: a gradient of the colours (the default), or the thumbhash as a PNG data URL. */
+export type Mode = "gradient" | "thumbhash";
+declare const placeholders: import("cssints/plugin").Scope<"placeholder", {
+  readonly placeholder: {
+    args: readonly [import("cssints/plugin").Typed<string>, {
+      readonly "mode?": "gradient | thumbhash";
+    }];
+    label?: undefined;
+    value(args: never): CSSImageValue;
+  };
+}>;
+/**
+ * `placeholder(path, { mode? })`: a placeholder of the image at `path` (relative to the working directory), read at build
+ * time. `mode: "gradient"` (the default) is a list of radial gradients of the image's colours, each where its part of the
+ * image is; `mode: "thumbhash"` is the image's thumbhash as a tiny PNG `url()`. An `<image>` for `backgroundImage`. JPEG
+ * and PNG; another format or a missing file is a build error at the call.
+ */
+export declare const placeholder: ReturnType<typeof placeholders.export>["placeholder"];
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { CSSImageValue } from "cssints";
+import { arg, dependsOn, fn, scope } from "cssints/plugin";
+import jpeg from "jpeg-js";
+import { PNG } from "pngjs";
+import { rgbaToThumbHash, thumbHashToRGBA } from "thumbhash";
+//#region src/pixels.ts
+const starts = (bytes, sig, at = 0) => sig.every((b, i) => bytes[at + i] === b);
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+const kind = (bytes) => starts(bytes, [
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+]) ? "png" : starts(bytes, [
+	255,
+	216,
+	255
+]) ? "jpeg" : starts(bytes, ascii("RIFF")) && starts(bytes, ascii("WEBP"), 8) ? "a WebP image" : starts(bytes, ascii("ftyp"), 4) && /^(avif|avis)$/.test(String.fromCharCode(...bytes.slice(8, 12))) ? "an AVIF image" : starts(bytes, ascii("GIF8")) ? "a GIF image" : "not an image it knows";
+/**
+* The RGBA pixels of a JPEG or PNG; anything else throws, naming what it is.
+* @param {Uint8Array} bytes the file
+* @returns {Pixels} its pixels
+*/
+const decode = (bytes) => {
+	const k = kind(bytes);
+	if (k === "png") {
+		const png = PNG.sync.read(Buffer.from(bytes));
+		return {
+			width: png.width,
+			height: png.height,
+			data: png.data
+		};
+	}
+	if (k === "jpeg") {
+		const img = jpeg.decode(bytes, {
+			useTArray: true,
+			formatAsRGBA: true
+		});
+		return {
+			width: img.width,
+			height: img.height,
+			data: img.data
+		};
+	}
+	throw new Error(`${k}: JPEG and PNG are read`);
+};
+const LINEAR = Array.from({ length: 256 }, (_, i) => {
+	const c = i / 255;
+	return c <= .04045 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4;
+});
+const toSrgb = (l) => {
+	const c = l <= .0031308 ? l * 12.92 : 1.055 * l ** (1 / 2.4) - .055;
+	return Math.round(Math.min(1, Math.max(0, c)) * 255);
+};
+const span = (i, n, size) => {
+	const from = Math.min(size - 1, Math.floor(i * size / n));
+	return [from, Math.max(from + 1, Math.floor((i + 1) * size / n))];
+};
+/**
+* `img` averaged to `w` × `h` (a box filter over the pixels each cell covers), in linear light and weighted by alpha, so
+* a transparent pixel gives no colour.
+* @param {Pixels} img the image
+* @param {number} w the width of the result
+* @param {number} h the height of the result
+* @returns {Pixels} `w` × `h` cells
+*/
+const downsample = (img, w, h) => {
+	const data = new Uint8Array(w * h * 4);
+	for (let cy = 0; cy < h; cy++) {
+		const [y0, y1] = span(cy, h, img.height);
+		for (let cx = 0; cx < w; cx++) {
+			const [x0, x1] = span(cx, w, img.width);
+			let [r, g, b, a] = [
+				0,
+				0,
+				0,
+				0
+			];
+			for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) {
+				const i = (y * img.width + x) * 4;
+				const alpha = img.data[i + 3] / 255;
+				r += LINEAR[img.data[i]] * alpha;
+				g += LINEAR[img.data[i + 1]] * alpha;
+				b += LINEAR[img.data[i + 2]] * alpha;
+				a += alpha;
+			}
+			const c = (cy * w + cx) * 4;
+			if (a) data.set([
+				toSrgb(r / a),
+				toSrgb(g / a),
+				toSrgb(b / a)
+			], c);
+			data[c + 3] = Math.round(a / ((y1 - y0) * (x1 - x0)) * 255);
+		}
+	}
+	return {
+		width: w,
+		height: h,
+		data
+	};
+};
+const hex = (d, i) => `#${[...d.subarray(i, i + (d[i + 3] === 255 ? 3 : 4))].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+const pct = (n) => n ? `${Math.round(n * 100)}%` : "0";
+/**
+* unpic-placeholder's gradient: a radial gradient per cell of a `columns` × `rows` grid, at the cell's place and fading out
+* at 50%, brightest first (on top), over the image's average colour.
+* @param {Pixels} img the image
+* @param {number} columns the cells across
+* @param {number} rows the cells down
+* @returns {string} the layers, comma-separated (a `background-image` value)
+*/
+const gradients = (img, columns, rows) => {
+	const { data } = downsample(img, columns, rows);
+	const cells = Array.from({ length: columns * rows }, (_, c) => c);
+	const luma = (c) => .299 * data[c * 4] + .587 * data[c * 4 + 1] + .114 * data[c * 4 + 2];
+	cells.sort((a, b) => luma(b) - luma(a));
+	const layers = cells.map((c) => `radial-gradient(at ${pct(c % columns / (columns - 1))} ${pct(Math.floor(c / columns) / (rows - 1))}, ${hex(data, c * 4)}, transparent 50%)`);
+	const average = hex(downsample(img, 1, 1).data, 0);
+	return [...layers, `linear-gradient(${average}, ${average})`].join(", ");
+};
+/**
+* The image's thumbhash (from a copy at most 100 px a side), rendered by thumbhash (32 px on the long side), averaged to
+* 16 px and written as a deflated PNG data URL: about 0.5 kB, where thumbhash's own `thumbHashToDataURL` (32 px, stored
+* uncompressed) is about 5 kB. The browser's smooth upscaling is the blur.
+* @param {Pixels} img the image
+* @returns {string} a `data:image/png;base64,…` URL
+*/
+const thumbhash = (img) => {
+	const fit = (p, side) => {
+		const scale = Math.min(1, side / Math.max(p.width, p.height));
+		return downsample(p, Math.max(1, Math.round(p.width * scale)), Math.max(1, Math.round(p.height * scale)));
+	};
+	const small = fit(img, 100);
+	const { w, h, rgba } = thumbHashToRGBA(rgbaToThumbHash(small.width, small.height, small.data));
+	const out = fit({
+		width: w,
+		height: h,
+		data: rgba
+	}, 16);
+	const png = new PNG({
+		width: out.width,
+		height: out.height
+	});
+	png.data = Buffer.from(out.data);
+	return `data:image/png;base64,${PNG.sync.write(png, { deflateLevel: 9 }).toString("base64")}`;
+};
+//#endregion
+//#region src/index.ts
+const g = globalThis;
+const fail = (message, cause) => {
+	throw new Error(`cssints: placeholder: ${message}`, { cause });
+};
+const compute = (path, mode) => {
+	let bytes;
+	dependsOn(path);
+	try {
+		bytes = readFileSync(resolve(path));
+	} catch (e) {
+		return fail(`cannot read ${path} (paths are relative to ${process.cwd()})`, e);
+	}
+	const key = `${createHash("sha256").update(bytes).digest("hex")} ${mode}`;
+	const cache = g.__cssintsPlaceholder ??= /* @__PURE__ */ new Map();
+	const hit = cache.get(key);
+	if (hit !== void 0) return hit;
+	let css;
+	try {
+		const img = decode(bytes);
+		const portrait = img.height > img.width;
+		css = mode === "thumbhash" ? `url("${thumbhash(img)}")` : gradients(img, portrait ? 3 : 4, portrait ? 4 : 3);
+	} catch (e) {
+		return fail(`${path}: ${e instanceof Error ? e.message : String(e)}`, e);
+	}
+	cache.set(key, css);
+	return css;
+};
+/**
+* `placeholder(path, { mode? })`: a placeholder of the image at `path` (relative to the working directory), read at build
+* time. `mode: "gradient"` (the default) is a list of radial gradients of the image's colours, each where its part of the
+* image is; `mode: "thumbhash"` is the image's thumbhash as a tiny PNG `url()`. An `<image>` for `backgroundImage`. JPEG
+* and PNG; another format or a missing file is a build error at the call.
+*/
+const placeholder = scope("placeholder", { placeholder: fn({
+	args: [arg(), { "mode?": "gradient | thumbhash" }],
+	value: ([path, { mode = "gradient" }]) => new CSSImageValue(compute(path, mode))
+}) }).export().placeholder;
+//#endregion
+export { placeholder };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@cssints/placeholder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Image placeholders for cssints: a gradient of the dominant colours, or a thumbhash data URL, read from the image at build time",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/placeholder"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "jpeg-js": "^0.4.4",
+    "pngjs": "^7.0.0",
+    "thumbhash": "^0.1.1"
+  },
+  "peerDependencies": {
+    "cssints": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}