feat: configure and display public seller descriptions

apps/api/src/modules/listings/repositories/listing-repository.js

@@ -273,6 +273,7 @@ export function createListingRepository(db) {
         marketValueCurrency: override?.currency ?? valuation?.currency ?? null,
         marketValueUpdatedAt: override?.createdAt ?? valuation?.calculatedAt ?? null,
         sellerDisplayName: result.sellerDisplayName,
+        sellerDescription: result.sellerSettings?.general?.publicDescription || null,
         sellerContactEmail: result.sellerSettings?.general?.publicContactEmail ?? null,
         sellerContactPhone: result.sellerSettings?.general?.publicContactPhone ?? null,
       };

apps/api/src/modules/products/repositories/product-repository.js

@@ -47,6 +47,7 @@ export function createProductRepository(db) {
       return {
         ...result.product,
         sellerDisplayName: result.sellerDisplayName,
+        sellerDescription: result.sellerSettings?.general?.publicDescription || null,
         sellerContactEmail: result.sellerSettings?.general?.publicContactEmail ?? null,
         sellerContactPhone: result.sellerSettings?.general?.publicContactPhone ?? null,
       };

apps/api/tests/application/seller-settings-service.test.js

@@ -40,3 +40,19 @@ test('rejects unknown or invalid settings', async () => {
     () => service.update({ sellerId: 'seller-1', settings: { secrets: { token: 'nope' } } }),
   );
 });
+
+
+test('seller descriptions are trimmed, bounded, preserved on partial updates and clearable', async () => {
+  let stored;
+  const service = createSellerSettingsService({ sellerSettingsRepository: {
+    async findBySellerId() { return stored; },
+    async upsert(sellerId, settings) { stored = { sellerId, settings }; return stored; },
+  } });
+  const update = (general) => service.update({ sellerId: 'seller-1', settings: { general } });
+  assert.equal((await update({ publicDescription: '  Collector.  ' })).general.publicDescription, 'Collector.');
+  assert.equal((await update({ publicContactPhone: '555-0100' })).general.publicDescription, 'Collector.');
+  await assert.rejects(() => update({ publicDescription: 'x'.repeat(2001) }));
+  await assert.rejects(() => update({ publicDescription: 123 }));
+  assert.equal((await update({ publicDescription: 'x'.repeat(2000) })).general.publicDescription.length, 2000);
+  assert.equal((await update({ publicDescription: '   ' })).general.publicDescription, '');
+});

apps/api/tests/http/public-listing-routes.test.js

@@ -37,6 +37,7 @@ function createTestApp() {
           askingPriceMinor: 2499,
           status: 'PENDING',
           sellerDisplayName: 'Pika Collectibles',
+          sellerDescription: 'Independent Pokémon collector.',
           sellerContactEmail: 'hello@pika.example',
           sellerContactPhone: null,
         };
