From 2524381f1ec3a70af1e22d630d0c4939149304d4 Mon Sep 17 00:00:00 2001
From: Pier Dolique <github@perd.dev>
Date: Mon, 28 Sep 2026 21:29:44 +0300
Subject: [PATCH] feat(equipment): manage catalog brands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ✨ Add an admin page to search, create, edit, and delete brands
- 🐛 Keep brand changes and keyboard focus safe during loading and retry
- ♿ Add accessible field errors, page landmarks, and responsive dialogs
- 🐛 Return safe database conflicts and retain raw errors in server logs
- ♻️ Keep brand types, view models, and styles aligned with project rules
- ✅ Cover API errors, strict HTTP mocks, custom slugs, and admin browser flows

Fixes #780
---
 app/pages/admin/equipment/brands/index.vue    | 590 +++++++++++++++++
 app/pages/admin/index.vue                     |   7 +
 app/utils/navigation.ts                       |   1 +
 server/api/equipment/brands/[id].delete.ts    |  20 +-
 server/api/equipment/brands/[id].patch.ts     |  22 +-
 .../equipment/brands/__tests__/create.test.ts |  92 ++-
 .../brands/__tests__/update-delete.test.ts    |  72 +-
 server/api/equipment/brands/index.post.ts     |  22 +-
 server/utils/equipment/brand-write-errors.ts  |  76 +++
 .../gear-library/admin-brands.test.ts         | 622 ++++++++++++++++++
 10 files changed, 1475 insertions(+), 49 deletions(-)
 create mode 100644 app/pages/admin/equipment/brands/index.vue
 create mode 100644 server/utils/equipment/brand-write-errors.ts
 create mode 100644 tests/playwright/gear-library/admin-brands.test.ts

