@protobase/server 0.13.0 → 0.13.3

package/dist/check-views.js

@@ -1,6 +1,6 @@
 import { relatedErrors } from "./view-related.js";
 import { cardPhotosErrors } from "./view-card-photos.js";
-import { mapErrors } from "./view-map.js";
+import { mapDisplayErrors, mapErrors } from "./view-map.js";
 import { addressErrors, addressPlaceholders, appHrefError, displayFields, fieldRefsIn, hrefPlaceholders } from "@protobase/schema";
 //#region src/check-views.ts
 const linkFields = (run) => run?.kind !== "link" ? [] : "to" in run ? addressPlaceholders(run.to) : hrefPlaceholders(run.href);
@@ -62,7 +62,7 @@ const widgetErrors = (view, model, fieldTypes) => Object.entries(view.fields).fl
 * field the resource does not have, labels or colours values its enum does not have, shows a field with a field type of
 * `fieldTypes` (each with the storage types it shows) that does not show it,
 * has a related section or a cards display's photos that do not fit the resources, a map that cannot show the
-* record's position, or a link to an address the app does not have.
+* record's position or a map display that cannot find the records in its view, or a link to an address the app does not have.
 */
 const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 	const models = Object.fromEntries(registry.entries.map((entry) => [entry.name, entry.model]));
@@ -72,7 +72,7 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 		if (!model) return [];
 		const related = view.layout.flatMap((item) => item.kind === "related" ? relatedErrors(item, view.resource, models).map((error) => `related "${item.title}": ${error}`) : []);
 		const photos = (view.list?.displays ?? []).flatMap((display) => display.kind === "cards" && display.photos ? cardPhotosErrors(display.photos, view.resource, models).map((error) => `display "${display.name}" photos: ${error}`) : []);
