emdash 0.7.0 → 0.9.0

package/src/schema/registry.ts

@@ -8,9 +8,11 @@ import { withTransaction } from "../database/transaction.js";
 import type { CollectionTable, Database, FieldTable } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
 import { FTSManager } from "../search/fts-manager.js";
+import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import {
 	type Collection,
 	type CollectionSource,
+	type CollectionSupport,
 	type ColumnType,
 	type Field,
 	type CreateCollectionInput,
@@ -49,6 +51,34 @@ function isColumnType(value: string): value is ColumnType {
 	return COLUMN_TYPES.has(value);
 }
 
+const VALID_COLLECTION_SUPPORTS: ReadonlySet<string> = new Set<CollectionSupport>([
+	"drafts",
+	"revisions",
+	"preview",
+	"scheduling",
+	"search",
+	"seo",
+]);
+
+function isCollectionSupport(value: unknown): value is CollectionSupport {
+	return typeof value === "string" && VALID_COLLECTION_SUPPORTS.has(value);
+}
+
+/**
+ * Parse a collection's `supports` column (stored as a JSON array of
+ * CollectionSupport keys). Unknown/invalid entries are filtered out so the
+ * runtime value matches the declared `CollectionSupport[]` type.
+ *
+ * Throws on malformed JSON so corruption surfaces loudly; returns an empty
+ * array only for explicitly null/empty values or non-array JSON.
+ */
+function parseSupports(raw: string | null | undefined): CollectionSupport[] {
+	if (!raw) return [];
+	const parsed: unknown = JSON.parse(raw);
+	if (!Array.isArray(parsed)) return [];
+	return parsed.filter(isCollectionSupport);
+}
+
 /**
  * Error thrown when a schema operation fails
  */
@@ -114,6 +144,61 @@ export class SchemaRegistry {
 		return { ...collection, fields };
 	}
 
+	/**
+	 * List every collection together with its fields in O(1) query shapes
+	 * — one for collections, then one batched query for the fields of every
+	 * returned collection — instead of the N+1 pattern of `listCollections`
+	 * + per-collection `listFields`. The fields query is chunked at
+	 * `SQL_BATCH_SIZE` to stay under D1's bound-parameter limit, so on
+	 * sites with more than `SQL_BATCH_SIZE` collections the field fetch
+	 * becomes `ceil(collectionCount / SQL_BATCH_SIZE)` queries — still
+	 * a constant factor, not N+1. Typical sites have well under
+	 * `SQL_BATCH_SIZE` collections, so this is two queries in practice.
+	 *
+	 * Used by the manifest build, which previously paid N+1 round-trips on
+	 * every admin request. Each round-trip costs ~80–150ms against the D1
+	 * primary on a busy link, so a 10-collection site spent ~1 s rebuilding
+	 * a manifest that is now built fresh per admin request (no cache).
+	 */
+	async listCollectionsWithFields(): Promise<CollectionWithFields[]> {
+		const collectionRows = await this.db
+			.selectFrom("_emdash_collections")
+			.selectAll()
+			.orderBy("slug", "asc")
+			.execute();
+
+		if (collectionRows.length === 0) return [];
+
+		const fieldsByCollection = new Map<string, Field[]>();
+		// Chunk to stay under D1's bound-parameter limit. Typical sites have
+		// well under SQL_BATCH_SIZE collections, so this is a single query
+		// in practice; on larger sites it becomes a small constant number
+		// of queries, never N+1.
+		for (const idChunk of chunks(
+			collectionRows.map((c) => c.id),
+			SQL_BATCH_SIZE,
+		)) {
+			const fieldRows = await this.db
+				.selectFrom("_emdash_fields")
+				.where("collection_id", "in", idChunk)
+				.selectAll()
+				.orderBy("collection_id", "asc")
+				.orderBy("sort_order", "asc")
+				.orderBy("created_at", "asc")
+				.execute();
+			for (const row of fieldRows) {
+				const list = fieldsByCollection.get(row.collection_id) ?? [];
+				list.push(this.mapFieldRow(row));
+				fieldsByCollection.set(row.collection_id, list);
+			}
+		}
+
+		return collectionRows.map((c) => ({
+			...this.mapCollectionRow(c),
+			fields: fieldsByCollection.get(c.id) ?? [],
+		}));
+	}
+
 	/**
 	 * Create a new collection
 	 */
@@ -132,11 +217,18 @@ export class SchemaRegistry {
 
 		const id = ulid();
 
+		// Default `supports` to drafts + revisions when the caller didn't
+		// specify it. Explicit empty array (`[]`) is preserved as an opt-out
+		// — only `undefined` triggers the default. This is the canonical
+		// default for new collections; the MCP and admin UI layers used to
+		// duplicate this default but now defer to the registry.
+		const supports = input.supports ?? ["drafts", "revisions"];
+
 		// Insert collection record and create content table in a transaction
 		// so a failure in table creation doesn't leave an orphaned row.
 		// Uses withTransaction for D1 compatibility (no transaction support).
 		// Derive hasSeo from supports array if not explicitly set
-		const hasSeo = input.hasSeo ?? input.supports?.includes("seo") ?? false;
+		const hasSeo = input.hasSeo ?? supports.includes("seo") ?? false;
 
 		await withTransaction(this.db, async (trx) => {
 			await trx
@@ -148,7 +240,7 @@ export class SchemaRegistry {
 					label_singular: input.labelSingular ?? null,
 					description: input.description ?? null,
 					icon: input.icon ?? null,
-					supports: input.supports ? JSON.stringify(input.supports) : null,
+					supports: JSON.stringify(supports),
 					source: input.source ?? "manual",
 					has_seo: hasSeo ? 1 : 0,
 					comments_enabled: input.commentsEnabled ? 1 : 0,
@@ -243,7 +335,7 @@ export class SchemaRegistry {
 			// Sync FTS state when the supports array changes (e.g. search toggled on/off)
 			if (input.supports !== undefined) {
 				const hadSearch = existing.supports.includes("search");
-				const hasSearch = (JSON.parse(row.supports ?? "[]") as string[]).includes("search");
+				const hasSearch = parseSupports(row.supports).includes("search");
 				if (hadSearch !== hasSearch) {
 					await this.syncSearchState(slug, trx);
 				}
@@ -525,7 +617,7 @@ export class SchemaRegistry {
 			.executeTakeFirst();
 		if (!row) return;
 
-		const wantsSearch = (JSON.parse(row.supports ?? "[]") as string[]).includes("search");
+		const wantsSearch = parseSupports(row.supports).includes("search");
 		const searchableFields = await ftsManager.getSearchableFields(collectionSlug);
 		const config = await ftsManager.getSearchConfig(collectionSlug);
 		const ftsActive = config?.enabled === true;
@@ -881,7 +973,7 @@ export class SchemaRegistry {
 			labelSingular: row.label_singular ?? undefined,
 			description: row.description ?? undefined,
 			icon: row.icon ?? undefined,
-			supports: row.supports ? JSON.parse(row.supports) : [],
+			supports: parseSupports(row.supports),
 			source: row.source && isCollectionSource(row.source) ? row.source : undefined,
 			hasSeo: row.has_seo === 1,
 			urlPattern: row.url_pattern ?? undefined,

package/src/schema/zod-generator.ts

@@ -35,9 +35,16 @@ export function generateFieldSchema(field: Field): ZodTypeAny {
 		schema = applyValidation(schema, field);
 	}
 
-	// Apply required/optional
+	// Apply required/optional. Non-required fields use `.nullish()` rather
+	// than `.optional()` because the underlying SQLite columns are nullable
+	// (see `SchemaRegistry.addFieldColumn` -- non-required fields are added
+	// without `NOT NULL`). The admin re-sends what it loaded from the
+	// server on autosave, so any field that's actually `null` in the DB
+	// must round-trip cleanly through the validator. `.optional()` only
+	// accepts `undefined`; `.nullish()` accepts both `undefined` and
+	// `null`. (#867 — autosave failures on seeded entries.)
 	if (!field.required) {
-		schema = schema.optional();
+		schema = schema.nullish();
 	}
 
 	// Apply default value
@@ -68,7 +75,15 @@ function getBaseSchema(type: FieldType, field: Field): ZodTypeAny {
 			return z.number().int();
 
 		case "boolean":
-			return z.boolean();
+			// Boolean fields map to `INTEGER` columns (`FIELD_TYPE_TO_COLUMN`
+			// in `schema/types.ts`) and `serializeValue` in
+			// `database/repositories/content.ts` writes booleans as 0/1.
+			// `deserializeValue` never converts them back, so reads return
+			// numbers. Coerce the stored 0/1 shape here so a GET → POST
+			// round-trip on a boolean field passes validation. Other inputs
+			// (strings, other numbers) fall through to `z.boolean()` and
+			// produce its standard rejection.
+			return z.preprocess((v) => (v === 0 || v === 1 ? Boolean(v) : v), z.boolean());
 
 		case "datetime":
 			return z.string().datetime().or(z.string().date());
@@ -92,12 +107,19 @@ function getBaseSchema(type: FieldType, field: Field): ZodTypeAny {
 		}
 
 		case "portableText":
-			// Portable Text is an array of blocks
+			// Portable Text is an array of blocks. We require `_type` because
+			// renderers dispatch on it, but `_key` is intentionally optional:
+			// it's a UI-layer concern that the editor regenerates on every
+			// change (see `PortableTextEditor`), and the rest of this schema
+			// uses `.passthrough()` for everything below the top level. Making
+			// `_key` strictly required here was an accidentally tight invariant
+			// that rejected any seed/import data not authored against the
+			// editor (#867 — autosave failures on seeded template content).
 			return z.array(
 				z
 					.object({
 						_type: z.string(),
-						_key: z.string(),
+						_key: z.string().optional(),
 					})
 					.passthrough(),
 			);

package/src/search/fts-manager.ts

@@ -418,8 +418,6 @@ export class FTSManager {
 			console.warn(
 				`FTS index for "${collectionSlug}" has ${ftsRows} rows but content table has ${contentRows}. Rebuilding.`,
 			);
-			const fields = await this.getSearchableFields(collectionSlug);
-			const config = await this.getSearchConfig(collectionSlug);
 			if (fields.length > 0) {
 				await this.rebuildIndex(collectionSlug, fields, config?.weights);
 			}

package/src/search/query.ts

@@ -26,6 +26,23 @@ const WHITESPACE_SPLIT_PATTERN = /\s+/;
 const FTS_OPERATORS_PATTERN = /\b(AND|OR|NOT|NEAR)\b/i;
 const DOUBLE_QUOTE_PATTERN = /"/g;
 
+/**
+ * Detect FTS5 query syntax errors. Match specifically on the SQLite FTS5
+ * error fingerprints rather than a broad "fts5" / "syntax error" filter
+ * (which would also swallow internal table-corruption errors). The two
+ * fingerprints we care about are:
+ *
+ *  - "fts5: syntax error near …" — unbalanced quotes, stray operators,
+ *    other malformed user input
+ *  - "unknown special query: …" — bare special tokens like `^*` that
+ *    parse but don't resolve to a real FTS5 directive
+ */
+function isFts5SyntaxError(error: unknown): boolean {
+	if (!(error instanceof Error)) return false;
+	const message = error.message.toLowerCase();
+	return message.includes("fts5: syntax error") || message.includes("unknown special query");
+}
+
 /**
  * Search across multiple collections
  *
@@ -198,14 +215,16 @@ async function searchSingleCollection(
 	const bm25Expr = bm25Args ? `bm25("${ftsTable}", ${bm25Args})` : `bm25("${ftsTable}")`;
 
 	// Snippet column index is 2 (after id=0, locale=1, first searchable field=2)
-	const results = await sql<{
-		id: string;
-		slug: string | null;
-		locale: string;
-		title: string | null;
-		snippet: string;
-		score: number;
-	}>`
+	let results;
+	try {
+		results = await sql<{
+			id: string;
+			slug: string | null;
+			locale: string;
+			title: string | null;
+			snippet: string | null;
+			score: number;
+		}>`
 		SELECT 
 			c.id,
 			c.slug,
@@ -222,6 +241,20 @@ async function searchSingleCollection(
 		ORDER BY score
 		LIMIT ${limit}
 	`.execute(db);
+	} catch (error) {
+		// FTS5 returns syntax errors for queries with unbalanced quotes,
+		// stray operators, or other malformed input. Treat these as
+		// "no matches" so the user gets an empty result rather than an
+		// internals-leaking error. Other errors (table missing, IO) still
+		// propagate. Intentionally not logged: any anonymous client can
+		// trigger this path, and the underlying error message embeds the
+		// raw query, so logging would be both noisy and a log-injection
+		// vector.
+		if (isFts5SyntaxError(error)) {
+			return [];
+		}
+		throw error;
+	}
 
 	return results.rows.map((row) => ({
 		collection,
@@ -229,11 +262,51 @@ async function searchSingleCollection(
 		slug: row.slug,
 		locale: row.locale,
 		title: row.title ?? undefined,
-		snippet: row.snippet,
+		// SQLite's snippet() returns NULL when the targeted column is
+		// NULL for that row — even if the row matched via a different
+		// searchable column. Skip sanitization in that case so we don't
+		// throw on `null.replace`. The SearchResult.snippet field is
+		// already optional, so omitting it is the documented contract.
+		snippet: row.snippet === null ? undefined : sanitizeSnippet(row.snippet),
 		score: Math.abs(row.score), // bm25 returns negative scores
 	}));
 }
 
+// Module-scope regexes so the engine doesn't recompile per call —
+// snippet sanitization runs on every search result.
+const SNIPPET_AMP_RE = /&/g;
+const SNIPPET_LT_RE = /</g;
+const SNIPPET_GT_RE = />/g;
+const SNIPPET_QUOT_RE = /"/g;
+const SNIPPET_APOS_RE = /'/g;
+
+/**
+ * Make an FTS5 snippet safe to render with `set:html` / `innerHTML`.
+ *
+ * SQLite's `snippet()` function splices literal `<mark>` and `</mark>`
+ * markers around matched terms but does not escape the surrounding
+ * source text. Posts that legitimately contain `<`, `>`, `&`, `"` or
+ * `'` would render as broken markup, and a `<script>` literal in a
+ * title (or any other indexed field) would execute when displayed.
+ *
+ * The fix: HTML-escape the whole string, which turns the markers into
+ * `&lt;mark&gt;` / `&lt;/mark&gt;`. Then restore those two patterns to
+ * their original tag form. The result is "the indexed text with all
+ * HTML metacharacters escaped, plus a small set of literal `<mark>`
+ * highlight tags around matched terms" — which matches the API's
+ * documented contract.
+ */
+function sanitizeSnippet(snippet: string): string {
+	return snippet
+		.replace(SNIPPET_AMP_RE, "&amp;")
+		.replace(SNIPPET_LT_RE, "&lt;")
+		.replace(SNIPPET_GT_RE, "&gt;")
+		.replace(SNIPPET_QUOT_RE, "&quot;")
+		.replace(SNIPPET_APOS_RE, "&#39;")
+		.replaceAll("&lt;mark&gt;", "<mark>")
+		.replaceAll("&lt;/mark&gt;", "</mark>");
+}
+
 /**
  * Get search suggestions for autocomplete
  *
@@ -282,23 +355,35 @@ export async function getSuggestions(
 			continue;
 		}
 
-		const results = await sql<{
-			id: string;
-			title: string;
-		}>`
-			SELECT 
-				c.id,
-				c.title
-			FROM "${sql.raw(ftsTable)}" f
-			JOIN "${sql.raw(contentTable)}" c ON f.id = c.id
-			WHERE "${sql.raw(ftsTable)}" MATCH ${prefixQuery}
-			AND c.status = 'published'
-			AND c.deleted_at IS NULL
-			AND c.title IS NOT NULL
-			${locale ? sql`AND c.locale = ${locale}` : sql``}
-			ORDER BY bm25("${sql.raw(ftsTable)}")
-			LIMIT ${limit}
-		`.execute(db);
+		let results;
+		try {
+			results = await sql<{
+				id: string;
+				title: string;
+			}>`
+				SELECT 
+					c.id,
+					c.title
+				FROM "${sql.raw(ftsTable)}" f
+				JOIN "${sql.raw(contentTable)}" c ON f.id = c.id
+				WHERE "${sql.raw(ftsTable)}" MATCH ${prefixQuery}
+				AND c.status = 'published'
+				AND c.deleted_at IS NULL
+				AND c.title IS NOT NULL
+				${locale ? sql`AND c.locale = ${locale}` : sql``}
+				ORDER BY bm25("${sql.raw(ftsTable)}")
+				LIMIT ${limit}
+			`.execute(db);
+		} catch (error) {
+			// Same swallow as searchSingleCollection: malformed prefix
+			// queries should yield no suggestions, not surface DB errors.
+			// Intentionally not logged (anonymous-triggerable, echoes
+			// user input -- see searchSingleCollection for rationale).
+			if (isFts5SyntaxError(error)) {
+				continue;
+			}
+			throw error;
+		}
 
 		for (const row of results.rows) {
 			suggestions.push({

package/src/search/types.ts

@@ -58,7 +58,14 @@ export interface SearchResult {
 	locale: string;
 	/** Entry title (if available) */
 	title?: string;
-	/** Highlighted snippet showing match context */
+	/**
+	 * Highlighted snippet showing match context.
+	 *
+	 * Sanitized server-side to be safe for `set:html` / `innerHTML`:
+	 * all HTML metacharacters in the source text are escaped, and
+	 * matched terms are wrapped in literal `<mark>...</mark>` tags
+	 * (the only HTML the snippet is allowed to contain).
+	 */
 	snippet?: string;
 	/** Relevance score (higher = more relevant) */
 	score: number;

package/src/sections/index.ts

@@ -137,17 +137,15 @@ export async function getSectionsWithDb(
 	// Order by title ASC, id ASC for stable cursor pagination
 	query = query.orderBy("title", "asc").orderBy("id", "asc");
 
-	// Cursor-based pagination
+	// Cursor-based pagination — throws on invalid cursor.
 	if (options.cursor) {
 		const decoded = decodeCursor(options.cursor);
-		if (decoded) {
-			query = query.where((eb) =>
-				eb.or([
-					eb("title", ">", decoded.orderValue),
-					eb.and([eb("title", "=", decoded.orderValue), eb("id", ">", decoded.id)]),
-				]),
-			);
-		}
+		query = query.where((eb) =>
+			eb.or([
+				eb("title", ">", decoded.orderValue),
+				eb.and([eb("title", "=", decoded.orderValue), eb("id", ">", decoded.id)]),
+			]),
+		);
 	}
 
 	query = query.limit(limit + 1);

package/src/seed/apply.ts

@@ -927,6 +927,8 @@ async function applyWidget(
 			sort_order: sortOrder,
 			type: widget.type,
 			title: widget.title ?? null,
+			// `widget.content` is Portable Text for content-type widgets;
+			// for other widget kinds it's null.
 			content: widget.content ? JSON.stringify(widget.content) : null,
 			menu_name: widget.menuName ?? null,
 			component_id: widget.componentId ?? null,

package/src/settings/index.ts

@@ -18,6 +18,53 @@ import type { SiteSettings, SiteSettingKey, MediaReference } from "./types.js";
 /** Prefix for site settings in the options table */
 const SETTINGS_PREFIX = "site:";
 
+/**
+ * Worker-isolate cache for the resolved `site:*` settings.
+ *
+ * Site settings (title, logo, SEO defaults) change rarely but are read on
+ * every public request. Caching across the isolate's lifetime drops the
+ * `options WHERE name LIKE 'site:%'` prefix scan from once-per-request to
+ * once-per-isolate. Cross-isolate staleness is bounded by isolate lifetime
+ * (workerd typically recycles within minutes); acceptable for chrome.
+ *
+ * Stored on globalThis with a Symbol.for key so Vite SSR chunk duplication
+ * doesn't produce two independent caches (same pattern as request-context.ts).
+ *
+ * Invalidation: every `site:*` write bumps `version`. Reads compare the
+ * cached promise's version against the current version and refetch on
+ * mismatch. Caching the promise (not the resolved value) lets concurrent
+ * cold-isolate readers share the in-flight query.
+ */
+interface SiteSettingsHolder {
+	version: number;
+	cached: Promise<Partial<SiteSettings>> | null;
+	cachedVersion: number;
+}
+
+const SITE_SETTINGS_CACHE_KEY = Symbol.for("emdash:site-settings");
+const g = globalThis as Record<symbol, unknown>;
+const holder: SiteSettingsHolder =
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- globalThis singleton pattern (see request-context.ts)
+	(g[SITE_SETTINGS_CACHE_KEY] as SiteSettingsHolder | undefined) ??
+	(() => {
+		const h: SiteSettingsHolder = { version: 0, cached: null, cachedVersion: -1 };
+		g[SITE_SETTINGS_CACHE_KEY] = h;
+		return h;
+	})();
+
+/**
+ * Bump the isolate-wide site-settings cache version, forcing the next
+ * `getSiteSettings()` to re-query the database.
+ *
+ * Called from every `site:*` write path. Other isolates still serve their
+ * own cached copy until they expire — staleness bounded by isolate lifetime.
+ */
+export function invalidateSiteSettingsCache(): void {
+	holder.version++;
+	holder.cached = null;
+	holder.cachedVersion = -1;
+}
+
 /**
  * Type guard for MediaReference values
  */
@@ -26,13 +73,18 @@ function isMediaReference(value: unknown): value is MediaReference {
 }
 
 /**
- * Resolve a media reference to include the full URL
+ * Resolve a media reference to include the full URL plus content metadata.
+ *
+ * Pulls `mimeType` and intrinsic dimensions from the media row so callers
+ * can emit correct head tags (e.g. `<link rel="icon" type="image/svg+xml">`,
+ * which Chromium requires when the URL has no `.svg` extension) without
+ * a second round-trip to the media table.
  */
 async function resolveMediaReference(
 	mediaRef: MediaReference | undefined,
 	db: Kysely<Database>,
 	_storage: Storage | null,
-): Promise<(MediaReference & { url?: string }) | undefined> {
+): Promise<MediaReference | undefined> {
 	if (!mediaRef?.mediaId) {
 		return mediaRef;
 	}
@@ -46,6 +98,9 @@ async function resolveMediaReference(
 			return {
 				...mediaRef,
 				url: `/_emdash/api/media/file/${media.storageKey}`,
+				contentType: media.mimeType,
+				...(media.width !== null ? { width: media.width } : {}),
+				...(media.height !== null ? { height: media.height } : {}),
 			};
 		}
 	} catch {
@@ -142,9 +197,24 @@ export async function getSiteSettingWithDb<K extends SiteSettingKey>(
  * ```
  */
 export function getSiteSettings(): Promise<Partial<SiteSettings>> {
-	return requestCached("siteSettings", async () => {
-		const db = await getDb();
-		return getSiteSettingsWithDb(db);
+	return requestCached("siteSettings", () => {
+		const versionAtCall = holder.version;
+		if (holder.cached && holder.cachedVersion === versionAtCall) {
+			return holder.cached;
+		}
+		const fetchPromise = (async () => {
+			const db = await getDb();
+			return getSiteSettingsWithDb(db);
+		})().catch((error) => {
+			if (holder.cached === fetchPromise) {
+				holder.cached = null;
+				holder.cachedVersion = -1;
+			}
+			throw error;
+		});
+		holder.cached = fetchPromise;
+		holder.cachedVersion = versionAtCall;
+		return fetchPromise;
 	});
 }
 
@@ -218,7 +288,11 @@ export async function setSiteSettings(
 		}
 	}
 
-	await options.setMany(updates);
+	try {
+		await options.setMany(updates);
+	} finally {
+		invalidateSiteSettingsCache();
+	}
 }
 
 /**

package/src/settings/types.ts

@@ -4,10 +4,32 @@
  * Global configuration for the site (title, logo, social links, etc.)
  */
 
-/** Media reference for logo/favicon */
+/**
+ * Media reference for logo/favicon.
+ *
+ * Stored shape is just `{ mediaId, alt? }`. The remaining fields are
+ * populated by `resolveMediaReference` on read so templates can emit
+ * correct head tags without a second round-trip to the media table.
+ *
+ * The Zod schemas at the REST/MCP boundary (`mediaReference`) define
+ * only `mediaId` and `alt` and rely on default strip-mode parsing to
+ * discard the resolved fields if a client posts them back. If you
+ * ever switch those schemas to `passthrough`, you must also strip the
+ * resolved fields explicitly in `setSiteSettings`, or stored options
+ * will accumulate stale `url` / `contentType` / `width` / `height`
+ * snapshots.
+ */
 export interface MediaReference {
 	mediaId: string;
 	alt?: string;
+	/** Resolved URL. Populated by `resolveMediaReference`; absent on raw stored values. */
+	url?: string;
+	/** Stored MIME type (e.g. `image/svg+xml`). Populated alongside `url`. */
+	contentType?: string;
+	/** Pixel width if known. Populated alongside `url`. */
+	width?: number;
+	/** Pixel height if known. Populated alongside `url`. */
+	height?: number;
 }
 
 /** Site-level SEO settings */

package/src/storage/s3.ts

@@ -7,6 +7,7 @@
 
 import {
 	S3Client,
+	type S3ClientConfig,
 	PutObjectCommand,
 	GetObjectCommand,
 	DeleteObjectCommand,
@@ -131,9 +132,14 @@ export class S3Storage implements Storage {
 		this.publicUrl = config.publicUrl;
 		this.endpoint = config.endpoint;
 
-		this.client = new S3Client({
+		// S3ClientConfig types `credentials` as required, but the SDK accepts
+		// omitted credentials at runtime (falls back to the provider chain).
+		/* eslint-disable typescript-eslint(no-unsafe-type-assertion) -- upstream @aws-sdk/client-s3 overstates required fields */
+		const clientConfig = {
 			endpoint: config.endpoint,
 			region: config.region || "auto",
+			// Required for R2 and some S3-compatible services
+			forcePathStyle: true,
 			...(config.accessKeyId && config.secretAccessKey
 				? {
 						credentials: {
@@ -142,9 +148,9 @@ export class S3Storage implements Storage {
 						},
 					}
 				: {}),
-			// Required for R2 and some S3-compatible services
-			forcePathStyle: true,
-		} as ConstructorParameters<typeof S3Client>[0]);
+		} as S3ClientConfig;
+		/* eslint-enable typescript-eslint(no-unsafe-type-assertion) */
+		this.client = new S3Client(clientConfig);
 	}
 
 	async upload(options: {
@@ -317,8 +323,8 @@ export class S3Storage implements Storage {
 		if (this.publicUrl) {
 			return `${this.publicUrl.replace(TRAILING_SLASH_PATTERN, "")}/${key}`;
 		}
-		// Default to endpoint + bucket + key
-		return `${this.endpoint.replace(TRAILING_SLASH_PATTERN, "")}/${this.bucket}/${key}`;
+		// No public URL configured; defer to the /_emdash/api/media/file route.
+		return `/_emdash/api/media/file/${key}`;
 	}
 }