diff --git a/app/pages/admin/equipment/brands/index.vue b/app/pages/admin/equipment/brands/index.vue
new file mode 100644
index 00000000..c970cab5
--- /dev/null
+++ b/app/pages/admin/equipment/brands/index.vue
@@ -0,0 +1,590 @@
+<template>
+  <PageContent page-title="Manage brands">
+    <template #actions>
+      <PerdLink :to="appRoutes.admin">Back to Admin</PerdLink>
+    </template>
+
+    <main :class="$style.component">
+      <div :class="$style.toolbar">
+        <label :class="$style.searchField">
+          <span>Search brands</span>
+          <input
+            ref="searchInput"
+            v-model="search"
+            type="search"
+            autocomplete="off"
+            placeholder="Search by name"
+            :class="$style.input"
+          >
+        </label>
+
+        <PerdButton ref="createButton" :disabled="isLoading" @click="openCreate">Add brand</PerdButton>
+      </div>
+
+      <p :class="$style.announcement" role="status" aria-live="polite" aria-atomic="true">
+        {{ announcement }}
+      </p>
+
+      <PageLoadingState v-if="isLoading" title="Loading brands" />
+
+      <PagePlaceholder v-else-if="hasLoadError" emoji="🧰" title="Brands unavailable.">
+        The brand list could not be loaded.
+        <template #actions>
+          <PerdButton variant="secondary" @click="retryLoad">Retry</PerdButton>
+        </template>
+      </PagePlaceholder>
+
+      <PagePlaceholder v-else-if="isEmpty" emoji="🏷️" title="No brands yet.">
+        Add the first brand to make it available in gear submissions.
+      </PagePlaceholder>
+
+      <PagePlaceholder v-else-if="hasNoMatches" emoji="🔎" title="No matching brands.">
+        Try a different name.
+      </PagePlaceholder>
+
+      <ul v-else :class="$style.list">
+        <li v-for="brand in visibleBrands" :key="brand.id" :class="$style.row">
+          <div :class="$style.brand">
+            <strong :class="$style.name">{{ brand.name }}</strong>
+            <span :class="$style.slug">{{ brand.slug }}</span>
+          </div>
+
+          <div :class="$style.rowActions">
+            <PerdButton size="small" variant="secondary" :aria-label="brand.editLabel" @click="openEdit(brand)">
+              Edit
+            </PerdButton>
+            <PerdButton size="small" variant="danger" :aria-label="brand.deleteLabel" @click="openDelete(brand)">
+              Delete
+            </PerdButton>
+          </div>
+        </li>
+      </ul>
+    </main>
+
+    <ModalDialog
+      v-model="isFormOpen"
+      :class="$style.dialog"
+      :aria-labelledby="formHeadingId"
+      :close-disabled="isSaving"
+    >
+      <form :class="$style.dialogContent" @submit.prevent="saveBrand">
+        <h2 :id="formHeadingId">{{ formHeading }}</h2>
+
+        <div :class="$style.field">
+          <label :for="nameInputId">Name</label>
+          <input
+            :id="nameInputId"
+            ref="nameInput"
+            v-model="formName"
+            :class="$style.input"
+            :aria-invalid="nameInvalid"
+            :aria-describedby="nameDescription"
+            name="name"
+            required
+            :maxlength="limits.maxBrandNameLength"
+            :disabled="isSaving"
+            autocomplete="off"
+          >
+          <p v-if="nameInvalid" :id="formErrorId" :class="$style.error" role="alert">{{ formError }}</p>
+        </div>
+
+        <div :class="$style.field">
+          <label :for="slugInputId">Slug</label>
+          <input
+            :id="slugInputId"
+            ref="slugInput"
+            v-model="formSlug"
+            :class="$style.input"
+            :aria-invalid="slugInvalid"
+            name="slug"
+            required
+            pattern="[a-z0-9]+(-[a-z0-9]+)*"
+            :maxlength="limits.maxBrandSlugLength"
+            :disabled="isSaving"
+            autocomplete="off"
+            :aria-describedby="slugDescription"
+            @input="markSlugManuallyEdited"
+          >
+          <small :id="slugHintId" :class="$style.fieldHint">Lowercase letters, numbers, and single hyphens. Changing it breaks old links.</small>
+          <p v-if="slugInvalid" :id="formErrorId" :class="$style.error" role="alert">{{ formError }}</p>
+        </div>
+
+        <p v-if="hasGeneralFormError" ref="formAlert" :class="$style.error" role="alert" tabindex="-1">{{ formError }}</p>
+
+        <div :class="$style.dialogActions">
+          <PerdButton variant="secondary" :disabled="isSaving" @click="closeBrandForm">
+            Cancel
+          </PerdButton>
+          <PerdButton type="submit" :loading="isSaving">{{ saveLabel }}</PerdButton>
+        </div>
+      </form>
+    </ModalDialog>
+
+    <ConfirmationDialog
+      v-model="isDeleteOpen"
+      header-text="Delete brand?"
+      confirm-button-text="Delete brand"
+      confirm-variant="danger"
+      :confirm-loading="isDeleting"
+      :close-on-confirm="false"
+      :error="deleteError"
+      @confirm="deleteBrand"
+    >
+      Delete {{ deleteTarget?.name }}? This is only possible if no gear uses this brand.
+    </ConfirmationDialog>
+  </PageContent>
+</template>
+
+<script lang="ts" setup>
+  import { computed, nextTick, ref, useId, useTemplateRef, watch } from 'vue'
+  import { definePageMeta, useFetch, useHead, useRequestFetch } from '#imports'
+  import { limits } from '#shared/constants'
+  import type { BrandsListResponse } from '#server/api/equipment/brands/index.get'
+  import PageLoadingState from '~/components/PageLoadingState.vue'
+  import PagePlaceholder from '~/components/PagePlaceholder.vue'
+  import PerdButton from '~/components/PerdButton.vue'
+  import PerdLink from '~/components/PerdLink.vue'
+  import PageContent from '~/components/layout/PageContent.vue'
+  import ConfirmationDialog from '~/components/dialogs/ConfirmationDialog.vue'
+  import ModalDialog from '~/components/dialogs/ModalDialog.vue'
+  import { getFetchErrorResponse } from '~/utils/fetch-error'
+  import { appRoutes } from '~/utils/navigation'
+
+  type Brand = BrandsListResponse[number]
+
+  definePageMeta({
+    layout: 'page',
+    middleware: 'admin'
+  })
+
+  useHead({ title: 'Manage brands' })
+
+  const requestFetch = useRequestFetch()
+  const formHeadingId = useId()
+  const nameInputId = useId()
+  const slugInputId = useId()
+  const slugHintId = useId()
+  const formErrorId = useId()
+  const slugErrorDescription = `${slugHintId} ${formErrorId}`
+  const searchInput = useTemplateRef('searchInput')
+  const createButton = useTemplateRef('createButton')
+  const nameInput = useTemplateRef('nameInput')
+  const slugInput = useTemplateRef('slugInput')
+  const formAlert = useTemplateRef('formAlert')
+  const search = ref('')
+  const announcement = ref('')
+  const rows = ref<Brand[]>([])
+  const isFormOpen = ref(false)
+  const editingId = ref<number | null>(null)
+  const formName = ref('')
+  const formSlug = ref('')
+  const slugManuallyEdited = ref(false)
+  const isSaving = ref(false)
+  const formError = ref<string | null>(null)
+  const formErrorField = ref<'name' | 'slug' | null>(null)
+  const isDeleteOpen = ref(false)
+  const deleteTarget = ref<Brand | null>(null)
+  const isDeleting = ref(false)
+  const deleteError = ref<string | null>(null)
+
+  const { data, error: loadError, refresh, status } = await useFetch('/api/equipment/brands', {
+    lazy: true
+  })
+
+  const isLoading = computed(() => status.value === 'pending')
+  const hasLoadError = computed(() => Boolean(loadError.value))
+  const isEmpty = computed(() => rows.value.length === 0)
+
+  const normalizedSearch = computed(() => {
+    const trimmedSearch = search.value.trim()
+
+    return trimmedSearch.toLocaleLowerCase()
+  })
+
+  const visibleBrands = computed(() => {
+    const matchingBrands = rows.value.filter((brand) => {
+      const normalizedName = brand.name.toLocaleLowerCase()
+
+      return normalizedName.includes(normalizedSearch.value)
+    })
+
+    const sortedBrands = matchingBrands.toSorted((left, right) => left.name.localeCompare(right.name))
+
+    return sortedBrands.map((brand) => {
+      const editLabel = `Edit ${brand.name}`
+      const deleteLabel = `Delete ${brand.name}`
+
+      return {
+        id: brand.id,
+        name: brand.name,
+        slug: brand.slug,
+        editLabel,
+        deleteLabel
+      }
+    })
+  })
+
+  const hasNoMatches = computed(() => visibleBrands.value.length === 0)
+  const formHeading = computed(() => editingId.value === null ? 'Add brand' : 'Edit brand')
+  const saveLabel = computed(() => editingId.value === null ? 'Create brand' : 'Save brand')
+  const nameInvalid = computed(() => formErrorField.value === 'name' || undefined)
+  const slugInvalid = computed(() => formErrorField.value === 'slug' || undefined)
+  const nameDescription = computed(() => nameInvalid.value ? formErrorId : undefined)
+  const slugDescription = computed(() => slugInvalid.value ? slugErrorDescription : slugHintId)
+  const hasGeneralFormError = computed(() => formError.value !== null && formErrorField.value === null)
+
+  function suggestSlug(name: string): string {
+    const expansions = new Map([
+      ['æ', 'ae'],
+      ['œ', 'oe'],
+      ['ß', 'ss'],
+      ['ø', 'o'],
+      ['ł', 'l'],
+      ['đ', 'd'],
+      ['ð', 'd'],
+      ['þ', 'th']
+    ])
+
+    const expanded = name.replaceAll(/[æœßøłđðþ]/giu, (character) => {
+      const lowercaseCharacter = character.toLowerCase()
+      const expansion = expansions.get(lowercaseCharacter)
+
+      return expansion ?? character
+    })
+
+    const normalized = expanded.normalize('NFKD')
+    const withoutMarks = normalized.replaceAll(/\p{M}/gu, '')
+    const lowercase = withoutMarks.toLowerCase()
+    const separated = lowercase.replaceAll(/[^a-z0-9]+/gu, '-')
+    const trimmed = separated.replaceAll(/^-|-$/gu, '')
+    const truncated = trimmed.slice(0, limits.maxBrandSlugLength)
+
+    return truncated.replaceAll(/-$/gu, '')
+  }
+
+  watch(data, (brands) => {
+    if (brands !== null && brands !== undefined) {
+      rows.value = brands
+    }
+  }, { immediate: true })
+
+  watch(formName, (name) => {
+    if (editingId.value === null && !slugManuallyEdited.value) {
+      formSlug.value = suggestSlug(name)
+    }
+  })
+
+  function resetFormErrors() {
+    formError.value = null
+    formErrorField.value = null
+  }
+
+  function markSlugManuallyEdited() {
+    slugManuallyEdited.value = true
+  }
+
+  function closeBrandForm() {
+    isFormOpen.value = false
+  }
+
+  function openCreate() {
+    editingId.value = null
+    formName.value = ''
+    formSlug.value = ''
+    slugManuallyEdited.value = false
+
+    resetFormErrors()
+
+    isFormOpen.value = true
+  }
+
+  function openEdit(brand: Brand) {
+    editingId.value = brand.id
+    formName.value = brand.name
+    formSlug.value = brand.slug
+    slugManuallyEdited.value = true
+
+    resetFormErrors()
+
+    isFormOpen.value = true
+  }
+
+  function openDelete(brand: Brand) {
+    deleteTarget.value = brand
+    deleteError.value = null
+    isDeleteOpen.value = true
+  }
+
+  async function retryLoad() {
+    searchInput.value?.focus()
+    await refresh()
+  }
+
+  async function focusFormError() {
+    await nextTick()
+
+    if (formErrorField.value === 'name') {
+      nameInput.value?.focus()
+    } else if (formErrorField.value === 'slug') {
+      slugInput.value?.focus()
+    } else {
+      formAlert.value?.focus()
+    }
+  }
+
+  async function focusAfterRemoval() {
+    await nextTick()
+    globalThis.requestAnimationFrame(() => searchInput.value?.focus())
+  }
+
+  async function saveBrand() {
+    if (isSaving.value) {
+      return
+    }
+
+    const name = formName.value.trim()
+    const slug = formSlug.value.trim()
+    const id = editingId.value
+    const isSlugValid = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(slug)
+
+    resetFormErrors()
+
+    if (name === '') {
+      formError.value = 'Enter a name.'
+      formErrorField.value = 'name'
+
+      await focusFormError()
+
+      return
+    }
+
+    if (!isSlugValid) {
+      formError.value = 'Enter a valid slug.'
+      formErrorField.value = 'slug'
+
+      await focusFormError()
+
+      return
+    }
+
+    isSaving.value = true
+
+    try {
+      const body = {
+        name,
+        slug
+      }
+
+      const path = id === null ? '/api/equipment/brands' : `/api/equipment/brands/${id}` as const
+      const method = id === null ? 'POST' : 'PATCH'
+
+      const brand = await requestFetch(path, {
+        method,
+        body
+      })
+
+      const nextRows = id === null
+        ? [...rows.value, brand]
+        : rows.value.map((row) => row.id === brand.id ? brand : row)
+
+      const resultAnnouncement = id === null ? `${brand.name} created.` : `${brand.name} updated.`
+      const normalizedName = brand.name.toLocaleLowerCase()
+      const matchesSearch = normalizedName.includes(normalizedSearch.value)
+
+      rows.value = nextRows
+      announcement.value = resultAnnouncement
+      isFormOpen.value = false
+
+      if (id === null) {
+        await nextTick()
+        globalThis.requestAnimationFrame(() => createButton.value?.focus())
+      } else if (!matchesSearch) {
+        await focusAfterRemoval()
+      }
+    } catch (error) {
+      const response = getFetchErrorResponse(error)
+
+      if (response.status === 409 && response.statusMessage) {
+        formError.value = response.statusMessage
+
+        if (response.statusMessage === 'Brand name already exists') {
+          formErrorField.value = 'name'
+        } else if (response.statusMessage === 'Brand slug already exists') {
+          formErrorField.value = 'slug'
+        }
+      } else if (response.status === 404) {
+        formError.value = 'This brand no longer exists. Reload the list.'
+      } else {
+        formError.value = 'Could not save the brand. Try again.'
+      }
+    } finally {
+      isSaving.value = false
+    }
+
+    if (formError.value !== null) {
+      await focusFormError()
+    }
+  }
+
+  async function deleteBrand() {
+    const target = deleteTarget.value
+
+    if (target === null || isDeleting.value) {
+      return
+    }
+
+    isDeleting.value = true
+    deleteError.value = null
+
+    try {
+      const path = `/api/equipment/brands/${target.id}` as const
+
+      await requestFetch(path, { method: 'DELETE' })
+
+      const remainingRows = rows.value.filter((brand) => brand.id !== target.id)
+      const resultAnnouncement = `${target.name} deleted.`
+
+      rows.value = remainingRows
+      announcement.value = resultAnnouncement
+      isDeleteOpen.value = false
+
+      await focusAfterRemoval()
+    } catch (error) {
+      const response = getFetchErrorResponse(error)
+
+      if (response.status === 409) {
+        deleteError.value = 'This brand is used by gear and cannot be deleted.'
+      } else if (response.status === 404) {
+        deleteError.value = 'This brand no longer exists. Reload the list.'
+      } else {
+        deleteError.value = 'Could not delete the brand. Try again.'
+      }
+    } finally {
+      isDeleting.value = false
+    }
+  }
+</script>
+
+<style module>
+  .component {
+    display: grid;
+    gap: var(--spacing-20);
+  }
+
+  .toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: end;
+    gap: var(--spacing-16);
+  }
+
+  .searchField,
+  .field {
+    display: grid;
+    gap: var(--spacing-8);
+    min-inline-size: min(100%, 16rem);
+  }
+
+  .searchField {
+    flex: 1;
+  }
+
+  .input {
+    inline-size: 100%;
+    min-block-size: var(--layout-button-height-medium);
+    padding-inline: var(--spacing-12);
+    border: 1px solid var(--color-text-tertiary);
+    border-radius: var(--layout-button-radius-small);
+    background: var(--color-background-elevated);
+    color: var(--color-text-primary);
+
+    &[aria-invalid='true'],
+    &:user-invalid {
+      border-color: var(--color-danger-primary);
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--color-accent-primary);
+      outline-offset: 2px;
+    }
+  }
+
+  .announcement {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  .list {
+    display: grid;
+    gap: var(--spacing-12);
+    padding: 0;
+    list-style: none;
+  }
+
+  .row {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    align-items: center;
+    gap: var(--spacing-16);
+    padding: var(--spacing-16);
+    border: 1px solid var(--color-border-subtle);
+    border-radius: var(--border-radius-16);
+    background: var(--color-surface-secondary);
+  }
+
+  .brand {
+    display: grid;
+    gap: var(--spacing-4);
+    min-inline-size: 0;
+  }
+
+  .name,
+  .slug {
+    overflow-wrap: anywhere;
+  }
+
+  .slug {
+    color: var(--color-text-secondary);
+    font-size: var(--font-size-14);
+  }
+
+  .rowActions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--spacing-8);
+  }
+
+  .dialog {
+    inline-size: min(100dvw - var(--spacing-32), 30rem);
+    max-inline-size: none;
+  }
+
+  .dialogContent {
+    display: grid;
+    gap: var(--spacing-20);
+    padding: var(--spacing-24);
+    border: 1px solid var(--color-border-subtle);
+    border-radius: var(--border-radius-24);
+    background: var(--color-surface-primary);
+  }
+
+  .fieldHint {
+    color: var(--color-text-secondary);
+  }
+
+  .error {
+    color: var(--color-danger-primary);
+  }
+
+  .dialogActions {
+    display: flex;
+    justify-content: end;
+    flex-wrap: wrap;
+    gap: var(--spacing-8);
+  }
+</style>
diff --git a/app/pages/admin/index.vue b/app/pages/admin/index.vue
index f2b95964..2629b30c 100644
--- a/app/pages/admin/index.vue
+++ b/app/pages/admin/index.vue
@@ -1,6 +1,13 @@
 <template>
   <PageContent page-title="Admin">
     <div :class="$style.component">