@@ -76,6 +77,7 @@ test('returns a public listing detail or a not-found response', async (testConte
   assert.equal(detailResponse.statusCode, 200);
   assert.equal('inventoryItemId' in detailResponse.json().data, false);
   assert.equal(detailResponse.json().data.sellerDisplayName, 'Pika Collectibles');
+  assert.equal(detailResponse.json().data.sellerDescription, 'Independent Pokémon collector.');
   assert.equal(detailResponse.json().data.sellerContactEmail, 'hello@pika.example');
   assert.equal(missingResponse.statusCode, 404);
   assert.equal(missingResponse.json().error.code, 'LISTING_NOT_FOUND');

apps/api/tests/http/public-product-routes.test.js

@@ -22,6 +22,7 @@ function createTestApp() {
           slug,
           description: 'A friendly plush.',
           sellerDisplayName: 'Pika Collectibles',
+          sellerDescription: 'Independent Pokémon collector.',
           sellerContactEmail: 'hello@pika.example',
           sellerContactPhone: null,
           createdAt: new Date('2026-09-07T00:00:00.000Z'),
@@ -55,6 +56,7 @@ test('returns a public product without private seller identity', async (testCont
     releaseYear: null,
     tags: [],
     sellerDisplayName: 'Pika Collectibles',
+    sellerDescription: 'Independent Pokémon collector.',
     sellerContactEmail: 'hello@pika.example',
     sellerContactPhone: null,
     createdAt: '2026-09-07T00:00:00.000Z',

apps/api/tests/integration/catalog-repositories.test.js

@@ -17,6 +17,7 @@ import {
   products,
   securityAuditEvents,
   sellers,
+  sellerSettings,
   sessions,
   users,
 } from '../../src/infrastructure/database/schema.js';
@@ -190,6 +191,12 @@ test('finds only products with active inventory and a public listing', async ()
     product.id,
   );
 
+  assert.equal((await productRepository.findPublicBySlug(product.slug)).sellerDescription, null);
+  await database.db.insert(sellerSettings).values({ sellerId: seller.id, settings: { general: { publicDescription: 'Collector.' }, security: { sessionIdleMinutes: 60 } } });
+  assert.equal((await productRepository.findPublicBySlug(product.slug)).sellerDescription, 'Collector.');
+  await database.db.update(sellerSettings).set({ settings: { general: { publicDescription: '' } } });
+  assert.equal((await productRepository.findPublicBySlug(product.slug)).sellerDescription, null);
+
   await database.db
     .update(listings)
     .set({ status: 'CLOSED' })

apps/api/tests/integration/listing-repository.test.js

@@ -12,6 +12,7 @@ import {
   listings,
   products,
   sellers,
+  sellerSettings,
   users,
 } from '../../src/infrastructure/database/schema.js';
 import { createInventoryImageRepository } from '../../src/modules/inventory/repositories/inventory-image-repository.js';
@@ -148,6 +149,12 @@ test('searches public listings with pagination and hides sold items by default',
     visible.items[0].id,
   );
 
+  assert.equal((await listingRepository.findPublicById(visible.items[0].id)).sellerDescription, null);
+  await database.db.insert(sellerSettings).values({ sellerId: product.sellerId, settings: { general: { publicDescription: 'Collector.' }, security: { sessionIdleMinutes: 60 } } });
+  assert.equal((await listingRepository.findPublicById(visible.items[0].id)).sellerDescription, 'Collector.');
+  await database.db.update(sellerSettings).set({ settings: { general: { publicDescription: '' } } });
+  assert.equal((await listingRepository.findPublicById(visible.items[0].id)).sellerDescription, null);
+
   await database.db
     .update(listings)
     .set({ status: 'CLOSED' })

apps/web/src/assets/styles/global-tokens.scss

@@ -91,6 +91,9 @@
 }
 
 [data-theme='dark'] {
+  --color-success-text: #63d991;
+  --color-warning-text: #ffc766;
+  --color-danger-text: #ff9297;
   color-scheme: dark;
   --color-background: #0b0d10;
   --color-surface: #11161d;

apps/web/src/components/organisms/CollectibleDetail.stories.js

@@ -1,3 +1,4 @@
+import { expect, within } from '@storybook/test';
 import CollectibleDetail from "./CollectibleDetail.vue";
 
 export default {
@@ -24,6 +25,7 @@ export const ListingDetail = {
       { id: "front", label: "FRONT", alt: "Front of Charizard ex" },
       { id: "back", label: "BACK", alt: "Back of Charizard ex" },
     ],
+    sellerDescription: "Independent Pokémon collector.\nCarefully packed for fellow collectors.",
     sellerDisplayName: "Pika Collectibles",
     sellerContactEmail: "hello@pika.example",
     sellerContactPhone: "555-0100",
@@ -49,3 +51,20 @@ export const SoldListing = {
     condition: "Near Mint",
   },
 };
+
+export const SellerDescriptionPlainText = {
+  args: { ...ListingDetail.args, sellerDescription: '<strong>Collector</strong>', sellerContactEmail: '', sellerContactPhone: '' },
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).getByText('<strong>Collector</strong>')).toBeVisible();
+    await expect(canvasElement.querySelector('.collectible-detail__seller-description strong')).toBeNull();
+  },
+};
+export const SellerWithoutDescription = { args: { ...ListingDetail.args, sellerDescription: '' } };
+export const SellerDescriptionDark = {
+  args: ListingDetail.args,
+  globals: { theme: 'dark' },
+  decorators: [() => ({ template: '<div style="background: var(--color-background); color: var(--color-text); padding: 24px"><story /></div>' })],
+};
+
+export const PendingSellerDescriptionDark = { ...SellerDescriptionDark, args: { ...ListingDetail.args, status: 'PENDING' } };
+export const SoldSellerDescriptionDark = { ...SellerDescriptionDark, args: { ...ListingDetail.args, status: 'SOLD' } };

apps/web/src/components/organisms/CollectibleDetail.vue

@@ -15,6 +15,7 @@ defineProps({
   description: { type: String, default: "" },
   facts: { type: Array, default: () => [] },
   images: { type: Array, default: () => [] },
+  sellerDescription: { type: String, default: "" },
   sellerDisplayName: { type: String, default: "" },
   sellerContactEmail: { type: String, default: "" },
   sellerContactPhone: { type: String, default: "" },
@@ -50,9 +51,10 @@ defineProps({
           <dd>{{ fact.value }}</dd>
         </div>
       </dl>
-      <section v-if="sellerDisplayName" class="collectible-detail__seller" aria-labelledby="collectible-detail-seller-title">
+      <section v-if="sellerDisplayName || sellerDescription || sellerContactEmail || sellerContactPhone" class="collectible-detail__seller" aria-labelledby="collectible-detail-seller-title">
         <p id="collectible-detail-seller-title" class="catalog-kicker">Sold by</p>
         <p class="collectible-detail__seller-name">{{ sellerDisplayName }}</p>
+        <p v-if="sellerDescription" class="collectible-detail__seller-description">{{ sellerDescription }}</p>
         <ul v-if="sellerContactEmail || sellerContactPhone" class="collectible-detail__seller-contacts">
           <li v-if="sellerContactEmail"><a :href="`mailto:${sellerContactEmail}`">{{ sellerContactEmail }}</a></li>
           <li v-if="sellerContactPhone"><a :href="`tel:${sellerContactPhone}`">{{ sellerContactPhone }}</a></li>
@@ -90,6 +92,10 @@ defineProps({
 .collectible-detail__seller-name {
   font-weight: var(--weight-bold);
 }
+.collectible-detail__seller-description {
+  white-space: pre-line;
+  overflow-wrap: anywhere;
+}
 .collectible-detail__seller-contacts {
   display: grid;
   gap: var(--space-1);

apps/web/src/pages/AdminSettingsPage.stories.js

@@ -1,5 +1,34 @@
+import { expect, userEvent, within, waitFor } from '@storybook/test';
 import AdminSettingsPage from './AdminSettingsPage.vue';
 
-export default { title: 'Pages/AdminSettingsPage', component: AdminSettingsPage };
+export default {
+  title: 'Pages/AdminSettingsPage', component: AdminSettingsPage,
+  beforeEach: () => {
+    const originalFetch = globalThis.fetch;
+    let stored = { general: { publicDescription: 'Independent collector.', publicContactEmail: 'collector@example.test' } };
+    globalThis.fetch = async (url, options) => {
+      if (!String(url).endsWith('/admin/settings')) return originalFetch(url, options);
+      if (options?.method === 'PATCH') stored = JSON.parse(options.body);
+      return new Response(JSON.stringify({ data: stored }), { headers: { 'content-type': 'application/json' } });
+    };
+    return () => { globalThis.fetch = originalFetch; };
+  },
+};
 
 export const SettingsForm = {};
+export const EditAndClearDescription = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const field = await canvas.findByLabelText('Public seller description (optional)');
+    await expect(field).toHaveValue('Independent collector.');
+    await userEvent.clear(field);
+    await userEvent.type(field, 'Cards and collectibles.');
+    await userEvent.click(canvas.getByRole('button', { name: 'Save settings' }));
+    await waitFor(() => expect(canvas.getByRole('status')).toHaveTextContent('Settings saved.'));
+    await expect(field).toHaveValue('Cards and collectibles.');
+    await userEvent.clear(field);
+    await userEvent.click(canvas.getByRole('button', { name: 'Save settings' }));
+    await waitFor(() => expect(canvas.getByRole('status')).toHaveTextContent('Settings saved.'));
+    await expect(field).toHaveValue('');
+  },
+};

apps/web/src/pages/AdminSettingsPage.vue

@@ -4,7 +4,7 @@ import { onMounted, reactive, ref } from 'vue';
 import { getAdminSettings, updateAdminSettings } from '@/services/admin-settings-service.js';
 
 const settings = reactive({
-  general: { publicContactEmail: '', publicContactPhone: '' },
+  general: { publicDescription: '', publicContactEmail: '', publicContactPhone: '' },
   inventory: { maxImagesPerItem: 10 },
   pricing: { defaultStrategy: 'median' },
   security: { sessionIdleMinutes: 60 },
@@ -63,6 +63,9 @@ onMounted(load);
     <form v-if="!isLoading" class="admin-workspace-grid" @submit.prevent="save">
       <fieldset class="showcase-panel">
         <legend>General</legend>
+        <label class="fixture-label" for="settings-description">Public seller description (optional)</label>
+        <p id="settings-description-help">Shown on public listing and product pages. Up to 2,000 characters. Clear to remove.</p>
+        <textarea id="settings-description" v-model="settings.general.publicDescription" class="fixture-input" rows="5" maxlength="2000" aria-describedby="settings-description-help" />
         <label class="fixture-label" for="settings-email">Public contact email</label>
         <input id="settings-email" v-model="settings.general.publicContactEmail" class="fixture-input" type="email" />
         <label class="fixture-label" for="settings-phone">Public contact phone</label>

apps/web/src/pages/ListingDetailPage.stories.js

@@ -1,5 +1,21 @@
+import { expect, within } from '@storybook/test';
 import ListingDetailPage from './ListingDetailPage.vue';
 
 export default { title: 'Pages/ListingDetailPage', component: ListingDetailPage };
 
 export const Overview = {};
+
+export const PublicSellerDescription = {
+  beforeEach: () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async () => new Response(JSON.stringify({ data: {
+      id: 'listing-1', name: 'Pikachu', productName: 'Pikachu', status: 'AVAILABLE',
+      askingPriceMinor: 2500, sellerDisplayName: 'Pika Collectibles',
+      sellerDescription: 'Independent Pokémon collector.', images: [], tags: [],
+    } }), { headers: { 'content-type': 'application/json' } });
+    return () => { globalThis.fetch = originalFetch; };
+  },
+  play: async ({ canvasElement }) => {
+    await expect(await within(canvasElement).findByText('Independent Pokémon collector.')).toBeVisible();
+  },
+};

apps/web/src/pages/ListingDetailPage.vue

@@ -45,6 +45,7 @@ onMounted(async () => {
       "
       :description="listing.notes"
       :images="listing.images"
+      :seller-description="listing.sellerDescription"
       :seller-display-name="listing.sellerDisplayName"
       :seller-contact-email="listing.sellerContactEmail"
       :seller-contact-phone="listing.sellerContactPhone"

apps/web/src/pages/ProductDetailPage.stories.js

@@ -1,5 +1,21 @@
+import { expect, within } from '@storybook/test';
 import ProductDetailPage from './ProductDetailPage.vue';
 
 export default { title: 'Pages/ProductDetailPage', component: ProductDetailPage };
 
 export const Overview = {};
+
+export const PublicSellerDescription = {
+  beforeEach: () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async () => new Response(JSON.stringify({ data: {
+      id: 'listing-1', name: 'Pikachu', productName: 'Pikachu', status: 'AVAILABLE',
+      askingPriceMinor: 2500, sellerDisplayName: 'Pika Collectibles',
+      sellerDescription: 'Independent Pokémon collector.', images: [], tags: [],
+    } }), { headers: { 'content-type': 'application/json' } });
+    return () => { globalThis.fetch = originalFetch; };
+  },
+  play: async ({ canvasElement }) => {
+    await expect(await within(canvasElement).findByText('Independent Pokémon collector.')).toBeVisible();
+  },
+};

apps/web/src/pages/ProductDetailPage.vue

@@ -37,6 +37,7 @@ onMounted(async () => {
         ...(product.cardNumber ? [{ label: 'Card number', value: product.cardNumber }] : []),
         ...(product.releaseYear ? [{ label: 'Release year', value: product.releaseYear }] : []),
       ]"
+      :seller-description="product.sellerDescription"
       :seller-display-name="product.sellerDisplayName"
       :seller-contact-email="product.sellerContactEmail"
       :seller-contact-phone="product.sellerContactPhone"