-		const maps = view.layout.flatMap((item) => item.kind === "map" ? mapErrors(item, model).map((error) => `map "${item.title}": ${error}`) : []);
+		const maps = [...view.layout.flatMap((item) => item.kind === "map" ? mapErrors(item, model).map((error) => `map "${item.title}": ${error}`) : []), ...(view.list?.displays ?? []).flatMap((display) => display.kind === "map" ? mapDisplayErrors(display, model).map((error) => `display "${display.name}": ${error}`) : [])];
 		return [
 			...sensitiveErrors(view, model),
 			...unknownFieldErrors(view, model),

package/dist/files/attach.js

@@ -1,5 +1,5 @@
 import { badRequest } from "../problem.js";
-import { baseOf, parseUri } from "./uri.js";
+import { baseOf, parseUri, variantPaths } from "./uri.js";
 import { tenantScope } from "../tenant.js";
 import { readTicket } from "./ticket.js";
 //#region src/files/attach.ts
@@ -52,8 +52,8 @@ const attachFiles = async (access, values, current) => {
 	return result;
 };
 /**
-* Schedules the delete of every file a write took out of its row: a replaced or cleared value, or all of a hard-deleted
-* row's files, each due after its provider's retention. It runs inside the write transaction, before the commit: if
+* Schedules the delete of every file a write took out of its row, with its variants: a replaced or cleared value, or all
+* of a hard-deleted row's files, each due after its provider's retention. It runs inside the write transaction, before the commit: if
 * the write rolls back, the file is still referenced when the entry is due, and stays.
 */
 const scheduleRemovedFiles = async (access, operation, before, after) => {
@@ -68,10 +68,12 @@ const scheduleRemovedFiles = async (access, operation, before, after) => {
 		if (typeof next === "string" && baseOf(next) === baseOf(old)) return [];
 		const ref = parseUri(old);
 		if (!ref || !files.providers[ref.provider]) return [];
+		const variants = Object.values(variantPaths(ref));
 		return [{
 			provider: ref.provider,
 			path: ref.path,
-			due: new Date(now + files.retention(ref.provider))
+			due: new Date(now + files.retention(ref.provider)),
+			...variants.length > 0 && { variants }
 		}];
 	});
 	if (removed.length > 0) await files.schedule.add(removed);

package/dist/files/cleanup-runner.js

@@ -31,7 +31,8 @@ const referenced = async (db, columns, uris) => {
 /**
 * Handles every scheduled delete that is due: right before deleting, it checks that no declared file column holds the
 * file; one that is referenced again (a rolled-back write, a restore, a shared value) is kept and its entry dropped.
-* Uploads never attached are deleted here too, after their ticket expired. Running it twice at once is harmless.
+* A file's variants go with it and stay with it. Uploads never attached are deleted here too, after their ticket
+* expired. Running it twice at once is harmless.
 */
 const runCleanup = async ({ db, columns, providers, schedule, now = /* @__PURE__ */ new Date() }) => {
 	const deleted = /* @__PURE__ */ new Set();
@@ -43,7 +44,9 @@ const runCleanup = async ({ db, columns, providers, schedule, now = /* @__PURE__
 			const uri = `${entry.provider}:${entry.path}`;
 			if (inUse.has(uri)) kept.add(uri);
 			else if (!deleted.has(uri)) {
-				await providers[entry.provider].store.delete(entry.path);
+				const { store } = providers[entry.provider];
+				for (const variant of entry.variants ?? []) await store.delete(variant);
+				await store.delete(entry.path);
 				deleted.add(uri);
 			}
 			await schedule.done(entry);

package/dist/files/cleanup-schedule.d.ts

@@ -1,10 +1,11 @@
 import { FileProvider } from "./store.js";
 //#region src/files/cleanup-schedule.d.ts
-/** A file to delete once `due`, unless a row references it again by then. */
+/** A file to delete once `due`, unless a row references it again by then, with the paths of its image variants. */
 export type ScheduledDelete = {
   provider: string;
   path: string;
   due: Date;
+  variants?: string[];
 };
 export type CleanupEntry = ScheduledDelete & {
   id: string;
@@ -22,7 +23,8 @@ export type CleanupSchedule = {
 };
 /**
  * Scheduled deletes as a to-do folder in each provider's storage: one JSON object per delete in `.cleanup/`, named after
- * its due time (`.cleanup/2026-10-12T03-00-00Z-<uuid>.json`) and saying which provider and path to delete.
+ * its due time (`.cleanup/2026-10-12T03-00-00Z-<uuid>.json`) and saying which provider and path to delete, and the
+ * paths of the file's variants when it has them.
  */
 export declare const storageCleanupSchedule: (providers: Record<string, FileProvider>) => CleanupSchedule;
 //#endregion

package/dist/files/cleanup-schedule.js

@@ -2,10 +2,12 @@
 const cleanupFolder = ".cleanup/";
 const stamp = (date) => date.toISOString().slice(0, 19).replaceAll(":", "-") + "Z";
 const entryPattern = /^\.cleanup\/(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z)-[0-9a-f-]{36}\.json$/;
-const isScheduledDelete = (value) => typeof value === "object" && value !== null && typeof value.provider === "string" && typeof value.path === "string" && typeof value.due === "string";
+const isPathList = (value) => value === void 0 || Array.isArray(value) && value.every((path) => typeof path === "string");
+const isScheduledDelete = (value) => typeof value === "object" && value !== null && typeof value.provider === "string" && typeof value.path === "string" && typeof value.due === "string" && isPathList(value.variants);
 /**
 * Scheduled deletes as a to-do folder in each provider's storage: one JSON object per delete in `.cleanup/`, named after
-* its due time (`.cleanup/2026-10-12T03-00-00Z-<uuid>.json`) and saying which provider and path to delete.
+* its due time (`.cleanup/2026-10-12T03-00-00Z-<uuid>.json`) and saying which provider and path to delete, and the
+* paths of the file's variants when it has them.
 */
 const storageCleanupSchedule = (providers) => {
 	const storeOf = (provider) => {
@@ -15,11 +17,12 @@ const storageCleanupSchedule = (providers) => {
 	};
 	return {
 		add: async (deletes) => {
-			for (const { provider, path, due } of deletes) {
+			for (const { provider, path, due, variants } of deletes) {
 				const body = new Blob([JSON.stringify({
 					provider,
 					path,
-					due: due.toISOString()
+					due: due.toISOString(),
+					...variants?.length && { variants }
 				})]).stream();
 				await storeOf(provider).put(`${cleanupFolder}${stamp(due)}-${crypto.randomUUID()}.json`, body);
 			}
@@ -36,7 +39,8 @@ const storageCleanupSchedule = (providers) => {
 					id: object.path,
 					provider,
 					path: content.path,
-					due: new Date(content.due)
+					due: new Date(content.due),
+					...content.variants?.length && { variants: content.variants }
 				});
 			}
 			return entries;

package/dist/files/download.js

@@ -2,7 +2,7 @@ import { HttpProblem, forbidden, notFound } from "../problem.js";
 import { decodeKeyText } from "../key.js";
 import { downloadExpiry, readDownloadUrl } from "./download-url.js";
 import { contentDisposition, downloadName, servedType } from "./media-types.js";
-import { baseOf, isFilePath, parseUri, tenantSegment } from "./uri.js";
+import { isFilePath, parseUri, tenantSegment, variantPaths } from "./uri.js";
 import { fetchRecord } from "../records.js";
 import { readTransaction } from "../transactions.js";
 //#region src/files/download.ts
@@ -18,6 +18,11 @@ const rangeOf = (header, size) => {
 		end
 	} : false;
 };
+const heldFile = (value, provider, path) => {
+	const ref = typeof value === "string" ? parseUri(value) : void 0;
+	if (!ref || ref.provider !== provider) return void 0;
+	return ref.path === path || Object.values(variantPaths(ref)).includes(path) ? ref : void 0;
+};
 const grantedName = async (deps, provider, path, query) => {
 	const read = await readDownloadUrl(deps.files.signer, provider, path, query);
 	if (read.status === "invalid") throw forbidden("invalid-signature", "This file link is not valid");
@@ -33,10 +38,11 @@ const grantedName = async (deps, provider, path, query) => {
 		fields
 	}));
 	const value = row?.record[field.name];
-	if (typeof value !== "string" || baseOf(value) !== `${provider}:${path}`) throw gone();
+	const held = heldFile(value, provider, path);
+	if (!held) throw gone();
 	if (tenantField && path.split("/")[0] !== await tenantSegment(row.record[tenantField.name])) throw gone();
 	return {
-		name: parseUri(value)?.name ?? path,
+		name: held.name,
 		expires: grant.expires
 	};
 };

package/dist/files/images.d.ts

@@ -0,0 +1,40 @@
+import { ImageFormat, ImageVariant } from "@protobase/schema";
+//#region src/files/images.d.ts
+type SharpImage = {
+  resize(width: number, height: number, options: {
+    fit: 'inside';
+  }): SharpImage;
+  resize(options: {
+    width?: number;
+    height?: number;
+    fit: 'inside' | 'cover';
+    withoutEnlargement: boolean;
+  }): SharpImage;
+  ensureAlpha(): SharpImage;
+  raw(): SharpImage;
+  toFormat(format: ImageFormat, options: {
+    quality?: number;
+  }): SharpImage;
+  toBuffer(): Promise<Uint8Array>;
+  toBuffer(options: {
+    resolveWithObject: true;
+  }): Promise<{
+    data: Uint8Array;
+    info: {
+      width: number;
+      height: number;
+    };
+  }>;
+};
+/** sharp's default export, as `import sharp from 'sharp'` gives it: what `files.sharp` takes. */
+export type Sharp = (input: Uint8Array, options: {
+  autoOrient: boolean;
+}) => SharpImage;
+/** An image's ThumbHash, base64: its shape and colours in about 25 bytes, drawn blurred while the image loads. */
+export declare const thumbHash: (sharp: Sharp, input: Uint8Array) => Promise<string>;
+/** An image resized and encoded as `variant` says, turned upright first; it is never enlarged and keeps no metadata. */
+export declare const renderVariant: (sharp: Sharp, input: Uint8Array, variant: ImageVariant) => Promise<{
+  data: Uint8Array<ArrayBufferLike>;
+  extension: string;
+}>;
+//#endregion

package/dist/files/images.js

@@ -0,0 +1,39 @@
+import { rgbaToThumbHash } from "thumbhash";
+//#region src/files/images.ts
+/** The types sharp reads, as uploads are decided: an image of another type, such as HEIC or SVG, is kept as it is. */
+const processableImages = /* @__PURE__ */ new Set([
+	"image/jpeg",
+	"image/png",
+	"image/webp",
+	"image/avif",
+	"image/gif",
+	"image/tiff"
+]);
+/** The extension each variant format is stored with. */
+const formatExtensions = {
+	webp: "webp",
+	avif: "avif",
+	jpeg: "jpg",
+	png: "png"
+};
+const thumbHashSide = 100;
+/** An image's ThumbHash, base64: its shape and colours in about 25 bytes, drawn blurred while the image loads. */
+const thumbHash = async (sharp, input) => {
+	const { data, info } = await sharp(input, { autoOrient: true }).resize(thumbHashSide, thumbHashSide, { fit: "inside" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+	return btoa(String.fromCharCode(...rgbaToThumbHash(info.width, info.height, data)));
+};
+/** An image resized and encoded as `variant` says, turned upright first; it is never enlarged and keeps no metadata. */
+const renderVariant = async (sharp, input, variant) => {
+	const image = sharp(input, { autoOrient: true });
+	return {
+		data: await (variant.width === void 0 && variant.height === void 0 ? image : image.resize({
+			width: variant.width,
+			height: variant.height,
+			fit: variant.fit ?? "inside",
+			withoutEnlargement: true
+		})).toFormat(variant.format, variant.quality === void 0 ? {} : { quality: variant.quality }).toBuffer(),
+		extension: formatExtensions[variant.format]
+	};
+};
+//#endregion
+export { formatExtensions, processableImages, renderVariant, thumbHash };

package/dist/files/options.d.ts

@@ -1,3 +1,4 @@
+import { Sharp } from "./images.js";
 import { FileProvider } from "./store.js";
 //#region src/files/options.d.ts
 /** `files` in `protobase.config.ts`. Environment variables override it (see `resolveProviders`). */
@@ -11,5 +12,10 @@ export type FilesOptions = {
   retention?: number | string;
   /** Signs upload tickets and download URLs; default `PROTOBASE_FILES_SECRET`, then `BETTER_AUTH_SECRET`. */
   secret?: string;
+  /**
+   * The image library that makes the variants and placeholders of image fields: `import sharp from 'sharp'` in the
+   * config, so a built bundle carries it with its native add-on.
+   */
+  sharp?: Sharp;
 };
 //#endregion

package/dist/files/present.d.ts

@@ -1,13 +1,25 @@
 import "../types.js";
 import "../request-access.js";
 //#region src/files/present.d.ts
-/** A file field as responses carry it; `missing` when the value does not parse or names a provider the config lacks. */
+/** An image variant of a file: its link and type, and the box the field resizes it into, as configured now. */
+export type FileVariantObject = {
+  url: string;
+  type: string;
+  width?: number;
+  height?: number;
+};
+/**
+ * A file field as responses carry it; `missing` when the value does not parse or names a provider the config lacks.
+ * `placeholder` is the ThumbHash of its placeholder field, when the row holds one.
+ */
 export type FileObject = {
   uri: string;
   name: string;
   type: string;
   size?: number;
   url?: string;
+  placeholder?: string;
+  variants?: Record<string, FileVariantObject>;
 } | {
   uri: string;
   missing: true;

package/dist/files/present.js

@@ -1,45 +1,61 @@
 import { downloadExpiry, signedDownloadUrl } from "./download-url.js";
 import { servedType } from "./media-types.js";
-import { parseUri } from "./uri.js";
+import { parseUri, variantPaths } from "./uri.js";
 import { encodeKey } from "@protobase/schema";
 //#region src/files/present.ts
+const linker = async (files, access, row, field, ref, expires) => {
+	const provider = files.providers[ref.provider];
+	if (provider.public) return async (path) => `${provider.publicUrl ?? `${files.path}/${ref.provider}`}/${path}`;
+	const key = access.full.primaryKey.map((name) => row[name]);
+	if (key.some((part) => typeof part !== "string" && typeof part !== "number")) return void 0;
+	const keyText = encodeKey(key);
+	return (path) => signedDownloadUrl(files.signer, files.path, {
+		provider: ref.provider,
+		path,
+		resource: access.entry.name,
+		key: keyText,
+		field,
+		expires
+	});
+};
 const fileObject = async (files, access, row, field, value, expires) => {
 	const ref = parseUri(value);
-	const provider = ref && files.providers[ref.provider];
-	if (!ref || !provider) return {
+	if (!ref || !files.providers[ref.provider]) return {
 		uri: value,
 		missing: true
 	};
+	const target = field.file?.placeholder;
+	const placeholder = target !== void 0 && access.model.fields[target] ? row[target] : void 0;
 	const described = {
 		uri: value,
 		name: ref.name,
 		type: servedType(ref.path),
-		...ref.size !== void 0 && { size: ref.size }
+		...ref.size !== void 0 && { size: ref.size },
+		...typeof placeholder === "string" && { placeholder }
 	};
-	if (provider.public) return {
-		...described,
-		url: `${provider.publicUrl ?? `${files.path}/${ref.provider}`}/${ref.path}`
-	};
-	const key = access.full.primaryKey.map((name) => row[name]);
-	if (key.some((part) => typeof part !== "string" && typeof part !== "number")) return described;
-	const keyText = encodeKey(key);
-	const url = await signedDownloadUrl(files.signer, files.path, {
-		provider: ref.provider,
-		path: ref.path,
-		resource: access.entry.name,
-		key: keyText,
-		field,
-		expires
-	});
+	const link = await linker(files, access, row, field.name, ref, expires);
+	if (!link) return described;
+	const variants = {};
+	for (const [name, path] of Object.entries(variantPaths(ref))) {
+		const box = field.file?.variants?.[name];
+		variants[name] = {
+			url: await link(path),
+			type: servedType(path),
+			...box?.width !== void 0 && { width: box.width },
+			...box?.height !== void 0 && { height: box.height }
+		};
+	}
 	return {
 		...described,
-		url
+		url: await link(ref.path),
+		...Object.keys(variants).length > 0 && { variants }
 	};
 };
 /**
-* Records as responses carry them: each readable file field as `{ uri, name, type, size, url }`. The URL is minted here,
-* after the ETag, for a caller who may already see the row: private files get a signed link to this row's field, public
-* ones their permanent address. Stored values, hooks and ETags only ever see the URI.
+* Records as responses carry them: each readable file field as `{ uri, name, type, size, url }`, with its `variants` and
+* `placeholder` when it has them. The URLs are minted here, after the ETag, for a caller who may already see the row:
+* private files get a signed link to this row's field, public ones their permanent address. Stored values, hooks and
+* ETags only ever see the URI.
 */
 const presentFiles = async (access, rows) => {
 	const files = access.deps.files;
@@ -50,7 +66,7 @@ const presentFiles = async (access, rows) => {
 		const shown = { ...row };
 		for (const field of fields) {
 			const value = row[field.name];
-			if (typeof value === "string") shown[field.name] = await fileObject(files, access, row, field.name, value, expires);
+			if (typeof value === "string") shown[field.name] = await fileObject(files, access, row, field, value, expires);
 		}
 		return shown;
 	}));

package/dist/files/runtime.d.ts

@@ -1,3 +1,5 @@
+import "./images.js";
+import "./options.js";
 import "./cleanup-runner.js";
 import { ResourceModel } from "@protobase/schema";
 import { Db } from "@protobase/query";

package/dist/files/runtime.js

@@ -5,15 +5,18 @@ import { createSigner } from "./signer.js";
 //#region src/files/runtime.ts
 /** How long an upload ticket stays usable, so a form left open still saves. */
 const ticketSeconds = 86400;
+const imageFields = (models) => models.flatMap((model) => Object.values(model.fields).flatMap(({ name, file }) => file && (file.variants || file.original || file.placeholder !== void 0) ? [`${model.name}.${name}`] : []));
 /**
 * The runtime, when a resource has a file field or the config names providers. It fails at startup when a field's
-* provider is not configured or nothing signs uploads.
+* provider is not configured, nothing signs uploads, or a field makes image variants or placeholders without sharp.
 */
 const createFilesRuntime = ({ options = {}, env, models, systemPath }) => {
 	const used = [...new Set(models.flatMap((model) => Object.values(model.fields).flatMap((field) => field.file ? [field.file.provider] : [])))];
 	if (used.length === 0 && !options.providers) return void 0;
 	const secret = options.secret ?? env.PROTOBASE_FILES_SECRET ?? env.BETTER_AUTH_SECRET;
 	if (!secret) throw new Error("File fields need a secret to sign uploads: set BETTER_AUTH_SECRET, PROTOBASE_FILES_SECRET or files.secret");
+	const images = imageFields(models);
+	if (images.length > 0 && !options.sharp) throw new Error(`${images.join(", ")} make image variants or placeholders, which need sharp: add it to the project (bun add sharp), then import sharp from 'sharp' in the config and pass files: { sharp }`);
 	const providers = resolveProviders(options, env, used);
 	const retention = retentionOf(options, env);
 	return {
@@ -22,7 +25,8 @@ const createFilesRuntime = ({ options = {}, env, models, systemPath }) => {
 		schedule: storageCleanupSchedule(providers),
 		retention: (provider) => retention(providers[provider]),
 		path: `${systemPath}/files`,
-		columns: fileColumns(models)
+		columns: fileColumns(models),
+		...options.sharp && { sharp: options.sharp }
 	};
 };
 /** Runs the scheduled deletes that are due (see `runCleanup`). */

package/dist/files/ticket.js

@@ -51,6 +51,7 @@ const readTicket = async (signer, value, scope, now) => {
 	const known = /* @__PURE__ */ new Set([
 		"name",
 		"size",
+		"variants",
 		"exp",
 		"sig"
 	]);
@@ -58,10 +59,13 @@ const readTicket = async (signer, value, scope, now) => {
 		ok: false,
 		reason: "invalid"
 	};
-	const parsed = parseUri(value.slice(0, value.indexOf("?")) + `?${new URLSearchParams({
+	const variants = query.get("variants");
+	const fileQuery = new URLSearchParams({
 		name: query.get("name") ?? "",
-		size: query.get("size") ?? ""
-	})}`);
+		size: query.get("size") ?? "",
+		...variants !== null && { variants }
+	});
+	const parsed = parseUri(`${value.slice(0, value.indexOf("?"))}?${fileQuery}`);
 	const expires = Number(query.get("exp"));
 	if (!parsed || parsed.size === void 0 || !Number.isSafeInteger(expires)) return {
 		ok: false,

package/dist/files/upload-images.js

@@ -0,0 +1,42 @@
+import { variantPath } from "./uri.js";
+import { formatExtensions, processableImages, renderVariant, thumbHash } from "./images.js";
+//#region src/files/upload-images.ts
+/** Whether an upload of `type` is an image this field processes: it declares variants, an original or a placeholder, and sharp reads the type. */
+const processesImage = (file, type) => processableImages.has(type) && (file.variants !== void 0 || file.original !== void 0 || file.placeholder !== void 0);
+/** The path the field's file is stored at: `<base>.<extension>`, with the original's format when an image replaces the upload. */
+const storedPath = (file, base, decision) => file.original && processesImage(file, decision.type) ? `${base}.${formatExtensions[file.original.format]}` : `${base}.${decision.extension}`;
+/** The extension of each variant an image of `type` gets, by name; none for other files. */
+const plannedVariants = (file, type) => processesImage(file, type) ? Object.fromEntries(Object.entries(file.variants ?? {}).map(([name, variant]) => [name, formatExtensions[variant.format]])) : {};
+const streamOf = (bytes) => new ReadableStream({ start(controller) {
+	controller.enqueue(bytes);
+	controller.close();
+} });
+/**
+* Makes what an image field declares from the upload stored at `uploaded`: the image replacing it at `path` (the
+* upload is then deleted), each variant beside `path`, and the ThumbHash. Answers the replacing image's bytes, if any.
+*/
+const processImage = async ({ sharp, store, file, uploaded, path }) => {
+	const body = await store.read(uploaded);
+	if (!body) throw new Error(`The upload ${uploaded} is gone from its store`);
+	const input = new Uint8Array(await new Response(body).arrayBuffer());
+	let replaced;
+	if (file.original) {
+		const { data } = await renderVariant(sharp, input, file.original);
+		replaced = {
+			data,
+			size: (await store.put(path, streamOf(data))).size
+		};
+		if (path !== uploaded) await store.delete(uploaded);
+	}
+	for (const [name, variant] of Object.entries(file.variants ?? {})) {
+		const { data, extension } = await renderVariant(sharp, input, variant);
+		await store.put(variantPath(path, name, extension), streamOf(data));
+	}
+	const placeholder = file.placeholder === void 0 ? void 0 : await thumbHash(sharp, input);
+	return {
+		replaced,
+		placeholder
+	};
+};
+//#endregion
+export { plannedVariants, processImage, processesImage, storedPath };

package/dist/files/upload.js

@@ -1,6 +1,6 @@
 import { HttpProblem, badRequest } from "../problem.js";
-import { accepts } from "./media-types.js";
-import { cleanName, tenantSegment } from "./uri.js";
+import { accepts, servedType } from "./media-types.js";
+import { cleanName, tenantSegment, variantPath } from "./uri.js";
 import { tenantScope } from "../tenant.js";
 import { requestAccess, requireOperation, writableFields } from "../request-access.js";
 import { issueTicket } from "./ticket.js";
@@ -8,6 +8,7 @@ import { ticketScope } from "./attach.js";
 import { ticketSeconds } from "./runtime.js";
 import { decideType } from "./detect.js";
 import { FileTooLarge, incomingFile, limitedStream, readHead, tooLarge } from "./upload-body.js";
+import { plannedVariants, processImage, processesImage, storedPath } from "./upload-images.js";
 //#region src/files/upload.ts
 /** How many first bytes processors get as `head`: enough for image headers, EXIF included. */
 const headBytes = 262144;
@@ -49,8 +50,9 @@ const deriveValues = async (entry, field, input) => {
 /**
 * `POST /{resource}:upload?field=<field>`: streams one file to the field's provider and answers with a ticket for a
 * write. The type is decided from the first bytes before anything is stored, a refused type gets 415 and a file over
-* `maxSize` 413. The field's processors then compute its derived values, which the ticket carries signed. An upload no
-* write ever uses is deleted after the ticket expires.
+* `maxSize` 413. An image field then makes its variants and placeholder, and replaces the upload when it declares an
+* original; the field's processors compute its derived values, which the ticket carries signed with the variants. An
+* upload no write ever uses is deleted after the ticket expires, variants included.
 */
 const uploadFile = async (deps, entry, session, request) => {
 	const files = deps.files;
@@ -82,39 +84,74 @@ const uploadFile = async (deps, entry, session, request) => {
 		});
 	}
 	const expires = Math.floor(Date.now() / 1e3) + ticketSeconds;
-	const path = `${await tenantSegment(tenantScope(entry, session)?.tenantValue)}/${crypto.randomUUID()}.${decision.extension}`;
+	const base = `${await tenantSegment(tenantScope(entry, session)?.tenantValue)}/${crypto.randomUUID()}`;
+	const uploaded = `${base}.${decision.extension}`;
+	const path = storedPath(field.file, base, decision);
+	const variants = plannedVariants(field.file, decision.type);
+	const variantList = Object.entries(variants).map(([variant, extension]) => variantPath(path, variant, extension));
+	const due = /* @__PURE__ */ new Date((expires + 3600) * 1e3);
 	await files.schedule.add([{
 		provider: providerName,
 		path,
-		due: /* @__PURE__ */ new Date((expires + 3600) * 1e3)
-	}]);
+		due,
+		...variantList.length > 0 && { variants: variantList }
+	}, ...uploaded === path ? [] : [{
+		provider: providerName,
+		path: uploaded,
+		due
+	}]]);
 	let size;
 	try {
-		size = (await provider.store.put(path, limitedStream(head, reader, maxSize))).size;
+		size = (await provider.store.put(uploaded, limitedStream(head, reader, maxSize))).size;
 	} catch (error) {
 		if (error instanceof FileTooLarge) throw tooLarge(maxSize);
 		throw error;
 	}
-	const derived = await deriveValues(entry, field, {
-		name,
+	let stored = {
 		type: decision.type,
 		size,
-		head,
-		store: provider.store,
-		path
-	});
+		head
+	};
+	let placeholder;
+	if (processesImage(field.file, decision.type)) {
+		if (!files.sharp) throw new Error(`${entry.name}.${field.name} makes image variants or placeholders, but no sharp is configured`);
+		const image = await processImage({
+			sharp: files.sharp,
+			store: provider.store,
+			file: field.file,
+			uploaded,
+			path
+		});
+		if (image.replaced) stored = {
+			type: servedType(path),
+			size: image.replaced.size,
+			head: image.replaced.data.subarray(0, headBytes)
+		};
+		placeholder = image.placeholder;
+	}
+	const target = field.file.placeholder;
+	const derived = {
+		...await deriveValues(entry, field, {
+			name,
+			...stored,
+			store: provider.store,
+			path
+		}),
+		...target !== void 0 && { [target]: placeholder ?? null }
+	};
 	const ref = {
 		provider: providerName,
 		path,
 		name,
-		size
+		size: stored.size,
+		...variantList.length > 0 && { variants }
 	};
 	return {
 		value: await issueTicket(files.signer, ref, derived, ticketScope(access, field.name), expires),
 		file: {
 			name,
-			type: decision.type,
-			size
+			type: stored.type,
+			size: stored.size
 		},
 		derived,
 		...decision.corrected && { corrected: decision.corrected }

package/dist/files/uri.d.ts

@@ -0,0 +1,21 @@
+//#region src/files/uri.d.ts
+/**
+ * A stored file value: `{provider}:{path}?name=<name>&size=<bytes>`, such as `private:acme/2992db9c-….jpg?name=bike.png&size=48211`.
+ * It is an ordinary URI whose scheme is the provider's name; `public:images/test.jpg`, without a query, parses too.
+ * The part before `?` is the file's identity; the query is metadata about bytes that never change, and names the image
+ * variants stored beside it with their extension: `&variants=card.webp,thumb.avif`.
+ */
+export type FileRef = {
+  provider: string;
+  path: string;
+  name: string;
+  size?: number;
+  variants?: Record<string, string>;
+};
+/**
+ * Where a file's variant is stored: beside it, its path followed by the variant's name and extension, such as
+ * `acme/2992db9c-….jpg.card.webp`. Every variant's address is built here.
+ */
+export declare const variantPath: (path: string, name: string, extension: string) => string;
+export declare const formatUri: (ref: FileRef) => string;
+//#endregion

package/dist/files/uri.js

@@ -6,10 +6,25 @@ const maxPath = 512;
 const isFilePath = (path) => path.length <= maxPath && path.split("/").every((part) => segment.test(part));
 /** The identity of a value or ticket: `{provider}:{path}`. */
 const baseOf = (value) => value.split("?", 1)[0];
+const variantEntry = /^([a-z][a-z0-9_]{0,31})\.([a-z0-9]{1,8})$/;
+/**
+* Where a file's variant is stored: beside it, its path followed by the variant's name and extension, such as
+* `acme/2992db9c-….jpg.card.webp`. Every variant's address is built here.
+*/
+const variantPath = (path, name, extension) => `${path}.${name}.${extension}`;
+/** The paths of a file's variants, by name. */
+const variantPaths = (ref) => Object.fromEntries(Object.entries(ref.variants ?? {}).map(([name, extension]) => [name, variantPath(ref.path, name, extension)]));
+const formatVariants = (variants) => Object.entries(variants).map(([name, extension]) => `${name}.${extension}`).join(",");
+const parseVariants = (text) => {
+	const entries = text.split(",").map((entry) => variantEntry.exec(entry));
+	if (entries.some((entry) => !entry)) return void 0;
+	return Object.fromEntries(entries.map((entry) => [entry[1], entry[2]]));
+};
 const formatUri = (ref) => {
 	const query = new URLSearchParams({
 		name: ref.name,
-		...ref.size !== void 0 && { size: String(ref.size) }
+		...ref.size !== void 0 && { size: String(ref.size) },
+		...ref.variants && Object.keys(ref.variants).length > 0 && { variants: formatVariants(ref.variants) }
 	});
 	return `${ref.provider}:${ref.path}?${query}`;
 };
@@ -21,11 +36,15 @@ const parseUri = (value) => {
 	const query = new URLSearchParams(match[3] ?? "");
 	const size = query.get("size");
 	if (size !== null && !/^\d{1,15}$/.test(size)) return void 0;
+	const listed = query.get("variants");
+	const variants = listed === null ? void 0 : parseVariants(listed);
+	if (listed !== null && !variants) return void 0;
 	return {
 		provider: match[1],
 		path: match[2],
 		name: query.get("name") || lastSegment(match[2]),
-		...size !== null && { size: Number(size) }
+		...size !== null && { size: Number(size) },
+		...variants && { variants }
 	};
 };
 const encoder = new TextEncoder();
@@ -44,4 +63,4 @@ const tenantSegment = async (tenant) => {
 	return tenantText.test(text) ? text : `t${(await sha256Hex(text)).slice(0, 32)}`;
 };
 //#endregion
-export { baseOf, cleanName, formatUri, isFilePath, parseUri, tenantSegment };
+export { baseOf, cleanName, formatUri, isFilePath, parseUri, tenantSegment, variantPath, variantPaths };

package/dist/index.d.ts

@@ -13,6 +13,7 @@ import { EnqueueOptions, JobContext, JobDefinition, JobOptions } from "./jobs/jo
 import { Admin, AuditEvent, AuditQueue, Authenticator, PipelineHook, ScanGuardMode, Session, SessionOrganization, TenantValue, User, ViewSource, WriteEvent, WriteOperation } from "./types.js";
 import { WebhooksOptions } from "./webhooks/table/options.js";
 import { EventData, RunContext, SubscriptionDefinition, SubscriptionEvent, SubscriptionOptions, subscription } from "./webhooks/subscription.js";
+import { Sharp, renderVariant, thumbHash } from "./files/images.js";
 import { FileProvider, FileStore, StoredObject } from "./files/store.js";
 import { FilesOptions } from "./files/options.js";
 import { ErrorReportingOptions, ErrorReportingSettings, errorReportingSettings, errorReportingVariable } from "./error-reporting/error-reporting-settings.js";
@@ -71,11 +72,12 @@ import { FileLimits, limitedFileStore } from "./files/limits.js";
 import { LocalFilesOptions, localFileStore, localFiles } from "./files/local-files.js";
 import { S3Bucket, S3FilesOptions, S3ListPage, S3Object, s3FileStore, s3Files } from "./files/s3-files.js";
 import { FileCleanupInput, createFileCleanup } from "./files/file-cleanup.js";
-import { FileObject } from "./files/present.js";
+import { FileObject, FileVariantObject } from "./files/present.js";
+import { FileRef, formatUri, variantPath } from "./files/uri.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
 import { defineJob, isJobDefinition, jobDefinitions } from "./jobs/define-job.js";
 import { FatalJobError } from "./jobs/run-job.js";
 import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
-export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileStore, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapOptions, type MemberInput, MissingCredentials, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type SignInPolicy, type SignInRule, type SignatureOptions, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };
+export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapOptions, type MemberInput, MissingCredentials, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };

package/dist/index.js

@@ -9,6 +9,7 @@ import { readOnlyQueryTool, readWriteQueryTool } from "./assistant/query-tools.j
 import { requestApproval } from "./assistant/approval.js";
 import { withCacheBreakpoints } from "./assistant/cache-breakpoints.js";
 import { ModelError, streamChatCompletion } from "./assistant/chat-completions.js";
+import { formatUri, variantPath } from "./files/uri.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
 import { runTurn } from "./assistant/turn.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
@@ -38,6 +39,7 @@ import { mapStyleUrl, mapStyleVariable } from "./maps/map-settings.js";
 import { pluginOptions, pluginsFor, pluginsVariable } from "./plugins/plugin-settings.js";
 import { runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
 import { checkSourceNames, sourceOptions, sourcesFor, sourcesVariable } from "./sources/source-settings.js";
+import { renderVariant, thumbHash } from "./files/images.js";
 import { createAdmin } from "./create-admin.js";
 import { configExports } from "./resource-source.js";
 import { defineConfig, mergeConfig } from "./project-config.js";
@@ -59,4 +61,4 @@ import { createFileCleanup } from "./files/file-cleanup.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
 import { startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
-export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };
+export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };

package/dist/map-service.js

@@ -0,0 +1,62 @@
+import { checkedFilter } from "./filter-input.js";
+import { readScope, requestAccess, requireOperation } from "./request-access.js";
+import { readTransaction } from "./transactions.js";
+import { parseParams } from "./params.js";
+import { listRecords } from "./list-service.js";
+import { checkMapPosition, countUpTo, mapBuckets, maxMapZoom } from "@protobase/query";
+import { z } from "zod";
+const mapParams = z.object({
+	latitude: z.string().min(1),
+	longitude: z.string().min(1),
+	zoom: z.coerce.number().int().min(0).max(maxMapZoom),
+	filter: z.string().optional(),
+	order_by: z.string().optional(),
+	fields: z.union([z.string(), z.array(z.string())]).optional()
+});
+/**
+* The matching records for a map at `zoom`, the bounding box being part of the filter: the records themselves when
+* few match or the map is close enough, as a list returns them, else buckets of a grid sized for the zoom. Both are
+* checked and scoped like a list.
+*/
+const mapRecords = async (deps, entry, session, input) => {
+	const params = parseParams(mapParams, input);
+	const access = await requestAccess(deps, entry, session);
+	requireOperation(access, "list");
+	const position = {
+		latitude: params.latitude,
+		longitude: params.longitude
+	};
+	checkMapPosition(access.model, position);
+	const filter = checkedFilter(access.model, params.filter);
+	const scope = readScope(access);
+	const found = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => countUpTo(trx, access.model, 201, filter, scope));
+	if (found <= 200 || params.zoom >= 16) {
+		const list = {
+			filter: params.filter,
+			order_by: params.order_by,
+			fields: params.fields,
+			page_size: 200,
+			...found > 200 && { count: "exact" }
+		};
+		const { body, warning } = await listRecords(deps, entry, session, list);
+		return {
+			warning,
+			body: {
+				items: body.items,
+				buckets: [],
+				total_size: body.total_size ?? found
+			}
+		};
+	}
+	const result = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => mapBuckets(trx, access.model, position, params.zoom, filter, scope));
+	return {
+		warning: void 0,
+		body: {
+			items: [],
+			buckets: result.buckets,
+			total_size: result.total
+		}
+	};
+};
+//#endregion
+export { mapRecords };

package/dist/openapi/resource-paths.js

@@ -1,5 +1,6 @@
 import { writableFields } from "../request-access.js";
 import { pascal } from "./naming.js";
+import { mapCellPixels, maxMapBuckets, maxMapZoom } from "@protobase/query";
 //#region src/openapi/resource-paths.ts
 const param = (name) => ({ $ref: `#/components/parameters/${name}` });
 const error = (name) => ({ $ref: `#/components/responses/${name}` });
@@ -63,12 +64,52 @@ const page = (name, seek = false) => json({
 		}
 	}
 });
+const bounds = {
+	type: "object",
+	properties: {
+		south: { type: "number" },
+		west: { type: "number" },
+		north: { type: "number" },
+		east: { type: "number" }
+	}
+};
+const mapResult = (name) => json({
+	type: "object",
+	required: [
+		"items",
+		"buckets",
+		"total_size"
+	],
+	properties: {
+		items: {
+			type: "array",
+			items: ref(name)
+		},
+		buckets: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					count: { type: "integer" },
+					latitude: { type: "number" },
+					longitude: { type: "number" },
+					bounds
+				}
+			}
+		},
+		total_size: {
+			type: "integer",
+			description: "How many records match"
+		}
+	}
+});
 const needs = {
 	list: "list",
 	search: "list",
 	facets: "list",
 	series: "list",
 	histogram: "list",
+	map: "list",
 	seek: "list",
 	get: "read",
 	reveal: "read",
@@ -386,6 +427,32 @@ const resourcePaths = (access) => {
 				...auth
 			}
 		} },