+      <ActionPanel
+        icon="hugeicons:tag-01"
+        subtitle="Add, rename, and remove brands used by the gear catalog."
+        title="Manage brands"
+        :to="appRoutes.adminEquipmentBrands"
+      />
+
       <ActionPanel
         icon="hugeicons:task-edit-01"
         subtitle="Check and correct pending gear before a publish decision."
diff --git a/app/utils/navigation.ts b/app/utils/navigation.ts
index 0c6b3aaa..3470af96 100644
--- a/app/utils/navigation.ts
+++ b/app/utils/navigation.ts
@@ -2,6 +2,7 @@ const appRoutes = {
   account: '/account',
   accountSubmissions: '/account/submissions',
   admin: '/admin',
+  adminEquipmentBrands: '/admin/equipment/brands',
   adminEquipmentPhotoSubmissions: '/admin/equipment/photo-submissions',
   adminEquipmentSubmissions: '/admin/equipment/submissions',
   gearLibrary: '/gear-library',
diff --git a/server/api/equipment/brands/[id].delete.ts b/server/api/equipment/brands/[id].delete.ts
index 1ad16a26..c0b3550d 100644
--- a/server/api/equipment/brands/[id].delete.ts
+++ b/server/api/equipment/brands/[id].delete.ts
@@ -1,12 +1,13 @@
 import { eq } from 'drizzle-orm'
-import { createError, defineEventHandler, getValidatedRouterParams, isError, setResponseStatus } from 'h3'
+import { createError, defineEventHandler, getValidatedRouterParams, setResponseStatus } from 'h3'
 import { brands, contributions } from '#server/database/schema'
 import { validateAdminUser } from '#server/utils/admin'
 import { createWebSocketClientFromEvent } from '#server/utils/config'
 import { brandBaseSelection } from '#server/utils/equipment/base-records'
+import { throwBrandWriteError } from '#server/utils/equipment/brand-write-errors'
 import { validateBrandIdParams } from '#server/utils/validation/schemas'
 
-export default defineEventHandler(async (event) => {
+export default defineEventHandler(async (event): Promise<void> => {
   const userId = await validateAdminUser(event)
   const { id: brandId } = await getValidatedRouterParams(event, validateBrandIdParams)
   const dbWebsocket = createWebSocketClientFromEvent(event)
@@ -38,16 +39,13 @@ export default defineEventHandler(async (event) => {
         })
     })
   } catch (error) {
-    if (isError(error)) {
-      throw error
-    }
-
-    throw createError({
-      status: 500,
-      message: 'Failed to delete brand'
-    })
+    throwBrandWriteError(error, 'delete')
   } finally {
-    await dbWebsocket.$client.end()
+    try {
+      await dbWebsocket.$client.end()
+    } catch (error) {
+      console.error('Failed to close brand write database client', { error })
+    }
   }
 
   setResponseStatus(event, 204)
diff --git a/server/api/equipment/brands/[id].patch.ts b/server/api/equipment/brands/[id].patch.ts
index 9cce38dc..9aa451ec 100644
--- a/server/api/equipment/brands/[id].patch.ts
+++ b/server/api/equipment/brands/[id].patch.ts
@@ -1,12 +1,13 @@
 import { eq } from 'drizzle-orm'
-import { createError, defineEventHandler, getValidatedRouterParams, isError, readValidatedBody } from 'h3'
+import { createError, defineEventHandler, getValidatedRouterParams, readValidatedBody } from 'h3'
 import { brands, contributions } from '#server/database/schema'
 import { validateAdminUser } from '#server/utils/admin'
 import { createWebSocketClientFromEvent } from '#server/utils/config'
-import { brandBaseSelection } from '#server/utils/equipment/base-records'
+import { brandBaseSelection, type BrandBaseRecord } from '#server/utils/equipment/base-records'
+import { throwBrandWriteError } from '#server/utils/equipment/brand-write-errors'
 import { validateBrandIdParams, validateBrandMutationBody } from '#server/utils/validation/schemas'
 
-export default defineEventHandler(async (event) => {
+export default defineEventHandler(async (event): Promise<BrandBaseRecord> => {
   const userId = await validateAdminUser(event)
   const { id: brandId } = await getValidatedRouterParams(event, validateBrandIdParams)
   const { name, slug } = await readValidatedBody(event, validateBrandMutationBody)
@@ -45,15 +46,12 @@ export default defineEventHandler(async (event) => {
       return updatedBrand
     })
   } catch (error) {
-    if (isError(error)) {
-      throw error
-    }
-
-    throw createError({
-      status: 500,
-      message: 'Failed to update brand'
-    })
+    throwBrandWriteError(error, 'update')
   } finally {
-    await dbWebsocket.$client.end()
+    try {
+      await dbWebsocket.$client.end()
+    } catch (error) {
+      console.error('Failed to close brand write database client', { error })
+    }
   }
 })
diff --git a/server/api/equipment/brands/__tests__/create.test.ts b/server/api/equipment/brands/__tests__/create.test.ts
index 09edd69d..d982d50f 100644
--- a/server/api/equipment/brands/__tests__/create.test.ts
+++ b/server/api/equipment/brands/__tests__/create.test.ts
@@ -218,42 +218,97 @@ describe('post /api/equipment/brands', () => {
     expect(createWebSocketClientMock).not.toHaveBeenCalled()
   })
 
-  it('should return 500 when brand slug already exists', async () => {
+  it.each([
+    ['name', 'brands_name_key', 'Brand name already exists'],
+    ['slug', 'brands_slug_key', 'Brand slug already exists']
+  ])('should return 409 when brand %s already exists', async (_field, constraint, statusMessage) => {
+    const duplicateError = new Error('duplicate value')
+
+    const databaseError = Object.assign(duplicateError, {
+      code: '23505',
+      constraint
+    })
+
+    const queryError = new Error('query failed', { cause: databaseError })
     const { dbWrite } = createDb()
 
-    dbWrite.transaction.mockRejectedValue(new Error('duplicate slug'))
+    dbWrite.transaction.mockRejectedValue(queryError)
     createWebSocketClientMock.mockReturnValue(dbWrite)
 
+    const errorLog = vi.spyOn(console, 'error').mockImplementation((message, details: { error: unknown; }) => {
+      expect(message).toBe('Failed to create brand')
+      expect(details.error).toBe(queryError)
+    })
+
     const event = createTestEvent({})
 
     await expect(createBrandHandler(event)).rejects.toMatchObject({
-      message: 'Failed to create brand',
-      statusCode: 500
+      statusCode: 409,
+      statusMessage
     })
 
     expect(dbWrite.$client.end).toHaveBeenCalledTimes(1)
+    expect(errorLog).toHaveBeenCalledTimes(1)
   })
 
   it('should return 500 when brand creation fails', async () => {
+    const failure = new Error('insert failed')
+
     const { dbWrite } = createDb({
-      insertError: new Error('insert failed')
+      insertError: failure
     })
 
     createWebSocketClientMock.mockReturnValue(dbWrite)
 
     const event = createTestEvent({})
 
+    const errorLog = vi.spyOn(console, 'error').mockImplementation((message) => {
+      expect(message).toBe('Failed to create brand')
+    })
+
     await expect(createBrandHandler(event)).rejects.toMatchObject({
       message: 'Failed to create brand',
       statusCode: 500
     })
 
     expect(dbWrite.$client.end).toHaveBeenCalledTimes(1)
+    expect(errorLog).toHaveBeenCalledTimes(1)
+    expect(errorLog).toHaveBeenCalledWith('Failed to create brand', { error: failure })
+  })
+
+  it('should not expose an unrelated database constraint', async () => {
+    const contributionError = new Error('duplicate contribution')
+
+    const failure = Object.assign(contributionError, {
+      code: '23505',
+      constraint: 'contributions_other_key'
+    })
+
+    const { dbWrite } = createDb()
+
+    dbWrite.transaction.mockRejectedValue(failure)
+    createWebSocketClientMock.mockReturnValue(dbWrite)
+
+    const errorLog = vi.spyOn(console, 'error').mockImplementation((message) => {
+      expect(message).toBe('Failed to create brand')
+    })
+
+    const event = createTestEvent({})
+
+    await expect(createBrandHandler(event)).rejects.toMatchObject({
+      statusCode: 500,
+      statusMessage: 'Failed to create brand'
+    })
+
+    expect(errorLog).toHaveBeenCalledTimes(1)
+    expect(errorLog).toHaveBeenCalledWith('Failed to create brand', { error: failure })
   })
 
   it('should return 500 when contribution logging fails after brand creation', async () => {
+    const contributionError = new Error('contribution failed')
+
     const { dbWrite } = createDb({
-      contributionError: new Error('contribution failed'),
+      contributionError,
 
       createdBrand: {
         id: 12,
@@ -274,4 +329,29 @@ describe('post /api/equipment/brands', () => {
     expect(setResponseStatusMock).not.toHaveBeenCalled()
     expect(dbWrite.$client.end).toHaveBeenCalledTimes(1)
   })
+
+  it('should retain a committed creation when closing the client fails', async () => {
+    const createdBrand = {
+      id: 12,
+      name: 'MSR',
+      slug: 'msr'
+    }
+
+    const { dbWrite } = createDb({ createdBrand })
+    const closeError = new Error('close failed')
+
+    dbWrite.$client.end.mockRejectedValue(closeError)
+    createWebSocketClientMock.mockReturnValue(dbWrite)
+
+    const errorLog = vi.spyOn(console, 'error').mockImplementation((message) => {
+      expect(message).toBe('Failed to close brand write database client')
+    })
+
+    const event = createTestEvent({})
+    const result = await createBrandHandler(event)
+
+    expect(result).toStrictEqual(createdBrand)
+    expect(setResponseStatusMock).toHaveBeenCalledWith(event, 201)
+    expect(errorLog).toHaveBeenCalledWith('Failed to close brand write database client', { error: closeError })
+  })
 })
diff --git a/server/api/equipment/brands/__tests__/update-delete.test.ts b/server/api/equipment/brands/__tests__/update-delete.test.ts
index bf331478..730d364a 100644
--- a/server/api/equipment/brands/__tests__/update-delete.test.ts
+++ b/server/api/equipment/brands/__tests__/update-delete.test.ts
@@ -338,25 +338,44 @@ describe('patch /api/equipment/brands/[id]', () => {
     expect(dbWrite.$client.end).toHaveBeenCalledTimes(1)
   })
 
-  it('should return 500 when brand slug already exists', async () => {
+  it.each([
+    ['name', 'brands_name_key', 'Brand name already exists'],
+    ['slug', 'brands_slug_key', 'Brand slug already exists']
+  ])('should return 409 when brand %s already exists', async (_field, constraint, statusMessage) => {
     const { dbWrite } = createPatchDb({})
+    const duplicateError = new Error('duplicate value')
+
+    const databaseError = Object.assign(duplicateError, {
+      code: '23505',
+      constraint
+    })
+
+    const queryError = new Error('query failed', { cause: databaseError })
 
-    dbWrite.transaction.mockRejectedValue(new Error('duplicate slug'))
+    dbWrite.transaction.mockRejectedValue(queryError)
     createWebSocketClientMock.mockReturnValue(dbWrite)
 
+    const errorLog = vi.spyOn(console, 'error').mockImplementation((message, details: { error: unknown; }) => {
+      expect(message).toBe('Failed to update brand')
+      expect(details.error).toBe(queryError)
+    })
+
     const event = createTestEvent({})
 
     await expect(updateBrandHandler(event)).rejects.toMatchObject({
-      message: 'Failed to update brand',
-      statusCode: 500
+      statusCode: 409,
+      statusMessage
     })
 
     expect(dbWrite.$client.end).toHaveBeenCalledTimes(1)
+    expect(errorLog).toHaveBeenCalledTimes(1)
   })
 
   it('should return 500 when contribution logging fails after brand update', async () => {
+    const contributionError = new Error('contribution failed')
+
     const { dbWrite } = createPatchDb({
-      contributionError: new Error('contribution failed'),
+      contributionError,
 
       updatedBrand: {
         id: 12,
@@ -378,8 +397,10 @@ describe('patch /api/equipment/brands/[id]', () => {
   })
 
   it('should return 500 when brand update fails', async () => {
+    const updateError = new Error('update failed')
+
     const { dbWrite } = createPatchDb({
-      updateError: new Error('update failed')
+      updateError
     })
 
     createWebSocketClientMock.mockReturnValue(dbWrite)
@@ -468,6 +489,37 @@ describe('delete /api/equipment/brands/[id]', () => {
     expect(dbWrite.$client.end).toHaveBeenCalledTimes(1)
   })
 
+  it('should return 409 when equipment uses the brand', async () => {
+    const { dbWrite } = createDeleteDb({})
+    const foreignKeyError = new Error('foreign key violation')
+
+    const databaseError = Object.assign(foreignKeyError, {
+      code: '23503',
+      constraint: 'equipment_items_brandId_brands_id_fkey'
+    })
+
+    const queryError = new Error('query failed', { cause: databaseError })
+
+    dbWrite.transaction.mockRejectedValue(queryError)
+    createWebSocketClientMock.mockReturnValue(dbWrite)
+
+    const errorLog = vi.spyOn(console, 'error').mockImplementation((message, details: { error: unknown; }) => {
+      expect(message).toBe('Failed to delete brand')
+      expect(details.error).toBe(queryError)
+    })
+
+    const event = createTestEvent({})
+
+    await expect(deleteBrandHandler(event)).rejects.toMatchObject({
+      statusCode: 409,
+      statusMessage: 'Brand is used by equipment'
+    })
+
+    expect(setResponseStatusMock).not.toHaveBeenCalled()
+    expect(dbWrite.$client.end).toHaveBeenCalledTimes(1)
+    expect(errorLog).toHaveBeenCalledTimes(1)
+  })
+
   it.each([
     'msr',
     '12-msr'
@@ -489,8 +541,10 @@ describe('delete /api/equipment/brands/[id]', () => {
   })
 
   it('should return 500 when contribution logging fails after brand delete', async () => {
+    const contributionError = new Error('contribution failed')
+
     const { dbWrite } = createDeleteDb({
-      contributionError: new Error('contribution failed'),
+      contributionError,
 
       deletedBrand: {
         id: 12,
@@ -512,8 +566,10 @@ describe('delete /api/equipment/brands/[id]', () => {
   })
 
   it('should return 500 when brand delete fails', async () => {
+    const deleteError = new Error('delete failed')
+
     const { dbWrite } = createDeleteDb({
-      deleteError: new Error('delete failed')
+      deleteError
     })
 
     createWebSocketClientMock.mockReturnValue(dbWrite)
diff --git a/server/api/equipment/brands/index.post.ts b/server/api/equipment/brands/index.post.ts
index fb275bd1..7b4a3593 100644
--- a/server/api/equipment/brands/index.post.ts
+++ b/server/api/equipment/brands/index.post.ts
@@ -1,11 +1,12 @@
-import { createError, defineEventHandler, isError, readValidatedBody, setResponseStatus } from 'h3'
+import { createError, defineEventHandler, readValidatedBody, setResponseStatus } from 'h3'
 import { brands, contributions } from '#server/database/schema'
 import { validateAdminUser } from '#server/utils/admin'
 import { createWebSocketClientFromEvent } from '#server/utils/config'
-import { brandBaseSelection } from '#server/utils/equipment/base-records'
+import { brandBaseSelection, type BrandBaseRecord } from '#server/utils/equipment/base-records'
+import { throwBrandWriteError } from '#server/utils/equipment/brand-write-errors'
 import { validateBrandMutationBody } from '#server/utils/validation/schemas'
 
-export default defineEventHandler(async (event) => {
+export default defineEventHandler(async (event): Promise<BrandBaseRecord> => {
   const userId = await validateAdminUser(event)
   const { name, slug } = await readValidatedBody(event, validateBrandMutationBody)
   const dbWebsocket = createWebSocketClientFromEvent(event)
@@ -47,15 +48,12 @@ export default defineEventHandler(async (event) => {
 
     return createdBrand
   } catch (error) {
-    if (isError(error)) {
-      throw error
-    }
-
-    throw createError({
-      status: 500,
-      message: 'Failed to create brand'
-    })
+    throwBrandWriteError(error, 'create')
   } finally {
-    await dbWebsocket.$client.end()
+    try {
+      await dbWebsocket.$client.end()
+    } catch (error) {
+      console.error('Failed to close brand write database client', { error })
+    }
   }
 })
diff --git a/server/utils/equipment/brand-write-errors.ts b/server/utils/equipment/brand-write-errors.ts
new file mode 100644
index 00000000..f60dd406
--- /dev/null
+++ b/server/utils/equipment/brand-write-errors.ts
@@ -0,0 +1,76 @@
+import { createError, isError } from 'h3'
+
+type BrandWriteAction = 'create' | 'update' | 'delete'
+
+function getDatabaseError(error: unknown): { code: string; constraint: string; } | null {
+  let current = error
+
+  for (let depth = 0; depth < 4; depth += 1) {
+    if (current === null || typeof current !== 'object') {
+      return null
+    }
+
+    const code: unknown = Reflect.get(current, 'code')
+    const constraint: unknown = Reflect.get(current, 'constraint')
+
+    if (typeof code === 'string' && typeof constraint === 'string') {
+      return {
+        code,
+        constraint
+      }
+    }
+
+    current = Reflect.get(current, 'cause')
+  }
+
+  return null
+}
+
+/** Maps only known brand constraints to public errors and keeps other failures private. */
+function throwBrandWriteError(error: unknown, action: BrandWriteAction): never {
+  const failureMessage = `Failed to ${action} brand`
+
+  if (isError(error)) {
+    if (error.statusCode >= 500) {
+      console.error(failureMessage, { error })
+    }
+
+    throw error
+  }
+
+  console.error(failureMessage, { error })
+
+  const databaseError = getDatabaseError(error)
+
+  if (databaseError?.code === '23505') {
+    if (databaseError.constraint === 'brands_name_key') {
+      throw createError({
+        status: 409,
+        statusMessage: 'Brand name already exists'
+      })
+    }
+
+    if (databaseError.constraint === 'brands_slug_key') {
+      throw createError({
+        status: 409,
+        statusMessage: 'Brand slug already exists'
+      })
+    }
+  }
+
+  if (action === 'delete'
+    && databaseError?.code === '23503'
+    && databaseError.constraint === 'equipment_items_brandId_brands_id_fkey') {
+    throw createError({
+      status: 409,
+      statusMessage: 'Brand is used by equipment'
+    })
+  }
+
+  throw createError({
+    status: 500,
+    statusMessage: failureMessage
+  })
+}
+
+export { throwBrandWriteError }
diff --git a/tests/playwright/gear-library/admin-brands.test.ts b/tests/playwright/gear-library/admin-brands.test.ts
new file mode 100644
index 00000000..e7a94bf2
--- /dev/null
+++ b/tests/playwright/gear-library/admin-brands.test.ts
@@ -0,0 +1,622 @@
+import type { BrowserContext, Page, Request, Route } from '@playwright/test'
+import * as v from 'valibot'
+import type { BrandsListResponse } from '../../../server/api/equipment/brands/index.get.ts'
+import { expect, test } from '../fixtures/global.fixtures.ts'
+import { mockAccountUser } from '../fixtures/account-user.fixtures.ts'
+import { createDeferred, mockCatalogApi } from '../fixtures/gear-library-entry-list.fixtures.ts'
+import { mockTwitchSignIn } from '../fixtures/twitch-auth.fixtures.ts'
+
+const adminId = '0195f6e8-8f44-74f6-bc9a-5c8f7df477aa'
+const path = '/admin/equipment/brands'
+const apiPath = '/api/equipment/brands'
+
+type Brand = BrandsListResponse[number]
+
+interface SignInOptions {
+  context: BrowserContext;
+  isAdmin: boolean;
+  page: Page;
+  target?: string;
+}
+
+const brandBodySchema = v.object({
+  name: v.string(),
+  slug: v.string()
+})
+
+function isCreateBrandRequest(request: Request): boolean {
+  const requestUrl = request.url()
+  const url = new globalThis.URL(requestUrl)
+  const method = request.method()
+  const isCreateRequest = url.pathname === apiPath && method === 'POST'
+
+  return isCreateRequest
+}
+
+async function signIn({ context, isAdmin, page, target = path }: SignInOptions) {
+  await mockAccountUser(context, {
+    email: null,
+    isAdmin,
+    isGuest: false,
+    isTwitchLinked: true,
+    userId: adminId
+  })
+
+  await mockTwitchSignIn(context, page, {
+    redirectTo: target,
+
+    user: {
+      email: null,
+      isAdmin,
+      isGuest: false,
+      userId: adminId
+    }
+  })
+}
+
+async function mockBrandStore(context: BrowserContext, initial: Brand[] = []) {
+  const brands = [...initial]
+  const itemPathPrefix = `${apiPath}/`
+  let nextId = 20
+
+  await context.route((url) => {
+    const isItemPath = url.pathname.startsWith(itemPathPrefix)
+    const isBrandPath = url.pathname === apiPath || isItemPath
+
+    return isBrandPath
+  }, async (route) => {
+    const request = route.request()
+    const requestUrl = request.url()
+    const { pathname } = new globalThis.URL(requestUrl)
+    const method = request.method()
+    const isListRequest = pathname === apiPath && method === 'GET'
+    const isCreateRequest = pathname === apiPath && method === 'POST'
+
+    if (isListRequest) {
+      await route.fulfill({ json: brands })
+
+      return
+    }
+
+    if (isCreateRequest) {
+      const rawBody: unknown = request.postDataJSON()
+      const body = v.parse(brandBodySchema, rawBody)
+
+      const brand = {
+        id: nextId,
+        name: body.name,
+        slug: body.slug
+      }
+
+      nextId += 1
+
+      brands.push(brand)
+
+      await route.fulfill({
+        status: 201,
+        json: brand
+      })
+
+      return
+    }
+
+    const isItemPath = pathname.startsWith(itemPathPrefix)
+    const isItemMutation = method === 'PATCH' || method === 'DELETE'
+    const isSupportedMutation = isItemPath && isItemMutation
+
+    if (!isSupportedMutation) {
+      await route.fallback()
+
+      return
+    }
+
+    const idText = pathname.slice(itemPathPrefix.length)
+    const id = Number(idText)
+    const index = brands.findIndex((brand) => brand.id === id)
+
+    if (index === -1) {
+      await route.fulfill({
+        status: 404,
+        json: { statusCode: 404 }
+      })
+
+      return
+    }
+
+    if (method === 'PATCH') {
+      const rawBody: unknown = request.postDataJSON()
+      const body = v.parse(brandBodySchema, rawBody)
+
+      const brand = {
+        id,
+        name: body.name,
+        slug: body.slug
+      }
+
+      brands[index] = brand
+
+      await route.fulfill({ json: brand })
+
+      return
+    }
+
+    brands.splice(index, 1)
+
+    await route.fulfill({
+      status: 204,
+      body: ''
+    })
+  })
+
+  return brands
+}
+
+async function fillBrandDialog(page: Page, name: string, slug?: string) {
+  const dialog = page.getByRole('dialog', { name: /brand/u })
+
+  await dialog.getByRole('textbox', { name: 'Name' }).fill(name)
+
+  if (slug !== undefined) {
+    await dialog.getByRole('textbox', { name: 'Slug' }).fill(slug)
+  }
+
+  return dialog
+}
+
+async function mockRecoveringBrands(context: BrowserContext, firstLoad: Promise<void>, retryLoad: Promise<void>) {
+  let loads = 0
+  let creates = 0
+
+  await context.route((url) => url.pathname === apiPath, async (route) => {
+    const request = route.request()
+    const method = request.method()
+
+    if (method === 'GET') {
+      loads += 1
+
+      if (loads <= 2) {
+        await firstLoad
+
+        await route.fulfill({
+          status: 500,
+          json: { statusCode: 500 }
+        })
+
+        return
+      }
+
+      await retryLoad
+
+      await route.fulfill({ json: [] })
+
+      return
+    }
+
+    if (method !== 'POST') {
+      await route.fallback()
+
+      return
+    }
+
+    creates += 1
+
+    const statusMessage = creates === 1 ? 'Brand slug already exists' : 'Brand name already exists'
+
+    await route.fulfill({
+      status: 409,
+
+      json: {
+        statusCode: 409,
+        statusMessage
+      }
+    })
+  })
+}
+
+async function mockRetryDelete(context: BrowserContext) {
+  const itemPath = `${apiPath}/10`
+  let attempts = 0
+
+  await context.route((url) => url.pathname === itemPath, async (route: Route) => {
+    const request = route.request()
+    const method = request.method()
+
+    if (method !== 'DELETE') {
+      await route.fallback()
+
+      return
+    }
+
+    attempts += 1
+
+    const response = attempts === 1
+      ? {
+        status: 409,
+
+        json: {
+          statusCode: 409,
+          statusMessage: 'Brand is used by equipment'
+        }
+      }
+      : {
+        status: 204,
+        body: ''
+      }
+
+    await route.fulfill(response)
+  })
+
+  return () => attempts
+}
+
+async function mockPendingBrandCreate(context: BrowserContext, release: Promise<void>) {
+  let creates = 0
+
+  await context.route((url) => url.pathname === apiPath, async (route) => {
+    const request = route.request()
+    const method = request.method()
+
+    if (method === 'GET') {
+      await route.fulfill({ json: [] })
+
+      return
+    }
+
+    if (method !== 'POST') {
+      await route.fallback()
+
+      return
+    }
+
+    creates += 1
+    await release
+
+    await route.fulfill({
+      status: 201,
+
+      json: {
+        id: 20,
+        name: 'MSR',
+        slug: 'msr'
+      }
+    })
+  })
+
+  return () => creates
+}
+
+test.describe('Admin brand management', () => {
+  test('guards the page before brand data loads', async ({ context, page }) => {
+    let brandRequests = 0
+
+    page.on('request', (request) => {
+      const requestUrl = request.url()
+      const url = new globalThis.URL(requestUrl)
+      const isBrandRequest = url.pathname === apiPath
+      const requestCount = Number(isBrandRequest)
+
+      brandRequests += requestCount
+    })
+
+    await signIn({
+      context,
+      page,
+      isAdmin: false
+    })
+
+    await expect(page).toHaveURL(/\/$/u)
+    expect(brandRequests).toBe(0)
+  })
+
+  test('creates, edits, searches, and deletes a brand by id', async ({ context, page }) => {
+    await mockCatalogApi(context)
+
+    const brands = await mockBrandStore(context, [{
+      id: 10,
+      name: 'MSR',
+      slug: 'msr'
+    }])
+
+    await test.step('open the brand workspace from Admin', async () => {
+      await signIn({
+        context,
+        page,
+        isAdmin: true,
+        target: '/admin'
+      })
+
+      const pathPattern = `${path}$`
+      const expectedUrl = new RegExp(pathPattern, 'u')
+
+      await page.getByRole('link', { name: 'Manage brands' }).click()
+      await expect(page).toHaveURL(expectedUrl)
+      await expect(page).toHaveTitle('Manage brands')
+      await expect(page.getByRole('main')).toHaveCount(1)
+      await expect(page.getByRole('main').getByRole('searchbox', { name: 'Search brands' })).toBeVisible()
+    })
+
+    await test.step('create a brand with its suggested slug', async () => {
+      await page.getByRole('button', { name: 'Add brand' }).click()
+
+      const createDialog = await fillBrandDialog(page, 'Crème Brûlée')
+
+      await expect(createDialog.getByRole('textbox', { name: 'Slug' })).toHaveValue('creme-brulee')
+      await createDialog.getByRole('button', { name: 'Create brand' }).click()
+      await expect(page.getByRole('status')).toContainText('Crème Brûlée created.')
+      await expect(page.getByText('creme-brulee')).toBeVisible()
+    })
+
+    await test.step('reload and sign in again to read the saved brand', async () => {
+      await page.reload()
+      await expect(page).toHaveURL(/\/login\?redirectTo=/u)
+
+      await signIn({
+        context,
+        page,
+        isAdmin: true
+      })
+
+      await expect(page.getByRole('button', { name: 'Edit Crème Brûlée' })).toBeVisible()
+    })
+
+    await test.step('edit the same brand and search the updated list', async () => {
+      await page.getByRole('button', { name: 'Edit Crème Brûlée' }).click()
+
+      const editDialog = await fillBrandDialog(page, 'Crème Brûlée Plus')
+
+      await expect(editDialog.getByRole('textbox', { name: 'Slug' })).toHaveValue('creme-brulee')
+      await editDialog.getByRole('textbox', { name: 'Slug' }).fill('creme-brulee-plus')
+      await editDialog.getByRole('button', { name: 'Save brand' }).click()
+      await expect(page.getByRole('button', { name: 'Edit Crème Brûlée Plus' })).toBeVisible()
+
+      const updatedBrand = brands.find((brand) => brand.id === 20)
+
+      expect(updatedBrand?.slug).toBe('creme-brulee-plus')
+      await page.getByRole('searchbox', { name: 'Search brands' }).fill('missing')
+      await expect(page.getByText('No matching brands.')).toBeVisible()
+      await page.getByRole('searchbox', { name: 'Search brands' }).fill('Brûlée')
+      await expect(page.getByRole('button', { name: 'Edit MSR' })).toHaveCount(0)
+    })
+
+    await test.step('use the changed brand in catalog filters and gear submissions', async () => {
+      await page.getByRole('navigation', { name: 'Workspace navigation' })
+        .getByRole('link', { name: 'Gear library' }).click()
+
+      await page.getByRole('button', { name: 'Filters' }).click()
+      await expect(page.getByRole('checkbox', { name: 'Crème Brûlée Plus' })).toBeVisible()
+      await page.getByRole('button', { name: 'Close filters' }).click()
+      await page.getByRole('link', { name: 'Submit gear' }).click()
+
+      const brandSelect = page.getByRole('combobox', { name: /^Brand/u })
+
+      await brandSelect.click()
+      await expect(page.getByRole('option', { name: 'Crème Brûlée Plus' })).toBeVisible()
+    })
+
+    await test.step('restore search focus when a rename removes the matching row', async () => {
+      await page.getByRole('navigation', { name: 'Workspace navigation' })
+        .getByRole('link', { name: 'Admin' }).click()
+
+      await page.getByRole('link', { name: 'Manage brands' }).click()
+      await page.getByRole('searchbox', { name: 'Search brands' }).fill('Brûlée')
+      await page.getByRole('button', { name: 'Edit Crème Brûlée Plus' }).click()
+
+      const renameDialog = await fillBrandDialog(page, 'Trail Stove')
+
+      await renameDialog.getByRole('button', { name: 'Save brand' }).click()
+      await expect(page.getByText('No matching brands.')).toBeVisible()
+      await expect(page.getByRole('searchbox', { name: 'Search brands' })).toBeFocused()
+    })
+
+    await test.step('delete the brand by its stable id and restore search focus', async () => {
+      await page.getByRole('searchbox', { name: 'Search brands' }).fill('')
+      await page.getByRole('button', { name: 'Delete Trail Stove' }).click()
+      await page.getByRole('dialog', { name: 'Delete brand?' }).getByRole('button', { name: 'Delete brand' }).click()
+      await expect(page.getByRole('button', { name: 'Delete Trail Stove' })).toHaveCount(0)
+      await expect(page.getByRole('searchbox', { name: 'Search brands' })).toBeFocused()
+
+      expect(brands).toEqual([{
+        id: 10,
+        name: 'MSR',
+        slug: 'msr'
+      }])
+    })
+  })
+
+  test('shows loading, retry, empty, and failed mutation states', async ({ context, page }) => {
+    const firstLoad = createDeferred()
+    const retryLoad = createDeferred()
+
+    await mockRecoveringBrands(context, firstLoad.promise, retryLoad.promise)
+
+    await signIn({
+      context,
+      page,
+      isAdmin: true,
+      target: '/admin'
+    })
+
+    await test.step('block creation while loading and keep search focused during keyboard retry', async () => {
+      const addBrand = page.getByRole('button', { name: 'Add brand' })
+      const search = page.getByRole('searchbox', { name: 'Search brands' })
+
+      await page.getByRole('link', { name: 'Manage brands' }).click()
+      await expect(page.getByText('Loading brands')).toBeVisible()
+      await expect(addBrand).toBeDisabled()
+      firstLoad.resolve()
+      await expect(page.getByText('Brands unavailable.')).toBeVisible()
+
+      const retry = page.getByRole('button', { name: 'Retry' })
+
+      await retry.focus()
+      await page.keyboard.press('Enter')
+      await expect(page.getByText('Loading brands')).toBeVisible()
+      await expect(addBrand).toBeDisabled()
+      await expect(search).toBeFocused()
+      retryLoad.resolve()
+      await expect(page.getByText('No brands yet.')).toBeVisible()
+      await expect(search).toBeFocused()
+      await expect(addBrand).toBeEnabled()
+    })
+
+    await test.step('preserve a custom slug after editing the name and a rejected creation', async () => {
+      await page.getByRole('button', { name: 'Add brand' }).click()
+
+      const dialog = await fillBrandDialog(page, 'Ångström')
+      const nameInput = dialog.getByRole('textbox', { name: 'Name' })
+      const slugInput = dialog.getByRole('textbox', { name: 'Slug' })
+
+      await expect(slugInput).toHaveValue('angstrom')
+      await slugInput.fill('custom-slug')
+      await nameInput.fill('Ångström Plus')
+      await expect(slugInput).toHaveValue('custom-slug')
+
+      const createRequest = page.waitForRequest(isCreateBrandRequest)
+
+      await dialog.getByRole('button', { name: 'Create brand' }).click()
+
+      const request = await createRequest
+      const rawBody: unknown = request.postDataJSON()
+      const body = v.parse(brandBodySchema, rawBody)
+
+      expect(body).toEqual({
+        name: 'Ångström Plus',
+        slug: 'custom-slug'
+      })
+
+      await expect(dialog.getByRole('alert')).toHaveText('Brand slug already exists')
+      await expect(nameInput).toHaveValue('Ångström Plus')
+      await expect(slugInput).toHaveValue('custom-slug')
+      await expect(slugInput).toHaveAttribute('aria-invalid', 'true')
+      await expect(slugInput).toHaveAccessibleDescription(/Brand slug already exists/u)
+      await expect(slugInput).toBeEnabled()
+      await expect(slugInput).toBeFocused()
+    })
+
+    await test.step('link custom and server name errors to the retained name field', async () => {
+      const dialog = page.getByRole('dialog', { name: 'Add brand' })
+      const nameInput = dialog.getByRole('textbox', { name: 'Name' })
+      const slugInput = dialog.getByRole('textbox', { name: 'Slug' })
+
+      await nameInput.fill('   ')
+      await dialog.getByRole('button', { name: 'Create brand' }).click()
+      await expect(dialog.getByRole('alert')).toHaveText('Enter a name.')
+      await expect(nameInput).toHaveAttribute('aria-invalid', 'true')
+      await expect(nameInput).toHaveAccessibleDescription('Enter a name.')
+      await expect(nameInput).toBeFocused()
+      await nameInput.fill('Ångström Plus')
+      await dialog.getByRole('button', { name: 'Create brand' }).click()
+      await expect(dialog.getByRole('alert')).toHaveText('Brand name already exists')
+      await expect(nameInput).toHaveValue('Ångström Plus')
+      await expect(nameInput).toHaveAttribute('aria-invalid', 'true')
+      await expect(nameInput).toHaveAccessibleDescription('Brand name already exists')
+      await expect(nameInput).toBeEnabled()
+      await expect(nameInput).toBeFocused()
+      await expect(slugInput).toHaveValue('custom-slug')
+      await expect(slugInput).not.toHaveAttribute('aria-invalid', 'true')
+    })
+  })
+
+  test('keeps a failed delete open and allows a retry', async ({ context, page }) => {
+    await mockBrandStore(context, [{
+      id: 10,
+      name: 'MSR',
+      slug: 'msr'
+    }])
+
+    const getAttempts = await mockRetryDelete(context)
+
+    await signIn({
+      context,
+      page,
+      isAdmin: true
+    })
+
+    await page.getByRole('button', { name: 'Delete MSR' }).click()
+
+    const dialog = page.getByRole('dialog', { name: 'Delete brand?' })
+
+    await dialog.getByRole('button', { name: 'Delete brand' }).click()
+    await expect(dialog.getByRole('alert')).toContainText('used by gear')
+    await dialog.getByRole('button', { name: 'Delete brand' }).click()
+    await expect(page.getByRole('button', { name: 'Delete MSR' })).toHaveCount(0)
+
+    const attempts = getAttempts()
+
+    expect(attempts).toBe(2)
+  })
+
+  test('fits the create dialog on a narrow screen and blocks duplicate pending saves', async ({ context, page }) => {
+    const pending = createDeferred()
+    const getCreates = await mockPendingBrandCreate(context, pending.promise)
+
+    await signIn({
+      context,
+      page,
+      isAdmin: true
+    })
+
+    await page.setViewportSize({
+      width: 320,
+      height: 720
+    })
+
+    await page.getByRole('button', { name: 'Add brand' }).click()
+
+    const dialog = await fillBrandDialog(page, 'MSR')
+
+    await test.step('keep the form inside the dialog and the narrow viewport', async () => {
+      const dialogGeometry = await dialog.evaluate((element) => {
+        const rectangle = element.getBoundingClientRect()
+        const { documentElement } = globalThis.document
+        const contentLeft = rectangle.left + element.clientLeft
+        const contentRight = contentLeft + element.clientWidth
+
+        return {
+          clientWidth: element.clientWidth,
+          scrollWidth: element.scrollWidth,
+          left: rectangle.left,
+          right: rectangle.right,
+          contentLeft,
+          contentRight,
+          documentWidth: documentElement.scrollWidth,
+          viewportWidth: documentElement.clientWidth
+        }
+      })
+
+      const formGeometry = await dialog.locator('form').evaluate((element) => {
+        const rectangle = element.getBoundingClientRect()
+
+        return {
+          left: rectangle.left,
+          right: rectangle.right
+        }
+      })
+
+      expect(dialogGeometry.scrollWidth).toBe(dialogGeometry.clientWidth)
+      expect(dialogGeometry.left).toBeGreaterThanOrEqual(0)
+      expect(dialogGeometry.right).toBeLessThanOrEqual(dialogGeometry.viewportWidth)
+      expect(dialogGeometry.documentWidth).toBeLessThanOrEqual(dialogGeometry.viewportWidth)
+      expect(formGeometry.left).toBeGreaterThanOrEqual(dialogGeometry.contentLeft)
+      expect(formGeometry.right).toBeLessThanOrEqual(dialogGeometry.contentRight)
+      await expect(dialog.getByRole('textbox', { name: 'Slug' })).toBeInViewport()
+      await expect(dialog.getByRole('button', { name: 'Cancel' })).toBeInViewport()
+      await expect(dialog.getByRole('button', { name: 'Create brand' })).toBeInViewport()
+    })
+
+    await test.step('disable repeated actions until the pending creation completes', async () => {
+      const createRequest = page.waitForRequest(isCreateBrandRequest)
+
+      await dialog.getByRole('button', { name: 'Create brand' }).click()
+
+      await createRequest
+
+      await expect(dialog.getByRole('button', { name: 'Create brand' })).toBeDisabled()
+      await expect(dialog.getByRole('button', { name: 'Cancel' })).toBeDisabled()
+      await expect(dialog.getByRole('textbox', { name: 'Name' })).toBeDisabled()
+      await expect.poll(getCreates).toBe(1)
+      pending.resolve()
+      await expect(page.getByRole('button', { name: 'Edit MSR' })).toBeVisible()
+    })
+  })
+})