@growth-labs/cms 0.8.8 → 0.8.14

package/src/migration-vendor.ts

@@ -119,26 +119,149 @@ function sequencePrefix(sequence: number): string {
 	return String(sequence).padStart(4, '0')
 }
 
+function targetSequence(target: string): number {
+	return Number.parseInt(target.slice(0, 4), 10)
+}
+
+function managedSuffix(source: string): string {
+	return `_growth_labs_cms_${source.replace(/^\d{4}_/, '')}`
+}
+
+/**
+ * Sequences already spoken for in the consumer's migrations directory.
+ *
+ * Wrangler accepts one `migrations_dir`, so a consumer's own analytics, SEO or
+ * product migrations are interleaved with the vendored package ones. Those
+ * numbers are not ours to take.
+ */
+async function occupiedSequences(migrationsDir: string): Promise<Set<number>> {
+	const names = await readdir(migrationsDir)
+	const taken = new Set<number>()
+	for (const name of names) {
+		if (!name.endsWith('.sql')) continue
+		const sequence = targetSequence(name)
+		if (Number.isSafeInteger(sequence)) taken.add(sequence)
+	}
+	return taken
+}
+
+interface PlanContext {
+	/** Recorded source -> target, the authority for anything already vendored. */
+	recorded: Map<string, CmsMigrationManifestEntry>
+	/** Existing consumer files, for sequence avoidance and hash adoption. */
+	migrationsDir?: string
+}
+
+/**
+ * Resolve each package migration to the consumer filename it must occupy.
+ *
+ * The hard invariant: a migration this consumer has ALREADY vendored keeps its
+ * exact filename forever. D1's `d1_migrations` ledger keys off that name, so
+ * renumbering an applied migration would re-run it. Every branch below either
+ * reuses a name or allocates an unused one; none ever rewrites an assigned one.
+ *
+ * Resolution order per source:
+ *   1. recorded in the receipt  -> reuse that target verbatim;
+ *   2. an on-disk file with our managed suffix whose bytes hash identical
+ *      -> adopt it (reconciles migrations vendored by hand before the receipt
+ *      existed, without creating a duplicate that would apply the same SQL
+ *      twice);
+ *   3. otherwise -> the next sequence above everything already assigned or
+ *      occupied, skipping consumer-owned numbers.
+ */
 async function planMigrations(
 	sourceDir: string,
 	startSequence: number,
+	context: PlanContext = { recorded: new Map() },
 ): Promise<PlannedMigration[]> {
 	assertStartSequence(startSequence)
 	const sourceNames = (await readdir(sourceDir)).filter((name) => MIGRATION_FILE.test(name)).sort()
 	if (sourceNames.length === 0) throw new Error('installed CMS package has no migration SQL')
-	if (startSequence + sourceNames.length - 1 > 9999) {
-		throw new Error('reserved CMS migration sequence exceeds 9999')
+
+	const occupied = context.migrationsDir
+		? await occupiedSequences(context.migrationsDir)
+		: new Set<number>()
+	const existingNames = context.migrationsDir ? await readdir(context.migrationsDir) : []
+	const assigned = new Set<number>()
+	let highWater = startSequence - 1
+	for (const sequence of occupied) {
+		if (sequence > highWater) highWater = sequence
 	}
 
-	return Promise.all(
-		sourceNames.map(async (source, index) => {
-			const sequence = startSequence + index
-			const suffix = source.replace(/^\d{4}_/, '')
-			const target = `${sequencePrefix(sequence)}_growth_labs_cms_${suffix}`
-			const bytes = new Uint8Array(await readFile(join(sourceDir, source)))
-			return { source, target, sequence, sha256: await sha256(bytes), bytes }
-		}),
-	)
+	const planned: PlannedMigration[] = []
+	for (const source of sourceNames) {
+		const bytes = new Uint8Array(await readFile(join(sourceDir, source)))
+		const hash = await sha256(bytes)
+		const suffix = managedSuffix(source)
+
+		const recorded = context.recorded.get(source)
+		if (recorded) {
+			const sequence = targetSequence(recorded.target)
+			assigned.add(sequence)
+			if (sequence > highWater) highWater = sequence
+			planned.push({ source, target: recorded.target, sequence, sha256: hash, bytes })
+			continue
+		}
+
+		const adopted = await findAdoptableTarget(
+			context.migrationsDir,
+			existingNames,
+			suffix,
+			hash,
+			assigned,
+		)
+		if (adopted) {
+			const sequence = targetSequence(adopted)
+			assigned.add(sequence)
+			if (sequence > highWater) highWater = sequence
+			planned.push({ source, target: adopted, sequence, sha256: hash, bytes })
+			continue
+		}
+
+		let sequence = Math.max(startSequence, highWater + 1)
+		while (occupied.has(sequence) || assigned.has(sequence)) sequence += 1
+		if (sequence > 9999) throw new Error('reserved CMS migration sequence exceeds 9999')
+		assigned.add(sequence)
+		highWater = sequence
+		planned.push({
+			source,
+			target: `${sequencePrefix(sequence)}${suffix}`,
+			sequence,
+			sha256: hash,
+			bytes,
+		})
+	}
+
+	return planned
+}
+
+/**
+ * An existing consumer file that IS this package migration, byte for byte.
+ *
+ * Content-addressed on purpose: adopting by filename alone would let an
+ * unrelated file with a colliding suffix be claimed as ours.
+ */
+async function findAdoptableTarget(
+	migrationsDir: string | undefined,
+	existingNames: string[],
+	suffix: string,
+	hash: string,
+	assigned: Set<number>,
+): Promise<string | null> {
+	if (!migrationsDir) return null
+	for (const name of existingNames.slice().sort()) {
+		if (!name.endsWith('.sql') || !name.endsWith(`${suffix}`)) continue
+		const sequence = targetSequence(name)
+		if (!Number.isSafeInteger(sequence) || assigned.has(sequence)) continue
+		let existingHash: string
+		try {
+			existingHash = await sha256(new Uint8Array(await readFile(join(migrationsDir, name))))
+		} catch {
+			continue
+		}
+		if (existingHash === hash) return name
+	}
+	return null
 }
 
 function manifestFor(
@@ -365,9 +488,15 @@ export async function syncCmsMigrations(
 	const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath)
 	return withManifestLock(manifestPath, async () => {
 		const contract = await packageContract()
-		const plan = await planMigrations(contract.sourceDir, options.startSequence)
-		const nextManifest = manifestFor(contract.packageVersion, options.startSequence, plan)
 		const currentManifest = await readManifest(manifestPath)
+		// The receipt is the authority for anything already vendored: plan with it
+		// so recorded migrations keep their exact filenames and only genuinely new
+		// ones are allocated a sequence.
+		const plan = await planMigrations(contract.sourceDir, options.startSequence, {
+			recorded: new Map((currentManifest?.files ?? []).map((entry) => [entry.source, entry])),
+			migrationsDir,
+		})
+		const nextManifest = manifestFor(contract.packageVersion, options.startSequence, plan)
 		assertManifestCanAdvance(currentManifest, nextManifest)
 		await assertNoSequenceCollisions(migrationsDir, plan)
 		const preflight = await verifyTargets(migrationsDir, plan, true)
@@ -424,7 +553,10 @@ export async function verifyCmsMigrations(
 				`CMS migration manifest version ${manifest.packageVersion} does not match installed ${contract.packageVersion}`,
 			)
 		}
-		const plan = await planMigrations(contract.sourceDir, manifest.startSequence)
+		const plan = await planMigrations(contract.sourceDir, manifest.startSequence, {
+			recorded: new Map(manifest.files.map((entry) => [entry.source, entry])),
+			migrationsDir,
+		})
 		const expected = manifestFor(contract.packageVersion, manifest.startSequence, plan)
 		if (
 			expected.files.length !== manifest.files.length ||

package/src/routes/content.ts

@@ -1140,6 +1140,72 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 		}
 	}
 
+	/**
+	 * The video sibling of maybeDispatchPodcastToFoundry: capture a sourced video
+	 * that holds no capture. A row with no trigger token is invisible to the
+	 * producer whatever its state says (trash and restore clears the token and
+	 * leaves `queued`), so only `ready` media and `failed` — the editor's Re-run
+	 * decision — are left alone. An archived item is inactive to the dispatcher;
+	 * it is captured once scheduling has made it active again.
+	 * The editor form captures after a save too, but it de-dupes on local state; a
+	 * later save that reset the capture left the video scheduled and never
+	 * prepared, with nothing to notice (Fronts, 2026-09-15..17).
+	 */
+	async function maybeCaptureVideoSource(
+		ctx: RouteContext,
+		contentId: string,
+	): Promise<DispatchResult | null> {
+		const hook = resolved.hooks.foundryVideo
+		if (!hook) return null
+		const readCapture = () =>
+			ctx.db
+				.prepare(
+					`SELECT vc.processing_source_url, vc.processing_trigger_token, vc.processing_state,
+						vc.hls_ready, ci.status
+					FROM video_content vc JOIN content_items ci ON ci.id = vc.content_id
+					WHERE vc.content_id = ?
+					LIMIT 1`,
+				)
+				.bind(contentId)
+				.first<{
+					processing_source_url: string | null
+					processing_trigger_token: string | null
+					processing_state: string | null
+					hls_ready: number | null
+					status: string
+				}>()
+		const row = await readCapture()
+		if (!row?.processing_source_url?.trim()) return null
+		if (row.processing_trigger_token?.trim()) return null
+		if (row.status === 'archived') return null
+		if (row.hls_ready === 1) return null
+		if (row.processing_state === 'ready' || row.processing_state === 'failed') return null
+		try {
+			return await dispatchToFoundry(ctx.db, contentId, hook, { ifUncaptured: true })
+		} catch (error) {
+			// The editor form fires its own capture after every save. Losing that
+			// race fails this call's compare-and-set, and the capture exists.
+			const raced = await readCapture()
+			if (raced?.processing_trigger_token?.trim()) return null
+			throw error
+		}
+	}
+
+	async function captureScheduledVideoAfterSave(
+		ctx: RouteContext,
+		contentId: string,
+	): Promise<PodcastFoundryAttempt> {
+		try {
+			return { result: await maybeCaptureVideoSource(ctx, contentId), reason: null }
+		} catch (error) {
+			if (error instanceof FoundryDispatchPrerequisiteError) {
+				return { result: null, reason: 'missing_duration' }
+			}
+			console.error('Scheduled video source capture failed after content save', error)
+			return { result: null, reason: 'dispatch_failed' }
+		}
+	}
+
 	function missingDurationResponse(): Response {
 		return json(
 			{
@@ -1422,6 +1488,33 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				const publishAtSeconds = Math.floor(publishAtMs / 1000)
 				const expectedTargets = new Map<string, ScheduleFrontsChannelTargets | undefined>()
 				for (const id of ids) {
+					// Same gate as the single-item path: no item in a bulk schedule
+					// may take a slot with a body publish will refuse.
+					const bulkGuard = await evaluateContentBodyForPublish(ctx.db, id, 'cms.schedule', {
+						requireBody: false,
+					})
+					if (bulkGuard && !bulkGuard.ok) {
+						return json(
+							{
+								error: 'Article body failed pre-publish validation',
+								source: 'cms.schedule',
+								contentId: id,
+								errors: bulkGuard.errors,
+							},
+							422,
+						)
+					}
+					// And the same capture guarantee: no sourced video in a bulk
+					// schedule may take a slot the producer cannot see.
+					try {
+						await maybeCaptureVideoSource(ctx, id)
+					} catch (error) {
+						if (error instanceof FoundryDispatchPrerequisiteError) {
+							return missingDurationResponse()
+						}
+						console.error('Video source capture failed before bulk schedule', error)
+						return json({ error: 'Foundry dispatch failed', contentId: id }, 502)
+					}
 					const prepared = await prepareScheduleTargets(ctx, id)
 					if ('error' in prepared) return prepared.error
 					expectedTargets.set(id, prepared.targets)
@@ -1433,6 +1526,8 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 					if (targets !== undefined && !changed) {
 						return json({ error: 'schedule_targets_changed', contentId: id, scheduled }, 409)
 					}
+					// Covers an item that was archived above, now active again.
+					await captureScheduledVideoAfterSave(ctx, id)
 					scheduled.push(id)
 				}
 				return json({ scheduled })
@@ -1738,6 +1833,12 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				existing.type === 'podcast'
 					? await dispatchPodcastAfterSave(ctx, id)
 					: { result: null, reason: null }
+			// A scheduled video is committed to a slot: a save that reset its capture
+			// must not leave it unprepared until someone notices the missed publish.
+			const videoAttempt: PodcastFoundryAttempt =
+				existing.type === 'video' && existing.status === 'scheduled'
+					? await captureScheduledVideoAfterSave(ctx, id)
+					: { result: null, reason: null }
 
 			// If the slug changed, record the old slug as a redirect (spec §8)
 			// and drop any stale redirect row for the now-live slug — atomically,
@@ -1752,6 +1853,8 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				podcastFoundryQueued: Boolean(podcastAttempt.result),
 				podcastFoundryCorrelationId: podcastAttempt.result?.correlationId ?? null,
 				podcastFoundryReason: podcastAttempt.reason,
+				videoFoundryQueued: Boolean(videoAttempt.result && !videoAttempt.result.skipped),
+				videoFoundryReason: videoAttempt.reason,
 				...(mediaSourceReadiness ? { mediaSourceReadiness } : {}),
 				// Present and empty when the body linted clean, so a client can
 				// distinguish "no warnings" from "this build does not report them".
@@ -1808,6 +1911,41 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 					return json({ error: 'Missing publish time' }, 400)
 				}
 
+				// A body the publish guard will refuse must not be allowed to take a
+				// slot. Scheduling was the one write in this lane that never ran
+				// the guard, so a defect an editor could not see at save time
+				// surfaced only when foundryd tried to publish — at 16:30 on a
+				// Monday, as a missed premium article (2026-09-15).
+				const scheduleGuard = await evaluateContentBodyForPublish(ctx.db, id, 'cms.schedule', {
+					// Claiming a slot before the piece is written stays allowed;
+					// claiming one with an already-broken body does not.
+					requireBody: false,
+				})
+				if (scheduleGuard && !scheduleGuard.ok) {
+					return json(
+						{
+							error: 'Article body failed pre-publish validation',
+							source: 'cms.schedule',
+							errors: scheduleGuard.errors,
+						},
+						422,
+					)
+				}
+				// A sourced video that holds no capture is invisible to the producer:
+				// it would take the slot and never publish. Capture it here, and refuse
+				// the slot if that cannot be done. A video with no source yet may still
+				// claim a slot early.
+				if (existing.type === 'video') {
+					try {
+						await maybeCaptureVideoSource(ctx, id)
+					} catch (error) {
+						if (error instanceof FoundryDispatchPrerequisiteError) {
+							return missingDurationResponse()
+						}
+						console.error('Video source capture failed before schedule', error)
+						return json({ error: 'Foundry dispatch failed' }, 502)
+					}
+				}
 				const prepared = await prepareScheduleTargets(ctx, id)
 				if ('error' in prepared) return prepared.error
 				const changed = await scheduleContent(
@@ -1820,6 +1958,8 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				if (prepared.targets !== undefined && !changed) {
 					return json({ error: 'schedule_targets_changed', contentId: id }, 409)
 				}
+				// Covers an item that was archived above, now active again.
+				if (existing.type === 'video') await captureScheduledVideoAfterSave(ctx, id)
 
 				// Fire content.scheduled webhook.
 				await fireWebhook(ctx, 'content.scheduled', {
@@ -1835,6 +1975,10 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			if (action === 'publish') {
 				const now = Math.floor(Date.now() / 1000)
 				const wasDraft = existing.status === 'draft'
+				const publishedAt =
+					existing.status === 'published' && existing.published_at !== null
+						? existing.published_at
+						: now
 				let podcastDispatch: DispatchResult | null = null
 				if (existing.type === 'podcast') {
 					try {
@@ -1929,7 +2073,7 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 					throw error
 				}
 				try {
-					await publishContent(ctx.db, id, now)
+					await publishContent(ctx.db, id, publishedAt, now)
 					await createRevision(ctx.db, id, ctx.userId || null)
 				} catch (error) {
 					if (error instanceof TagInputError) return tagInputErrorResponse(error)

package/src/ui/editor/ContentForm.tsx

@@ -485,7 +485,7 @@ export function ContentForm({
 						setForm((prev) => ({
 							...prev,
 							saving: false,
-							saveError: err.error ?? 'Save failed',
+							saveError: apiErrorMessage(err, 'Save failed'),
 						}))
 						return
 					}

package/src/ui/editor/editor-media-upload.ts

@@ -1,3 +1,4 @@
+import { apiErrorMessage } from '../api-error.js'
 import { slugifyTitle } from './content-payload.js'
 
 type FetchLike = (url: string, init?: RequestInit) => Promise<Response>
@@ -17,7 +18,7 @@ export async function uploadEditorImage(
 	})
 	if (!res.ok) {
 		const err = (await res.json().catch(() => ({ error: res.statusText }))) as { error?: string }
-		throw new Error(err.error ?? 'Image upload failed')
+		throw new Error(apiErrorMessage(err, 'Image upload failed'))
 	}
 	const body = (await res.json()) as { url?: string; publicUrl?: string }
 	const url = body.url || body.publicUrl

package/src/ui/inspector/PublishTab.tsx

@@ -12,6 +12,7 @@
 
 import { useCallback, useEffect, useState } from 'react'
 import type { ContentStatus } from '../../schema/types.js'
+import { apiErrorMessage } from '../api-error.js'
 import { Icon } from '../icons.js'
 import { Field } from './Field.js'
 import {
@@ -246,7 +247,7 @@ export function PublishTab({
 				const err = (await res.json().catch(() => ({ error: res.statusText }))) as {
 					error?: string
 				}
-				throw new Error(err.error ?? 'Could not add author')
+				throw new Error(apiErrorMessage(err, 'Could not add author'))
 			}
 			const created = (await res.json()) as CreatedAuthorResponse
 			const nextAuthor = { id: created.id, name }

package/src/ui/screens/LibraryScreen.tsx

@@ -12,6 +12,7 @@
 
 import { useCallback, useEffect, useReducer, useRef, useState } from 'react'
 import type { ContentStatus, ContentType, FrontsPublishStatus } from '../../schema/types.js'
+import { apiErrorMessage } from '../api-error.js'
 import { buildSharePrefill, ShareModal } from '../components/ShareModal.js'
 import { Icon } from '../icons.js'
 import { useWorkspace } from '../workspace-context.js'
@@ -1139,7 +1140,7 @@ function BulkBar({
 				const err = (await res.json().catch(() => ({ error: res.statusText }))) as {
 					error?: string
 				}
-				alert(`Bulk ${op} failed: ${err.error ?? res.statusText}`)
+				alert(`Bulk ${op} failed: ${apiErrorMessage(err, res.statusText)}`)
 				setBusy(false)
 				return
 			}
@@ -1241,7 +1242,7 @@ function ImportModal({
 				const err = (await res.json().catch(() => ({ error: res.statusText }))) as {
 					error?: string
 				}
-				setError(err.error ?? 'Parse failed')
+				setError(apiErrorMessage(err, 'Parse failed'))
 				return
 			}
 			const data = (await res.json()) as ParseResult
@@ -1266,7 +1267,7 @@ function ImportModal({
 				const err = (await res.json().catch(() => ({ error: res.statusText }))) as {
 					error?: string
 				}
-				setError(err.error ?? 'Confirm failed')
+				setError(apiErrorMessage(err, 'Confirm failed'))
 				setStep('preview')
 				return
 			}

package/src/ui/screens/SettingsScreen.tsx

@@ -24,6 +24,7 @@
 import { useCallback, useEffect, useReducer, useState } from 'react'
 import type { ApiKeyListEntry } from '../../engine/api-keys.js'
 import { WEBHOOK_EVENTS, type WebhookRecord } from '../../engine/webhooks.js'
+import { apiErrorMessage } from '../api-error.js'
 import { Icon } from '../icons.js'
 import { useWorkspace } from '../workspace-context.js'
 import {
@@ -552,7 +553,7 @@ function TeamSettings({ currentSubject }: { currentSubject: string | null }) {
 			const res = await fetch('/admin/api/settings/members')
 			if (!res.ok) {
 				const body = (await res.json().catch(() => ({}))) as { error?: string }
-				dispatch({ type: 'fetch-error', error: body.error ?? `HTTP ${res.status}` })
+				dispatch({ type: 'fetch-error', error: apiErrorMessage(body, `HTTP ${res.status}`) })
 				return
 			}
 			const body = (await res.json()) as {
@@ -600,7 +601,7 @@ function TeamSettings({ currentSubject }: { currentSubject: string | null }) {
 			})
 			if (!res.ok) {
 				const body = (await res.json().catch(() => ({}))) as { error?: string; reason?: string }
-				alert(body.reason ?? body.error ?? `Failed to change role (HTTP ${res.status})`)
+				alert(body.reason ?? apiErrorMessage(body, `Failed to change role (HTTP ${res.status})`))
 				return
 			}
 			dispatch({ type: 'update-role', userId, role: newRole })
@@ -629,7 +630,7 @@ function TeamSettings({ currentSubject }: { currentSubject: string | null }) {
 				error?: string
 			}
 			if (!res.ok) {
-				setInviteError(body.error ?? `HTTP ${res.status}`)
+				setInviteError(apiErrorMessage(body, `HTTP ${res.status}`))
 				return
 			}
 			setInviteSuccess(
@@ -905,7 +906,7 @@ function ApiSettings() {
 			const res = await fetch('/admin/api/settings/api-keys')
 			if (!res.ok) {
 				const body = (await res.json().catch(() => ({}))) as { error?: string }
-				dispatch({ type: 'fetch-error', error: body.error ?? `HTTP ${res.status}` })
+				dispatch({ type: 'fetch-error', error: apiErrorMessage(body, `HTTP ${res.status}`) })
 				return
 			}
 			const body = (await res.json()) as { apiKeys: ApiKeyListEntry[] }
@@ -937,7 +938,7 @@ function ApiSettings() {
 				error?: string
 			}
 			if (!res.ok) {
-				setCreateError(body.error ?? `HTTP ${res.status}`)
+				setCreateError(apiErrorMessage(body, `HTTP ${res.status}`))
 				return
 			}
 			// Show the one-time reveal modal
@@ -965,7 +966,7 @@ function ApiSettings() {
 				dispatch({ type: 'revoked', id })
 			} else {
 				const body = (await res.json().catch(() => ({}))) as { error?: string }
-				alert(body.error ?? `Failed to revoke (HTTP ${res.status})`)
+				alert(apiErrorMessage(body, `Failed to revoke (HTTP ${res.status})`))
 			}
 		} catch (err) {
 			alert(String(err))
@@ -1158,7 +1159,7 @@ function WebhooksSettings() {
 			const res = await fetch('/admin/api/settings/webhooks')
 			if (!res.ok) {
 				const body = (await res.json().catch(() => ({}))) as { error?: string }
-				dispatch({ type: 'fetch-error', error: body.error ?? `HTTP ${res.status}` })
+				dispatch({ type: 'fetch-error', error: apiErrorMessage(body, `HTTP ${res.status}`) })
 				return
 			}
 			const body = (await res.json()) as { webhooks: WebhookRecord[] }
@@ -1185,7 +1186,7 @@ function WebhooksSettings() {
 			})
 			const body = (await res.json().catch(() => ({}))) as { error?: string }
 			if (!res.ok) {
-				setCreateError(body.error ?? `HTTP ${res.status}`)
+				setCreateError(apiErrorMessage(body, `HTTP ${res.status}`))
 				return
 			}
 			setNewUrl('')
@@ -1206,7 +1207,7 @@ function WebhooksSettings() {
 			})
 			const body = (await res.json().catch(() => ({}))) as { error?: string }
 			if (!res.ok) {
-				alert(body.error ?? `Test failed (HTTP ${res.status})`)
+				alert(apiErrorMessage(body, `Test failed (HTTP ${res.status})`))
 				return
 			}
 			dispatch({ type: 'update-status', id, status: 'test' })
@@ -1228,7 +1229,7 @@ function WebhooksSettings() {
 				dispatch({ type: 'deleted', id })
 			} else {
 				const body = (await res.json().catch(() => ({}))) as { error?: string }
-				alert(body.error ?? `Failed to delete (HTTP ${res.status})`)
+				alert(apiErrorMessage(body, `Failed to delete (HTTP ${res.status})`))
 			}
 		} catch (err) {
 			alert(String(err))
@@ -1481,7 +1482,7 @@ function IntegrationsSettings() {
 			.then(async (res) => {
 				if (!res.ok) {
 					const body = (await res.json().catch(() => ({}))) as { error?: string }
-					setError(body.error ?? `HTTP ${res.status}`)
+					setError(apiErrorMessage(body, `HTTP ${res.status}`))
 					return
 				}
 				const body = (await res.json()) as IntegrationsData
@@ -1600,7 +1601,7 @@ function DomainsSettings() {
 			.then(async (res) => {
 				if (!res.ok) {
 					const body = (await res.json().catch(() => ({}))) as { error?: string }
-					setError(body.error ?? `HTTP ${res.status}`)
+					setError(apiErrorMessage(body, `HTTP ${res.status}`))
 					return
 				}
 				const body = (await res.json()) as DomainsData
@@ -1728,7 +1729,7 @@ export function SettingsScreen() {
 			})
 			if (!res.ok) {
 				const body = (await res.json().catch(() => ({}))) as { error?: string }
-				alert(body.error ?? `Failed to save settings (HTTP ${res.status})`)
+				alert(apiErrorMessage(body, `Failed to save settings (HTTP ${res.status})`))
 				return
 			}
 			// Re-fetch to ensure the UI is in sync with server state

package/src/ui/screens/TopicsScreen.tsx

@@ -30,6 +30,7 @@
 // confirm dialog. NO classes outside the broadsheet vocabulary.
 
 import { useCallback, useEffect, useReducer, useState } from 'react'
+import { apiErrorMessage } from '../api-error.js'
 import { Icon } from '../icons.js'
 import {
 	buildTopicCreateBody,
@@ -191,7 +192,7 @@ export function TopicsScreen() {
 				error?: string
 			}
 			if (!res.ok || !body.topic) {
-				setCreateError(body.error || `${res.status} ${res.statusText}`)
+				setCreateError(apiErrorMessage(body, `${res.status} ${res.statusText}`))
 				return
 			}
 			dispatchTopics({ type: 'create-ok', topic: body.topic })
@@ -219,7 +220,7 @@ export function TopicsScreen() {
 				error?: string
 			}
 			if (!res.ok || !body.topic) {
-				setRenameError(body.error || `${res.status} ${res.statusText}`)
+				setRenameError(apiErrorMessage(body, `${res.status} ${res.statusText}`))
 				return
 			}
 			dispatchTopics({ type: 'rename-ok', fromSlug: pendingRename.slug, topic: body.topic })

package/src/ui/screens/author-recovery.ts

@@ -1,3 +1,5 @@
+import { apiErrorMessage } from '../api-error.js'
+
 interface AuthorWriteFailureBody {
 	error?: string
 	errorClass?: string
@@ -17,7 +19,7 @@ export function formatAuthorWriteFailure(
 		body.author?.id ? `author id: ${body.author.id}` : '',
 		body.author?.slug ? `slug: ${body.author.slug}` : '',
 	].filter(Boolean)
-	const message = body.error || 'Author synchronization failed'
+	const message = apiErrorMessage(body, 'Author synchronization failed')
 	const classifiedMessage = message.includes(body.errorClass)
 		? message
 		: `${body.errorClass}: ${message}`