+		[`/${entry.name}:map`]: { get: {
+			operationId: `map_${entry.name}`,
+			tags: tag,
+			summary: `${entry.name} records on a map, or buckets of them`,
+			description: `Put the map's bounding box in the filter, such as \`lat >= 51.9 AND lat <= 52.1 AND lng >= 4.2 AND lng <= 4.5\`. When up to 200 records match, or from zoom 16 on, \`items\` holds them (at most 200) as a list returns them and \`buckets\` is empty; otherwise \`buckets\` counts them per cell of a Web Mercator grid about ${mapCellPixels} pixels across at the zoom (the fullest ${maxMapBuckets}) and \`items\` is empty. Records without a position are in no bucket.`,
+			parameters: [
+				query("latitude", "A filterable number field holding the latitude in decimal degrees", { type: "string" }, true),
+				query("longitude", "A filterable number field holding the longitude in decimal degrees", { type: "string" }, true),
+				query("zoom", "The map's zoom, as MapLibre counts it", {
+					type: "integer",
+					minimum: 0,
+					maximum: maxMapZoom
+				}, true),
+				param("filter"),
+				param("orderBy"),
+				param("fields")
+			],
+			responses: {
+				200: {
+					description: "The records or the buckets, and how many records match",
+					content: mapResult(name)
+				},
+				400: error("BadRequest"),
+				...auth
+			}
+		} },
 		[`/${entry.name}:seek`]: { get: {
 			operationId: `seek_${entry.name}`,
 			tags: tag,

package/dist/openapi/schemas.js

@@ -41,6 +41,24 @@ const fileSchema = {
 		},
 		size: { type: "integer" },
 		url: { type: "string" },
+		placeholder: {
+			type: "string",
+			description: "The image's ThumbHash, base64, to draw while it loads"
+		},
+		variants: {
+			type: "object",
+			description: "Resized copies of the image by name, each with the box the field resizes it into",
+			additionalProperties: {
+				type: "object",
+				required: ["url", "type"],
+				properties: {
+					url: { type: "string" },
+					type: { type: "string" },
+					width: { type: "integer" },
+					height: { type: "integer" }
+				}
+			}
+		},
 		missing: { type: "boolean" }
 	}
 };

package/dist/project-config.js

@@ -101,14 +101,16 @@ const mergedFiles = (named) => {
 		label
 	})));
 	checkUnique("The file provider", providers);
-	const { retention, secret } = lastSet(all.map(({ files }) => ({
+	const { retention, secret, sharp } = lastSet(all.map(({ files }) => ({
 		retention: files.retention,
-		secret: files.secret
+		secret: files.secret,
+		sharp: files.sharp
 	})));
 	return {
 		...providers.length > 0 && { providers: Object.fromEntries(providers.map(({ name, value }) => [name, value])) },
 		...retention !== void 0 && { retention },
-		...secret !== void 0 && { secret }
+		...secret !== void 0 && { secret },
+		...sharp !== void 0 && { sharp }
 	};
 };
 const mergedJobs = (named) => {

package/dist/routes/collection.js

@@ -1,6 +1,7 @@
 import { runWrite } from "../write-pipeline.js";
 import { listRecords } from "../list-service.js";
 import { facets, numericHistogram, timeSeries } from "../aggregate-service.js";
+import { mapRecords } from "../map-service.js";
 import { uploadFile } from "../files/upload.js";
 import { returnPreference } from "./preferences.js";
 import { resolveTarget, unknownAction } from "./target.js";
@@ -23,6 +24,10 @@ const collectionRoutes = (deps) => {
 		if (action === "facets") return c.json(await facets(deps, entry, session, query));
 		if (action === "series") return c.json(await timeSeries(deps, entry, session, query));
 		if (action === "histogram") return c.json(await numericHistogram(deps, entry, session, query));
+		if (action === "map") {
+			const { body, warning } = await mapRecords(deps, entry, session, query);
+			return c.json(body, 200, warningHeader(warning));
+		}
 		if (action === "seek") {
 			const { body, warning } = await listRecords(deps, entry, session, query, void 0, true);
 			return c.json(body, 200, warningHeader(warning));

package/dist/view-map.js

@@ -17,5 +17,13 @@ const mapErrors = (item, model) => [
 	...coordinateErrors(model, item.longitude),
 	...item.zoom === void 0 || Number.isFinite(item.zoom) && item.zoom >= 0 && item.zoom <= maxZoom ? [] : [`zoom ${item.zoom} is not between 0 and ${maxZoom}`]
 ];
+const filterableErrors = (model, name) => Object.hasOwn(model.fields, name) && !model.fields[name].filterable ? [`"${name}" on ${model.name} is not filterable, and the map display filters by position`] : [];
+/** What makes a map display unable to show the records: a field that is no number, or one it cannot filter by. */
+const mapDisplayErrors = (display, model) => [
+	...coordinateErrors(model, display.latitude),
+	...coordinateErrors(model, display.longitude),
+	...filterableErrors(model, display.latitude),
+	...filterableErrors(model, display.longitude)
+];
 //#endregion
-export { mapErrors };
+export { mapDisplayErrors, mapErrors };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.13.0",
+  "version": "0.13.3",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.13.0",
-    "@protobase/query": "0.13.0",
-    "@protobase/schema": "0.13.0",
+    "@protobase/layout": "0.13.3",
+    "@protobase/query": "0.13.3",
+    "@protobase/schema": "0.13.3",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",
     "@simplewebauthn/server": "^13.3.1",
@@ -45,6 +45,15 @@
     "kysely": "^0.29.6",
     "nodemailer": "^10.0.16",
     "pg-boss": "12.37.1",
+    "thumbhash": "^0.1.1",
     "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "sharp": "^0.35.5"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
   }
 }