Merge pull request 'feat(shard)!: Protocol 3.0 cutover — visibility framework, spawn atlas, marketplace' (#118) from edge into main

Reviewed-on: #118
Reviewed-by: Colby Whitlock <whitlocktech@gmail.com>

.env.example

@@ -117,7 +117,10 @@ BOT_INTERNAL_KEY=change-me-to-a-long-random-string
 # token). These URLs are just defaults; the admin can override them at runtime.
 UOLINK_BASE_URL=http://127.0.0.1:8080
 UOLINK_WS_URL=ws://127.0.0.1:8080/ws
-UOLINK_PROTOCOL=1
+# Wire protocol this build speaks (3 = Protocol 3.0). Only a fallback for a site
+# with nothing saved yet — the admin panel's pinned value wins — but set it lower
+# if you deliberately run an older sidecar.
+UOLINK_PROTOCOL=3
 
 # ─── Push notifications (M7) — self-hosted ntfy UnifiedPush relay ───
 # The `ntfy` compose service and the backend's push fan-out (opt-in notifications

.gitignore

@@ -28,6 +28,17 @@ logs/
 # See docs/website/SPAWN_ATLAS.md and db/data/spawnAtlas.art.example.json.
 server/db/data/spawnAtlas.art.json
 
+# Operator-supplied cliloc table. UO's localization strings are EA's, extracted
+# from the operator's own client and converted once (docs/website/CLILOCS.md);
+# the repo ships no string table, for the same reason it ships no artwork and no
+# map snapshot. This covers the conventional in-repo location — the supported
+# arrangement is a path OUTSIDE the repo, set from Admin → Shard.
+server/db/data/cliloc*
+server/db/data/clilocs.*
+# The build output of tools/cliloc-export (a throwaway helper, not a package).
+server/tools/cliloc-export/bin/
+server/tools/cliloc-export/obj/
+
 # reference material (extracted from the provided archives)
 _reference/
 

client/src/App.jsx

@@ -26,6 +26,8 @@ import Rules from './routes/public/Rules.jsx'
 import Atlas from './routes/public/Atlas.jsx'
 import AtlasCreature from './routes/public/AtlasCreature.jsx'
 import Leaderboards from './routes/public/Leaderboards.jsx'
+import Market from './routes/public/Market.jsx'
+import MarketVendor from './routes/public/MarketVendor.jsx'
 import Wiki from './routes/wiki/Wiki.jsx'
 import WikiArticle from './routes/wiki/WikiArticle.jsx'
 import CmsPage from './routes/public/CmsPage.jsx'
@@ -107,6 +109,8 @@ export default function App() {
             <Route path="/site/atlas" element={<Atlas />} />
             <Route path="/site/atlas/:slug" element={<AtlasCreature />} />
             <Route path="/site/leaderboards" element={<Leaderboards />} />
+            <Route path="/site/market" element={<Market />} />
+            <Route path="/site/market/vendors/:serial" element={<MarketVendor />} />
             <Route path="/wiki" element={<Wiki />} />
             <Route path="/wiki/:slug" element={<WikiArticle />} />
             {/* CMS pages: top-level /:slug, matched only after the named routes

client/src/api/client.js

@@ -154,6 +154,28 @@ export const api = {
     // `board` 404s for a system the shard has never published.
     points: () => req('/public/shard/points'),
     pointsBoard: (system) => req(`/public/shard/points/${encodeURIComponent(system)}`),
+    // Protocol 3.0: the player-vendor marketplace. Rate-limited server-side, so
+    // the page debounces its search box rather than firing per keystroke.
+    market: (opts = {}) => {
+      const qs = new URLSearchParams()
+      if (opts.q) qs.set('q', opts.q)
+      if (opts.minPrice != null && opts.minPrice !== '') qs.set('minPrice', opts.minPrice)
+      if (opts.maxPrice != null && opts.maxPrice !== '') qs.set('maxPrice', opts.maxPrice)
+      if (opts.itemId != null && opts.itemId !== '') qs.set('itemId', opts.itemId)
+      if (opts.map) qs.set('map', opts.map)
+      if (opts.region) qs.set('region', opts.region)
+      if (opts.sort) qs.set('sort', opts.sort)
+      if (opts.limit) qs.set('limit', opts.limit)
+      if (opts.offset) qs.set('offset', opts.offset)
+      return req(`/public/shard/market${withQs(qs.toString())}`)
+    },
+    marketMeta: () => req('/public/shard/market/meta'),
+    marketVendor: (serial, opts = {}) => {
+      const qs = new URLSearchParams()
+      if (opts.limit) qs.set('limit', opts.limit)
+      if (opts.offset) qs.set('offset', opts.offset)
+      return req(`/public/shard/market/vendors/${encodeURIComponent(serial)}${withQs(qs.toString())}`)
+    },
     // Which shard surfaces this caller may reach, plus the audience rung they
     // resolved to. Drives nav so we never render a link that would 403.
     features: () => req('/public/shard/features'),

client/src/components/CharacterSheet.jsx

@@ -10,21 +10,42 @@ import ShardAccountActions from './ShardAccountActions.jsx'
 
 const RESIST_LABELS = { phys: 'Physical', fire: 'Fire', cold: 'Cold', pois: 'Poison', energy: 'Energy' }
 
+// What to call an equipped item.
+//
+// Items on the wire carry a `LabelNumber`, not a name, so this used to be able
+// to show nothing but the layer and `id 12345`. The server now resolves the
+// cliloc against its own table and attaches `clilocName` (see
+// docs/website/CLILOCS.md); a shard with no cliloc file configured sends none,
+// and the layer fallback below is exactly what the sheet did before.
+//
+// A player-given `name` outranks the resolved type name — "Bob's lucky axe"
+// should not be relabelled "hatchet" — and the server applies the same
+// precedence, so this only re-states it for a profile that arrived with both.
+const itemName = (it) => it.name || it.clilocName || it.layer || 'Item'
+
 // The char.profile `titles` block (Protocol 2.0). fameKarma/skill are already
 // computed display strings; reward entries may be a cliloc NUMBER-as-string or a
-// literal string. Without a cliloc table on the site we can only show literals, so
-// numeric reward entries are skipped rather than shown as a raw number. Returns a
-// de-duped list of human-readable title chips.
+// literal string.
+//
+// `rewardResolved` is the server's parallel array with the numeric entries turned
+// into words (null where the cliloc table had nothing, or is not configured at
+// all). Prefer it, and keep the literal-only path as the fallback for a profile
+// served before the cliloc table existed — a numeric entry with no resolution is
+// still skipped rather than shown as a raw number.
 function displayTitles(titles) {
   if (!titles) return []
   const out = []
   if (titles.fameKarma) out.push(titles.fameKarma)
   if (titles.skill) out.push(titles.skill)
-  const reward = Array.isArray(titles.reward) ? titles.reward : []
+  const raw = Array.isArray(titles.reward) ? titles.reward : []
+  const resolved = Array.isArray(titles.rewardResolved) ? titles.rewardResolved : null
+  const reward = raw.map((r, i) => resolved?.[i] ?? (/^\d+$/.test(String(r)) ? null : String(r)))
   const sel = typeof titles.selected === 'number' ? titles.selected : -1
-  // Prefer the selected reward title; fall back to the first literal one.
-  const candidate = sel >= 0 && sel < reward.length ? reward[sel] : reward.find((r) => r && !/^\d+$/.test(String(r)))
-  if (candidate && !/^\d+$/.test(String(candidate))) out.push(String(candidate))
+  // Prefer the selected reward title; fall back to the first one that resolved.
+  // The `??` matters: a selected title whose cliloc did not resolve must fall
+  // through to the fallback rather than suppress the chip entirely.
+  const candidate = (sel >= 0 && sel < reward.length ? reward[sel] : null) ?? reward.find(Boolean)
+  if (candidate) out.push(String(candidate))
   return [...new Set(out.filter(Boolean))]
 }
 
@@ -241,12 +262,18 @@ export default function CharacterSheet({ char, moderation = false }) {
         <section>
           <div className="field-label" style={{ marginBottom: 8 }}>Equipment</div>
           <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
-            {equipment.map((it) => (
+            {equipment.map((it) => {
+              const label = itemName(it)
+              const layer = it.layer || 'Item'
+              // The layer only earns its own line once the headline is a real
+              // name; when it IS the headline, repeating it is just noise.
+              const detail = [label === layer ? null : layer, `id ${it.itemId}`, it.hue ? `hue ${it.hue}` : null]
+              return (
               <div key={it.serial} style={{ display: 'flex', alignItems: 'center', gap: 12, padding: '10px 14px', border: '1px solid var(--line)', borderRadius: 8 }}>
                 <span style={{ flex: 'none', width: 22, height: 22, borderRadius: 5, border: '1px solid var(--line)', background: 'rgba(255,255,255,0.05)' }} />
                 <div style={{ flex: 1, minWidth: 0 }}>
-                  <div className="sans" style={{ color: 'var(--head)', fontSize: '0.88rem' }}>{it.layer || 'Item'}</div>
-                  <div className="sans dim" style={{ fontSize: '0.74rem' }}>id {it.itemId}{it.hue ? ` · hue ${it.hue}` : ''}</div>
+                  <div className="sans" style={{ color: 'var(--head)', fontSize: '0.88rem' }}>{label}</div>
+                  <div className="sans dim" style={{ fontSize: '0.74rem' }}>{detail.filter(Boolean).join(' · ')}</div>
                 </div>
                 {it.mods && Object.keys(it.mods).length > 0 && (
                   <div className="sans" style={{ display: 'flex', gap: 6, flexWrap: 'wrap', justifyContent: 'flex-end', maxWidth: '55%' }}>
@@ -256,7 +283,8 @@ export default function CharacterSheet({ char, moderation = false }) {
                   </div>
                 )}
               </div>
-            ))}
+              )
+            })}
           </div>
         </section>
       )}

client/src/components/SiteHeader.jsx

@@ -26,6 +26,7 @@ const NAV = [
   { label: 'Rules', to: '/site/rules', feature: 'ruleset' },
   { label: 'Atlas', to: '/site/atlas', feature: 'atlas' },
   { label: 'Leaderboards', to: '/site/leaderboards', feature: 'leaderboards' },
+  { label: 'Market', to: '/site/market', feature: 'market' },
   { label: 'About', to: '/site/about' },
 ]
 

client/src/routes/admin/views/ShardAdmin.jsx

@@ -155,7 +155,7 @@ export default function ShardAdmin() {
   const [baseUrl, setBaseUrl] = useState('')
   const [wsUrl, setWsUrl] = useState('')
   const [token, setToken] = useState('')
-  const [protocol, setProtocol] = useState(1)
+  const [protocol, setProtocol] = useState(3)
   const [enabled, setEnabled] = useState(false)
   const [busy, setBusy] = useState(false)
   const [msg, setMsg] = useState('')
@@ -172,7 +172,7 @@ export default function ShardAdmin() {
       if (!initializedRef.current) {
         setBaseUrl(c.baseUrl || '')
         setWsUrl(c.wsUrl || '')
-        setProtocol(c.protocol || 1)
+        setProtocol(c.protocol || 3)
         setEnabled(c.enabled)
         initializedRef.current = true
       }

client/src/routes/admin/views/ShardVisibility.jsx

@@ -70,6 +70,10 @@ const FIELD_LABEL = {
   // field's meaning. The label is what carries the meaning to the admin.
   name: 'Character names on leaderboards',
   ownerName: 'Vendor owner name',
+  // One rule, one key — `location` is a nested object on both the wire frame and
+  // the stored read model precisely so that hiding it takes the facet, the
+  // coordinates, the region and the house together.
+  ownerSerial: 'Vendor owner character id',
 }
 
 function RungSelect({ value, onChange, ladder, disabled }) {

client/src/routes/public/Leaderboards.jsx

@@ -5,6 +5,7 @@ import { Loading, ErrorState } from '../../components/PageState.jsx'
 import { useAsync } from '../../lib/useAsync.js'
 import { useShardFeed } from '../../lib/useShardFeed.js'
 import { api } from '../../api/client.js'
+import { useSite } from '../../contexts/SiteContext.jsx'
 
 // Points / loyalty leaderboards (Protocol 3.0 §7). The shard carries ~25 separate
 // point currencies — Queen's Loyalty, Void Pool, Clean Up Britannia, the nine city
@@ -96,6 +97,7 @@ function Entry({ entry, best }) {
 }
 
 function Board({ board }) {
+  const { siteTitle } = useSite()
   const top = Array.isArray(board.top) ? board.top : []
   // Bars are relative to the board leader, not to maxPoints: most systems have no
   // cap (maxPoints 0), and where there is one the leader is often nowhere near it,
@@ -116,9 +118,28 @@ function Board({ board }) {
       </div>
 
       {top.length === 0 ? (
-        <p className="sans dim" style={{ margin: 0, fontSize: '0.84rem' }}>
-          Nobody has earned points here yet.
-        </p>
+        // A board nobody has scored on still gets a row, so the page reads as a set
+        // of standings waiting to be filled rather than a stack of blanks. It is
+        // deliberately NOT shaped like an Entry — no medal, no bar, an em dash where
+        // a score goes — because a placeholder that looked like a real standing would
+        // be a fabricated one. The first real entry replaces it.
+        <div>
+          <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline', gap: 10, padding: '6px 0' }}>
+            <span
+              className="sans"
+              style={{
+                color: 'var(--muted)', fontSize: '0.86rem',
+                overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+              }}
+            >
+              {siteTitle}
+            </span>
+            <span className="sans dim" style={{ fontSize: '0.82rem', flex: 'none' }}>&mdash;</span>
+          </div>
+          <p className="sans dim" style={{ margin: 0, fontSize: '0.78rem' }}>
+            Nobody has earned points here yet.
+          </p>
+        </div>
       ) : (
         <div>
           {top.map((entry) => (

client/src/routes/public/Market.jsx

@@ -0,0 +1,325 @@
+import { useCallback, useEffect, useState } from 'react'
+import { Link } from 'react-router-dom'
+import PublicLayout from '../../components/PublicLayout.jsx'
+import PageHeader from '../../components/PageHeader.jsx'
+import { Loading, ErrorState, EmptyState } from '../../components/PageState.jsx'
+import { useAsync } from '../../lib/useAsync.js'
+import { api } from '../../api/client.js'
+
+// ── The player-vendor marketplace ───────────────────────────────────────────
+//
+// What every player vendor on the shard is selling, for how much, and where it
+// is standing — the same index the in-game Vendor Search gump reads, honouring
+// the same per-vendor opt-out, reachable without logging in to the game.
+//
+// Three things this page must be honest about, all of them consequences of how
+// the data is gathered (docs/link/v3.md §8):
+//
+//   • **The prices are not live.** The shard sweeps vendors round-robin, so a
+//     shop can be a full cycle behind. The banner says how far, from `staleAt`.
+//     A page that implied live prices would send people across the world to a
+//     vendor whose item sold twenty minutes ago.
+//   • **A shop can be truncated.** A commodity reseller with thousands of stacks
+//     publishes only the first N, and saying so beats presenting a partial shop
+//     as complete.
+//   • **An item may have no name.** On a shard whose operator has not converted
+//     a cliloc table, `displayName` is null and the honest render is the item id
+//     — not an invented name.
+//
+// There is deliberately no live feed here. The market feature's SSE stream ships
+// disabled: a firehose of whole vendor inventories would be the site's single
+// biggest bandwidth consumer, and nothing on this page needs it.
+
+const PAGE = 50
+
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v).toLocaleString() : '—')
+
+const SORTS = [
+  { key: 'price_asc', label: 'Cheapest' },
+  { key: 'price_desc', label: 'Priciest' },
+  { key: 'recent', label: 'Recently seen' },
+]
+
+// How old the index may be, in words. `staleAt` is the OLDEST vendor row, so
+// this is a worst case rather than an average — which is the number worth
+// showing, because the one stale shop is the one that wastes a trip.
+function staleness(staleAt) {
+  if (!staleAt) return null
+  const ms = Date.now() - new Date(staleAt).getTime()
+  if (!Number.isFinite(ms) || ms < 0) return null
+  const mins = Math.round(ms / 60000)
+  if (mins < 1) return 'just now'
+  if (mins < 60) return `${mins} minute${mins === 1 ? '' : 's'} ago`
+  const hours = Math.round(mins / 60)
+  if (hours < 48) return `${hours} hour${hours === 1 ? '' : 's'} ago`
+  return `${Math.round(hours / 24)} days ago`
+}
+
+// The item's name, or an honest statement that we do not have one. Never a
+// fabricated label — "Item 3922" would be indistinguishable from a real name.
+const itemLabel = (l) => l.displayName || l.name || `id ${l.itemId}`
+
+function Chip({ active, onClick, children }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="sans"
+      style={{
+        fontSize: '0.78rem',
+        padding: '5px 12px',
+        borderRadius: 999,
+        cursor: 'pointer',
+        color: active ? 'var(--bg-deep)' : 'var(--muted)',
+        background: active ? 'var(--accent)' : 'transparent',
+        border: `1px solid ${active ? 'var(--accent)' : 'var(--line)'}`,
+      }}
+    >
+      {children}
+    </button>
+  )
+}
+
+function ListingRow({ listing }) {
+  const v = listing.vendor || {}
+  // `location` is one field the admin can gate away wholesale, so everything
+  // that reads from it has to tolerate its absence rather than assuming a map.
+  const loc = v.location || null
+  const where = loc ? [loc.region, loc.map].filter(Boolean).join(', ') : null
+
+  return (
+    <div className="panel" style={{ padding: '13px 15px', display: 'flex', gap: 14, alignItems: 'center' }}>
+      <div style={{ minWidth: 0, flex: 1 }}>
+        <div
+          className="display"
+          style={{ fontSize: '0.98rem', color: 'var(--head)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}
+        >
+          {listing.amount > 1 ? `${num(listing.amount)} × ` : ''}
+          {itemLabel(listing)}
+        </div>
+        <div className="sans dim" style={{ fontSize: '0.74rem', marginTop: 3 }}>
+          {v.serial ? (
+            <Link to={`/site/market/vendors/${encodeURIComponent(v.serial)}`} style={{ color: 'inherit' }}>
+              {v.shopName || 'an unnamed shop'}
+            </Link>
+          ) : (
+            v.shopName || 'an unnamed shop'
+          )}
+          {v.ownerName ? ` · ${v.ownerName}` : ''}
+          {where ? ` · ${where}` : ''}
+          {/* Priced by the container it sits in, exactly as the in-game search
+              reports it — the price buys the whole container, not this item. */}
+          {listing.child ? ' · sold with its container' : ''}
+        </div>
+      </div>
+      <div className="sans" style={{ flex: 'none', textAlign: 'right' }}>
+        <div style={{ color: 'var(--head)', fontSize: '0.92rem' }}>{num(listing.price)}</div>
+        <div className="dim" style={{ fontSize: '0.68rem', letterSpacing: '0.05em' }}>gold</div>
+      </div>
+    </div>
+  )
+}
+
+export default function Market() {
+  const [input, setInput] = useState('')
+  const [q, setQ] = useState('')
+  const [map, setMap] = useState('')
+  const [region, setRegion] = useState('')
+  const [sort, setSort] = useState('price_asc')
+  const [minPrice, setMinPrice] = useState('')
+  const [maxPrice, setMaxPrice] = useState('')
+  // Applied prices are separate from the typed ones so the search fires when the
+  // user is done, not on every digit of "250000".
+  const [prices, setPrices] = useState({ min: '', max: '' })
+
+  const [state, setState] = useState({ loading: true, error: null, listings: [], total: 0, staleAt: null })
+  const [more, setMore] = useState(false)
+
+  const meta = useAsync(() => api.shard.marketMeta())
+
+  // Debounced: typing "vanquishing" should be one request, not eleven — and the
+  // endpoint is rate-limited, so an undebounced box would 429 a fast typist.
+  useEffect(() => {
+    const timer = setTimeout(() => setQ(input.trim()), 300)
+    return () => clearTimeout(timer)
+  }, [input])
+
+  useEffect(() => {
+    const timer = setTimeout(() => setPrices({ min: minPrice, max: maxPrice }), 500)
+    return () => clearTimeout(timer)
+  }, [minPrice, maxPrice])
+
+  const load = useCallback(
+    (offset) =>
+      api.shard.market({
+        q,
+        map,
+        region,
+        sort,
+        minPrice: prices.min,
+        maxPrice: prices.max,
+        limit: PAGE,
+        offset,
+      }),
+    [q, map, region, sort, prices],
+  )
+
+  useEffect(() => {
+    let alive = true
+    setState({ loading: true, error: null, listings: [], total: 0, staleAt: null })
+    load(0)
+      .then((page) => {
+        if (!alive) return
+        setState({
+          loading: false,
+          error: null,
+          listings: page.listings || [],
+          total: page.total || 0,
+          staleAt: page.staleAt || null,
+        })
+      })
+      .catch((error) => alive && setState({ loading: false, error, listings: [], total: 0, staleAt: null }))
+    return () => {
+      alive = false
+    }
+  }, [load])
+
+  const loadMore = async () => {
+    setMore(true)
+    try {
+      const page = await load(state.listings.length)
+      setState((s) => ({
+        ...s,
+        listings: [...s.listings, ...(page.listings || [])],
+        total: page.total ?? s.total,
+        staleAt: page.staleAt ?? s.staleAt,
+      }))
+    } catch {
+      // A failed "load more" leaves what is on screen alone; the button stays
+      // available to retry.
+    } finally {
+      setMore(false)
+    }
+  }
+
+  const maps = meta.data?.maps || []
+  const regions = meta.data?.regions || []
+  const age = staleness(state.staleAt)
+
+  return (
+    <PublicLayout section="website">
+      <div className="shell-narrow page-body">
+        <PageHeader
+          eyebrow="Marketplace"
+          title="Player vendors"
+          lead="Every shop on the shard, searchable from here — the same index the in-game vendor search reads, and it honours the same per-vendor opt-out."
+        />
+
+        {/* Not decoration. The sweep is round-robin, so the index is inherently
+            up to one full cycle old and the page has to say so. */}
+        {age && (
+          <p className="sans dim" style={{ fontSize: '0.76rem', margin: '-12px 0 18px' }}>
+            Prices last refreshed {age}
+            {meta.data?.vendors ? ` · ${num(meta.data.vendors)} shops` : ''}
+            {meta.data?.items ? ` · ${num(meta.data.items)} listings` : ''}
+          </p>
+        )}
+
+        <input
+          className="input"
+          type="search"
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Search listings…"
+          style={{ width: '100%', marginBottom: 10 }}
+        />
+
+        <div style={{ display: 'flex', gap: 8, marginBottom: 12, flexWrap: 'wrap' }}>
+          <input
+            className="input"
+            type="number"
+            min="0"
+            value={minPrice}
+            onChange={(e) => setMinPrice(e.target.value)}
+            placeholder="Min price"
+            style={{ maxWidth: 140 }}
+          />
+          <input
+            className="input"
+            type="number"
+            min="0"
+            value={maxPrice}
+            onChange={(e) => setMaxPrice(e.target.value)}
+            placeholder="Max price"
+            style={{ maxWidth: 140 }}
+          />
+        </div>
+
+        <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginBottom: 10 }}>
+          {SORTS.map((s) => (
+            <Chip key={s.key} active={sort === s.key} onClick={() => setSort(s.key)}>
+              {s.label}
+            </Chip>
+          ))}
+        </div>
+
+        {/* Facet and region names come from the shard's own data, never a list in
+            this file — a shard running custom maps gets its own names here with
+            no code change (docs/link/v3.md §6.1 R2). */}
+        {maps.length > 0 && (
+          <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginBottom: 10 }}>
+            <Chip active={map === ''} onClick={() => setMap('')}>All facets</Chip>
+            {maps.map((m) => (
+              <Chip key={m} active={map === m} onClick={() => setMap(m)}>{m}</Chip>
+            ))}
+          </div>
+        )}
+
+        {regions.length > 0 && (
+          <select
+            className="input"
+            value={region}
+            onChange={(e) => setRegion(e.target.value)}
+            style={{ width: '100%', marginBottom: 18 }}
+          >
+            <option value="">Anywhere</option>
+            {regions.map((r) => (
+              <option key={r} value={r}>{r}</option>
+            ))}
+          </select>
+        )}
+
+        {state.loading && <Loading />}
+        {state.error && <ErrorState message="Could not load the marketplace right now." />}
+
+        {!state.loading && !state.error && state.listings.length === 0 && (
+          <EmptyState>
+            {meta.data?.vendors
+              ? 'Nothing on the shard matches that.'
+              : 'No player vendors have been indexed yet.'}
+          </EmptyState>
+        )}
+
+        {!state.loading && !state.error && state.listings.length > 0 && (
+          <>
+            <p className="sans dim" style={{ fontSize: '0.78rem', margin: '0 0 12px' }}>
+              Showing {num(state.listings.length)} of {num(state.total)}
+            </p>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+              {state.listings.map((l) => (
+                <ListingRow key={`${l.vendor?.serial}:${l.serial}`} listing={l} />
+              ))}
+            </div>
+            {state.listings.length < state.total && (
+              <div style={{ textAlign: 'center', marginTop: 16 }}>
+                <button type="button" className="btn" onClick={loadMore} disabled={more}>
+                  {more ? 'Loading…' : 'Load more'}
+                </button>
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    </PublicLayout>
+  )
+}

client/src/routes/public/MarketVendor.jsx

@@ -0,0 +1,102 @@
+import { Link, useParams } from 'react-router-dom'
+import PublicLayout from '../../components/PublicLayout.jsx'
+import PageHeader from '../../components/PageHeader.jsx'
+import { Loading, ErrorState, EmptyState } from '../../components/PageState.jsx'
+import { useAsync } from '../../lib/useAsync.js'
+import { api } from '../../api/client.js'
+
+// One player vendor: where to find it and everything it is selling.
+//
+// The page a search result points at. Two states it has to render honestly and
+// which the search list cannot (docs/link/v3.md §8):
+//
+//   • `truncated` — the shop holds more than the shard publishes per frame. A
+//     commodity reseller with thousands of stacks is a real thing, and showing
+//     250 of 3,104 as if it were the whole shop would be a lie about the shard.
+//   • a gated `location` — an admin may put vendor whereabouts behind a rung, in
+//     which case there is nothing to render and the page says so rather than
+//     showing an empty coordinate.
+
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v).toLocaleString() : '—')
+
+const itemLabel = (i) => i.displayName || i.name || `id ${i.itemId}`
+
+export default function MarketVendor() {
+  const { serial } = useParams()
+  const { loading, error, data } = useAsync(() => api.shard.marketVendor(serial), [serial])
+
+  if (loading) {
+    return (
+      <PublicLayout section="website">
+        <div className="shell-narrow page-body"><Loading /></div>
+      </PublicLayout>
+    )
+  }
+
+  if (error || !data) {
+    return (
+      <PublicLayout section="website">
+        <div className="shell-narrow page-body">
+          <ErrorState message="That shop is not in the index — it may have been dismissed or hidden." />
+          <p style={{ marginTop: 16 }}>
+            <Link to="/site/market" className="sans">← Back to the marketplace</Link>
+          </p>
+        </div>
+      </PublicLayout>
+    )
+  }
+
+  const loc = data.location || null
+  const items = data.items || []
+
+  return (
+    <PublicLayout section="website">
+      <div className="shell-narrow page-body">
+        <PageHeader
+          eyebrow={data.ownerName ? `Run by ${data.ownerName}` : 'Player vendor'}
+          title={data.shopName || 'An unnamed shop'}
+          lead={
+            loc
+              ? [loc.house, loc.region, loc.map].filter(Boolean).join(' · ') +
+                (Number.isFinite(loc.x) ? ` — ${loc.x}, ${loc.y}` : '')
+              : 'This shard does not publish vendor locations.'
+          }
+        />
+
+        <p className="sans dim" style={{ fontSize: '0.78rem', margin: '-12px 0 18px' }}>
+          {data.truncated
+            ? `Showing ${num(data.count)} of ${num(data.total)} listings — this shop holds more than the shard publishes.`
+            : `${num(data.total)} listing${data.total === 1 ? '' : 's'}`}
+          {data.updatedAt ? ` · last seen ${new Date(data.updatedAt).toLocaleString()}` : ''}
+        </p>
+
+        {items.length === 0 ? (
+          <EmptyState>This shop has nothing priced for sale.</EmptyState>
+        ) : (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+            {items.map((i) => (
+              <div
+                key={i.serial}
+                className="panel"
+                style={{ padding: '10px 14px', display: 'flex', gap: 12, alignItems: 'baseline' }}
+              >
+                <span className="sans" style={{ flex: 1, minWidth: 0, color: 'var(--head)', fontSize: '0.88rem' }}>
+                  {i.amount > 1 ? `${num(i.amount)} × ` : ''}
+                  {itemLabel(i)}
+                  {i.child ? <span className="dim"> · sold with its container</span> : null}
+                </span>
+                <span className="sans" style={{ flex: 'none', color: 'var(--head)', fontSize: '0.88rem' }}>
+                  {num(i.price)}
+                </span>
+              </div>
+            ))}
+          </div>
+        )}
+
+        <p style={{ marginTop: 20 }}>
+          <Link to="/site/market" className="sans">← Back to the marketplace</Link>
+        </p>
+      </div>
+    </PublicLayout>
+  )
+}

server/db/schema.sql

@@ -359,7 +359,7 @@ CREATE TABLE IF NOT EXISTS uo_link_config (
   base_url          VARCHAR(255) NULL,
   ws_url            VARCHAR(255) NULL,
   auth_token_enc    TEXT         NULL,
-  protocol          INT          NOT NULL DEFAULT 1,
+  protocol          INT          NOT NULL DEFAULT 3,
   enabled           TINYINT(1)   NOT NULL DEFAULT 0,
   status            VARCHAR(20)  NOT NULL DEFAULT 'disconnected',
   status_detail     VARCHAR(500) NULL,
@@ -640,6 +640,76 @@ CREATE TABLE IF NOT EXISTS shard_points_boards (
   updated_at    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
 
+-- Player-vendor market index (Protocol 3.0 vendor.listing). One row per player
+-- vendor and one per priced listing, so the site can offer the search the in-game
+-- Vendor Search gump offers — from outside the game.
+--
+-- The shard sweeps vendors round-robin and emits one AUTHORITATIVE frame per
+-- vendor, so ingest is delete-then-insert of that vendor's items inside one
+-- transaction (see shardMarket.db.js). No foreign key from items to vendors, in
+-- keeping with every other shard_* table: the ingest transaction is what keeps
+-- them consistent, and an FK would turn a malformed frame into a failed write
+-- rather than a dropped row.
+--
+-- Only vendors whose owner left the in-game Vendor Search flag ON are ever sent,
+-- so a player who hid their shop in game is hidden here too — see BridgeMarket.cs.
+CREATE TABLE IF NOT EXISTS shard_vendors (
+  serial       VARCHAR(20)  NOT NULL PRIMARY KEY,   -- "0x40001234"
+  shop_name    VARCHAR(160) NULL,
+  owner_serial VARCHAR(20)  NULL,
+  owner_name   VARCHAR(64)  NULL,
+  map          VARCHAR(40)  NULL,
+  x            INT          NULL,
+  y            INT          NULL,
+  z            INT          NULL,
+  region       VARCHAR(80)  NULL,
+  house        VARCHAR(160) NULL,                   -- the house SIGN's name, not the house type
+  item_count   INT          NOT NULL DEFAULT 0,     -- listings published in the frame
+  item_total   INT          NOT NULL DEFAULT 0,     -- listings the shop actually holds
+  truncated    TINYINT(1)   NOT NULL DEFAULT 0,     -- item_total > item_count
+  t            BIGINT       NULL,                   -- frame time, epoch ms
+  updated_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_shard_vendors_owner (owner_name),
+  INDEX idx_shard_vendors_map (map),
+  INDEX idx_shard_vendors_region (region),
+  -- The market page's staleness banner is MIN(updated_at) over this column: the
+  -- round-robin sweep means the oldest row is how far behind the index can be.
+  INDEX idx_shard_vendors_updated (updated_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- One priced listing. Unlike the points board's top-N — a fixed-size list read
+-- whole — these are the searchable rows the whole feature exists for, so they are
+-- normalized rather than left inside a payload column, and there is no payload
+-- column on shard_vendors at all.
+--
+-- `display_name` is DENORMALIZED at ingest: the shard sends `cliloc` (the item's
+-- LabelNumber) and, rarely, a literal `name`, and resolving 50 clilocs per page
+-- at query time would make the cliloc table a join on the hot path AND make
+-- search-by-name impossible. Resolving once on write buys the index. It is
+-- re-resolved in bulk after a cliloc import, because the diff sweep will not
+-- re-send an unchanged shop just because the site learned what its items are
+-- called.
+CREATE TABLE IF NOT EXISTS shard_vendor_items (
+  id            BIGINT       NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  vendor_serial VARCHAR(20)  NOT NULL,
+  serial        VARCHAR(20)  NOT NULL,
+  item_id       INT          NOT NULL DEFAULT 0,    -- ItemID (the art/graphic id)
+  hue           INT          NOT NULL DEFAULT 0,
+  amount        INT          NOT NULL DEFAULT 1,
+  price         BIGINT       NOT NULL DEFAULT 0,
+  name          VARCHAR(160) NULL,                  -- the item's literal Name, null for most
+  cliloc        INT          NULL,                  -- LabelNumber, resolved against shard_clilocs
+  display_name  VARCHAR(160) NULL,                  -- resolved at ingest; what search matches
+  child         TINYINT(1)   NOT NULL DEFAULT 0,    -- priced by an enclosing container, not itself
+  INDEX idx_shard_vendor_items_vendor (vendor_serial),
+  INDEX idx_shard_vendor_items_price (price),
+  INDEX idx_shard_vendor_items_item (item_id),
+  INDEX idx_shard_vendor_items_name (display_name),
+  -- Search filters on name and sorts on price; the composite covers the common
+  -- "cheapest matching X" without a filesort over the whole table.
+  INDEX idx_shard_vendor_items_name_price (display_name, price)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
 -- Per-feature visibility for every shard-derived surface (Protocol 3.0). One row
 -- per feature; an absent row means "use the compiled default", and the compiled
 -- defaults reproduce the behavior that shipped before v3 — so an empty table is
@@ -1180,6 +1250,39 @@ CREATE TABLE IF NOT EXISTS shard_champion_spawns (
   INDEX idx_shard_champion_spawns_facet (facet)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
 
+-- UO's localization table: cliloc id -> display string. Items carry a
+-- `LabelNumber` rather than a name, so without this the site can only render
+-- `id 1023721` where the game shows "quarter staff". The shard has always sent
+-- the id (char.profile's `cliloc`, and one per marketplace listing) — the number
+-- was never the missing piece, the table was.
+--
+-- Sourced from a file the OPERATOR converts once from their own UO client and
+-- points the site at (docs/website/CLILOCS.md); nothing derived from the client
+-- is committed, the same rule the spawn atlas and the creature art map follow.
+-- A shard with no cliloc file configured simply renders item ids, which is what
+-- it did before this table existed.
+--
+-- `text` is TEXT, not VARCHAR: real tables top out around 12 KB for the long
+-- property descriptions, and truncating them silently would be worse than
+-- storing them. Item NAMES are all short — the index that matters for search is
+-- on the denormalized `shard_vendor_items.display_name`, not here.
+CREATE TABLE IF NOT EXISTS shard_clilocs (
+  number      INT          NOT NULL PRIMARY KEY,
+  flag        SMALLINT     NOT NULL DEFAULT 0,
+  text        TEXT         NOT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Singleton (id = 1) describing the cliloc table currently loaded: the source
+-- file, its sha256, the entry count and the parser version. The boot path
+-- compares the stored hash against the file on disk and skips the parse when
+-- they match, which is every restart that did not follow a client patch.
+CREATE TABLE IF NOT EXISTS shard_cliloc_meta (
+  id          TINYINT      NOT NULL PRIMARY KEY DEFAULT 1,
+  payload     JSON         NOT NULL,
+  imported_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  CONSTRAINT chk_shard_cliloc_meta_singleton CHECK (id = 1)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
 -- Singleton (id = 1) describing the artifact currently loaded: when it was
 -- built, its counts, and a sha256 per ServUO source file. The admin drift check
 -- compares this against db/data/spawnAtlas.meta.json to report when the database
@@ -1294,3 +1397,19 @@ ALTER TABLE mobile_refresh_tokens ADD COLUMN IF NOT EXISTS last_used_at DATETIME
 -- trust token. A boolean only — the token is returned over that app→server call
 -- and never persisted here (only its sha256 lands in trusted_devices).
 ALTER TABLE mobile_auth_sessions ADD COLUMN IF NOT EXISTS trust_device TINYINT(1) NOT NULL DEFAULT 0;
+
+-- Protocol 3.0 cutover: this build speaks wire protocol 3 (world.ruleset,
+-- points.board, vendor.listing), so the pinned version an existing install
+-- carries has to move with it — a 2 against a v3 sidecar 409s every REST call
+-- and closes the WS on ws.hello. MODIFY fixes the column default for installs
+-- created before the bump (idempotent, like the other MODIFYs here).
+ALTER TABLE uo_link_config MODIFY COLUMN protocol INT NOT NULL DEFAULT 3;
+-- The row itself is admin-editable, and schema.sql runs on EVERY boot, so this
+-- must be one-shot: an operator who deliberately pins an older sidecar in
+-- Admin → Shard has to stay pinned. The marker row in `settings` is what makes
+-- it fire once — written after the UPDATE, and on a fresh install (no
+-- uo_link_config row yet) it is simply written with nothing to update.
+UPDATE uo_link_config SET protocol = 3
+  WHERE id = 1 AND protocol < 3
+    AND NOT EXISTS (SELECT 1 FROM settings WHERE `key` = 'uo_link_protocol_3_migrated');
+INSERT IGNORE INTO settings (`key`, value) VALUES ('uo_link_protocol_3_migrated', '1');

server/routes.guards.json

@@ -727,6 +727,37 @@
         "validate"
       ]
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/clilocs",
+      "handlers": 2,
+      "gates": [
+        "noindex",
+        "requireAuth"
+      ]
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/clilocs/import",
+      "handlers": 5,
+      "gates": [
+        "noindex",
+        "requireAuth",
+        "middleware",
+        "validate"
+      ]
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/clilocs/path",
+      "handlers": 4,
+      "gates": [
+        "noindex",
+        "requireAuth",
+        "middleware",
+        "validate"
+      ]
+    },
     {
       "method": "GET",
       "path": "/api/v1/admin/shard/houses",
@@ -1996,6 +2027,30 @@
       "handlers": 2,
       "gates": []
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market",
+      "handlers": 13,
+      "gates": [
+        "middleware",
+        "validate"
+      ]
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market/meta",
+      "handlers": 2,
+      "gates": []
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market/vendors/:serial",
+      "handlers": 7,
+      "gates": [
+        "middleware",
+        "validate"
+      ]
+    },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/online",

server/routes.manifest.json

@@ -293,6 +293,18 @@
       "method": "GET",
       "path": "/api/v1/admin/shard/char/:serial"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/clilocs"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/clilocs/import"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/clilocs/path"
+    },
     {
       "method": "GET",
       "path": "/api/v1/admin/shard/houses"
@@ -817,6 +829,18 @@
       "method": "GET",
       "path": "/api/v1/public/shard/idoc"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market/meta"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market/vendors/:serial"
+    },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/online"

server/src/middleware/rateLimit.js

@@ -118,6 +118,19 @@ const passwordResetConfirmLimiter = makeLimiter({
   message: 'Too many attempts. Please try again later.',
 })
 
+// The player-vendor market search. The first genuinely expensive PUBLIC endpoint
+// on the site: every call is a LIKE scan plus a COUNT over the listings table,
+// which on a large shard is the biggest table there is, and it is anonymous by
+// default. Generous for a human browsing shops (a typed search is debounced to
+// one request, and paging is a click), tight enough that it cannot be used as a
+// cheap way to load the database.
+const marketLimiter = makeLimiter({
+  windowMs: 60 * 1000,
+  max: 60,
+  label: 'market',
+  message: 'Too many searches. Please slow down.',
+})
+
 // CSP violation reports. Unauthenticated by necessity (browsers send them with no
 // session), and every accepted report writes a log line — so an attacker who can get
 // a victim to load a page could otherwise use it as a log-flood amplifier. Generous
@@ -141,5 +154,6 @@ module.exports = {
   mobileSsoExchangeLimiter,
   passwordResetRequestLimiter,
   passwordResetConfirmLimiter,
+  marketLimiter,
   cspReportLimiter,
 }

server/src/model/settings/settings.model.js

@@ -70,6 +70,24 @@ async function isMobileAppLinksEnabled() {
   }
 }
 
+/**
+ * This instance's name, resolved exactly as `getPublic().brand.name` resolves it —
+ * the admin-editable site title wins over BRAND_NAME. Anything that has to *speak*
+ * the instance's name outside the settings payload must use this rather than
+ * `brand.name`, or an install that set only the site title gets two different names
+ * on two different pages.
+ *
+ * Never throws: a name is always better than an error, so a DB fault falls back to
+ * the env value.
+ */
+async function getInstanceName() {
+  try {
+    return (await settingsDb.get('site_title')) || brand.name
+  } catch {
+    return brand.name
+  }
+}
+
 async function get(key) {
   return settingsDb.get(key)
 }
@@ -154,6 +172,7 @@ module.exports = {
   setMany,
   getAll,
   getPublic,
+  getInstanceName,
   PUBLIC_KEYS,
   REGISTRATION_KEY,
   REGISTRATION_MODES,

server/src/model/shardClilocs/shardClilocs.db.js

@@ -0,0 +1,108 @@
+const { pool, query } = require('../../utils/db')
+
+// Raw SQL for the cliloc table. `shard_clilocs` is IMPORT-OWNED: `replaceAll`
+// empties and refills it inside one transaction, and nothing else in the
+// codebase writes to it. No foreign keys, consistent with every other shard_*
+// table.
+
+const BATCH = 1000
+
+/**
+ * Replace the entire cliloc table in one transaction.
+ *
+ * All-or-nothing on purpose: a failed reload must leave the previous table
+ * intact rather than a half-loaded one, because a partially-imported cliloc
+ * table is indistinguishable from a complete one to anyone reading it — you
+ * would just see some items named and some not, which is also what "no table at
+ * all" looks like.
+ *
+ * `DELETE`, not `TRUNCATE` — `TRUNCATE` is DDL in MariaDB and implicitly
+ * commits, which would defeat exactly that guarantee. (The same trap the spawn
+ * atlas import documents; at ~123k rows `DELETE` is still well under a second.)
+ */
+async function replaceAll(entries, meta) {
+  const conn = await pool.getConnection()
+  try {
+    await conn.beginTransaction()
+    await conn.query('DELETE FROM shard_clilocs')
+
+    // Blank entries are dropped rather than stored. Roughly HALF of a real
+    // cliloc table is empty strings — ids the client reserves and never uses —
+    // and a row that resolves to no name is indistinguishable from no row at
+    // all to every caller. Dropping them halves the table (123,490 → ~67,500)
+    // and, more importantly, makes the binary and text imports converge on
+    // identical content: the binary format carries the blanks explicitly and a
+    // text export may or may not, depending on the tool.
+    //
+    // Later duplicates win. Merging across sources already happened upstream in
+    // `readCliloc`, so in practice this collapses nothing — it is kept because
+    // the plain format permits a repeated id WITHIN one file and the client's
+    // own loader resolves it the same way (its dictionary assignment
+    // overwrites). Without it, a file the game itself would load happily would
+    // fail the batch insert on a primary-key collision.
+    const byNumber = new Map()
+    let blank = 0
+    for (const entry of entries) {
+      if (!Number.isInteger(entry.number)) continue
+      if (String(entry.text ?? '').trim() === '') {
+        blank++
+        continue
+      }
+      byNumber.set(entry.number, entry)
+    }
+
+    const rows = [...byNumber.values()].map((e) => [e.number, e.flag ?? 0, e.text])
+    for (let i = 0; i < rows.length; i += BATCH) {
+      await conn.batch('INSERT INTO shard_clilocs (number, flag, text) VALUES (?,?,?)', rows.slice(i, i + BATCH))
+    }
+
+    await conn.query(
+      'INSERT INTO shard_cliloc_meta (id, payload) VALUES (1, ?) ' +
+        'ON DUPLICATE KEY UPDATE payload = VALUES(payload), imported_at = CURRENT_TIMESTAMP',
+      [JSON.stringify({ ...meta, count: rows.length })],
+    )
+
+    await conn.commit()
+    return { count: rows.length, blank, duplicates: entries.length - blank - rows.length }
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+async function getMeta() {
+  const rows = await query('SELECT payload, imported_at FROM shard_cliloc_meta WHERE id = 1')
+  if (rows.length === 0) return null
+  const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload
+  return { ...payload, importedAt: rows[0].imported_at }
+}
+
+/**
+ * Look up a batch of ids.
+ *
+ * Batched rather than one-at-a-time because every caller has a LIST: a character
+ * sheet resolves a dozen equipment ids at once, and a page of marketplace
+ * listings resolves fifty. `IN (...)` with generated placeholders keeps it one
+ * round trip and one parameterized statement.
+ */
+async function lookup(numbers) {
+  if (!Array.isArray(numbers) || numbers.length === 0) return []
+  const ids = [...new Set(numbers.filter((n) => Number.isInteger(n)))]
+  if (ids.length === 0) return []
+  const placeholders = ids.map(() => '?').join(',')
+  return query(`SELECT number, text FROM shard_clilocs WHERE number IN (${placeholders})`, ids)
+}
+
+async function count() {
+  const rows = await query('SELECT COUNT(*) AS n FROM shard_clilocs')
+  return Number(rows[0]?.n) || 0
+}
+
+module.exports = {
+  replaceAll,
+  getMeta,
+  lookup,
+  count,
+}

server/src/model/shardClilocs/shardClilocs.model.js

@@ -0,0 +1,368 @@
+const db = require('./shardClilocs.db')
+const settings = require('../settings/settings.model')
+const { displayText } = require('../../utils/clilocParse')
+const {
+  ClilocFormatError,
+  ClilocSourceError,
+  PARSER_VERSION,
+  hashSources,
+  sameSources,
+  missingSources,
+  readCliloc,
+} = require('../../utils/clilocSource')
+const log = require('../../utils/logger')('shardClilocs')
+
+// The cliloc table — UO's id → display-string map, refreshed from a file the
+// operator converts once from their own client.
+//
+// Why the site holds this at all: items on the wire carry a `LabelNumber`, not a
+// name. `char.profile.equipment` has always sent `cliloc`, and every marketplace
+// listing sends one too. Without the table the UI can only print `id 1023721`
+// where the game prints "quarter staff".
+//
+// Two rules govern the boot path, both inherited from the spawn atlas:
+//
+//   1. **It never blocks startup.** No configured path, an unreadable file, a
+//      wrong-format file, a database error — all caught and logged. The site
+//      comes up either way, serving whatever table it already had (or none, in
+//      which case the UI falls back to item ids exactly as it did before).
+//   2. **Nothing client-derived is committed.** The table is built from the
+//      operator's own file at a configured path. The repo ships no strings.
+//
+// The table is built from a SET of sources — the converted client table plus
+// every operator-maintained overlay beside it — because shards edit items and
+// add new ones, and those carry cliloc ids no stock client table has. All of
+// them are re-read on every boot and hash-gated together, so adding one custom
+// item never means re-exporting a 5 MB client file. Later sources win.
+//
+// That set is also why this has the atlas's escalation, in a lighter form. A
+// single corrupt file fails the parse loudly, but a source that has simply
+// VANISHED parses perfectly and imports a table quietly missing everything it
+// contributed — the same ambiguity (real change vs half-copied mount) the atlas
+// stages a facet removal for. So a disappearing source is refused and reported
+// rather than applied.
+//
+// It is lighter than the atlas's because it needs to be: the atlas stores a
+// pending decision in its own table and adds approve/reject endpoints, whereas
+// here the decision is a single boolean an admin passes to the import they were
+// already going to run. Re-parsing at approval time — the property that makes
+// the atlas store only the decision — is automatic when there is nothing stored.
+
+const SETTING_KEY = 'cliloc_client_path'
+
+/**
+ * Where the converted cliloc file lives.
+ *
+ * The admin setting wins over the environment so an operator can repoint it
+ * without a redeploy, matching how the rest of the shard integration is
+ * admin-managed rather than env-configured. `UO_CLIENT_PATH` remains as the
+ * deploy-time default, since the path usually describes a mount the deployment
+ * sets up.
+ */
+async function getClientPath() {
+  try {
+    const configured = await settings.get(SETTING_KEY)
+    if (configured && String(configured).trim() !== '') return String(configured).trim()
+  } catch {
+    // Settings unavailable is not fatal — fall through to the env default.
+  }
+  const fromEnv = process.env.UO_CLIENT_PATH
+  return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : ''
+}
+
+async function setClientPath(value, updatedBy = null) {
+  const result = await settings.set(SETTING_KEY, String(value ?? '').trim(), updatedBy)
+  invalidate()
+  return result
+}
+
+// ── Refresh ────────────────────────────────────────────────────────────────
+
+/** Was the loaded table built by THIS parser? */
+const currentParser = (meta) => meta?.parserVersion === PARSER_VERSION
+
+/**
+ * Refresh the cliloc table from the configured file.
+ *
+ * Returns a result describing what happened rather than throwing, so the caller
+ * — including the boot path — can log it and move on:
+ *
+ *   `skipped`     no path configured
+ *   `unavailable` path configured but missing / unreadable / not a cliloc file
+ *   `unchanged`   source hashes match the loaded table; nothing parsed
+ *   `imported`    parsed and applied
+ *   `needsReview` a previously-present source has vanished; NOT applied
+ *   `failed`      parsed or applied and something went wrong
+ *
+ * `force` skips the hash check (an admin asking for a reimport). `approve`
+ * additionally accepts a vanished source.
+ */
+async function refresh({ force = false, approve = false, path: pathOverride = '' } = {}) {
+  // An explicit override wins outright — a one-off "use this file", which must
+  // not be silently overruled by the configured path the way an env default is.
+  const configured = pathOverride.trim() !== '' ? pathOverride.trim() : await getClientPath()
+  if (configured === '') return { status: 'skipped', reason: 'no cliloc path configured' }
+
+  let fingerprint
+  try {
+    fingerprint = hashSources(configured)
+  } catch (err) {
+    if (err instanceof ClilocSourceError) {
+      return { status: 'unavailable', reason: err.message, code: err.code, path: configured }
+    }
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+
+  const meta = await db.getMeta().catch(() => null)
+
+  // Two things make a loaded table stale: any source changed, or the PARSER did.
+  // Only checking the sources would strand an install whose client never patches
+  // on whatever an older build derived.
+  if (!force && sameSources(fingerprint.hashes, meta?.hashes) && currentParser(meta)) {
+    return {
+      status: 'unchanged',
+      path: configured,
+      file: fingerprint.file,
+      count: meta.count ?? null,
+      customCount: fingerprint.customCount,
+    }
+  }
+
+  // A source that was there last import and is not there now is refused, not
+  // applied — an unmounted volume and a deliberate deletion look identical from
+  // here, and the wrong guess silently drops every name that file contributed.
+  const gone = missingSources(fingerprint.hashes, meta?.hashes)
+  if (gone.length > 0 && !approve) {
+    return {
+      status: 'needsReview',
+      reason: `${gone.length} previously-loaded cliloc source(s) are missing; the existing table is unchanged`,
+      missingSources: gone,
+      path: configured,
+      file: fingerprint.file,
+    }
+  }
+
+  let parsed
+  try {
+    parsed = readCliloc(configured)
+  } catch (err) {
+    if (err instanceof ClilocFormatError || err instanceof ClilocSourceError) {
+      return { status: 'unavailable', reason: err.message, code: err.code, path: configured }
+    }
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+
+  try {
+    const applied = await db.replaceAll(parsed.entries, parsed.source)
+    invalidate()
+    return {
+      status: 'imported',
+      path: configured,
+      file: parsed.source.file,
+      count: applied.count,
+      parsed: parsed.entries.length,
+      blank: applied.blank,
+      // Per-source breakdown: how many entries each file contributed and how
+      // many of them overrode something already merged. An operator who adds an
+      // overlay wants to see it took effect, and "overrode: 0" on a file meant
+      // to re-label stock items says it did not.
+      sources: parsed.source.sources,
+      acceptedMissing: gone.length > 0 ? gone : undefined,
+    }
+  } catch (err) {
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+}
+
+/**
+ * Boot hook. Best-effort by contract: it logs and returns, never throws, so a
+ * missing or malformed cliloc file can never stop the site coming up.
+ */
+async function refreshOnBoot() {
+  try {
+    const result = await refresh()
+    switch (result.status) {
+      case 'imported':
+        log.info('cliloc table refreshed', {
+          file: result.file,
+          count: result.count,
+          overlays: (result.sources || []).filter((s) => s.kind === 'custom').length,
+        })
+        break
+      case 'needsReview':
+        log.warn(
+          'cliloc refresh staged for admin review — a previously-loaded source is missing; ' +
+            'the existing table is unchanged',
+          { missing: result.missingSources },
+        )
+        break
+      case 'unavailable':
+        // Deliberately a warning, not an error: an operator who has not supplied
+        // a cliloc file is in a supported state (the UI shows item ids), and the
+        // most common cause — pointing at the client's own compressed file —
+        // needs the reason spelled out rather than a stack trace.
+        log.warn('cliloc source unavailable (item names will show as ids)', {
+          reason: result.reason,
+          code: result.code,
+          path: result.path,
+        })
+        break
+      case 'failed':
+        log.warn('cliloc refresh failed', { reason: result.reason })
+        break
+      default:
+        break
+    }
+    return result
+  } catch (err) {
+    log.warn('cliloc refresh errored', { error: err.message })
+    return { status: 'failed', reason: err.message }
+  }
+}
+
+/** Everything the admin panel needs to describe cliloc state. */
+async function status({ path: pathOverride = '' } = {}) {
+  const configured = pathOverride.trim() !== '' ? pathOverride.trim() : await getClientPath()
+  const meta = await db.getMeta().catch(() => null)
+  const loaded = await db.count().catch(() => 0)
+
+  let fileReadable = false
+  let file = null
+  let drift = null
+  let problem = null
+  let code = null
+  let sources = []
+  let missing = []
+  if (configured !== '') {
+    try {
+      const fingerprint = hashSources(configured)
+      fileReadable = true
+      file = fingerprint.file
+      sources = Object.keys(fingerprint.hashes)
+      missing = missingSources(fingerprint.hashes, meta?.hashes)
+      // A compressed file is readable but not importable, and the panel has to
+      // say so HERE — otherwise pointing at an unconverted client directory
+      // reports a healthy file with pending drift ("ready to import") and the
+      // operator only finds out when the import fails. `drift` stays null
+      // because comparing hashes with an unusable file answers nothing.
+      if (fingerprint.compressed) {
+        problem =
+          'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' +
+          'Convert it to the plain format first — see docs/website/CLILOCS.md.'
+        code = 'COMPRESSED'
+      } else {
+        drift = !sameSources(fingerprint.hashes, meta?.hashes) || !currentParser(meta)
+      }
+    } catch (err) {
+      fileReadable = false
+      problem = err.message
+      code = err.code ?? null
+    }
+  }
+
+  return {
+    configured: configured !== '',
+    path: configured,
+    file,
+    fileReadable,
+    problem,
+    code,
+    drift,
+    count: loaded,
+    // Every source found now (base first, then overlays), what each contributed
+    // at the last import, and any that have since vanished — which is the state
+    // an import will refuse without `approve`.
+    sources,
+    loadedSources: meta?.sources ?? null,
+    missingSources: missing,
+    importedAt: meta?.importedAt ?? null,
+    sourceBytes: meta?.bytes ?? null,
+  }
+}
+
+// ── Lookup ─────────────────────────────────────────────────────────────────
+//
+// Resolution happens SERVER-SIDE, not in the browser. Two reasons: the table is
+// ~123k rows and shipping it to a client would dwarf every page that uses it,
+// and the Android app consumes the same JSON and would otherwise need its own
+// copy. Callers get names, not ids-plus-a-table.
+
+// A small write-through cache in front of the table. Item ids repeat heavily —
+// one page of listings is mostly the same few hundred clilocs, and a character
+// sheet re-resolves the same gear on every view — so this turns the steady state
+// into zero queries. Capped so a pathological caller cannot grow it without
+// bound; on overflow it is dropped wholesale rather than evicted entry-by-entry,
+// which is cheap and correct for a table that only changes on reimport.
+const CACHE_MAX = 20000
+let cache = new Map()
+
+function invalidate() {
+  cache = new Map()
+}
+
+/**
+ * Resolve a batch of cliloc ids to display strings.
+ *
+ * Returns a `Map<number, string>` holding only the ids that resolved to
+ * something displayable — an id with no row, or one whose text is nothing but
+ * interpolated arguments we do not have, is simply absent. Callers fall back to
+ * whatever they had (the item id), so "missing" and "unnamed" collapse into one
+ * branch at the call site.
+ *
+ * Never throws: a cliloc lookup is decoration on someone's character sheet, and
+ * a database blip must not fail the sheet.
+ */
+async function resolveMany(numbers) {
+  const out = new Map()
+  if (!Array.isArray(numbers)) return out
+
+  const wanted = [...new Set(numbers.filter((n) => Number.isInteger(n) && n > 0))]
+  if (wanted.length === 0) return out
+
+  const missing = []
+  for (const number of wanted) {
+    if (cache.has(number)) {
+      const hit = cache.get(number)
+      if (hit !== '') out.set(number, hit)
+    } else {
+      missing.push(number)
+    }
+  }
+
+  if (missing.length > 0) {
+    try {
+      const rows = await db.lookup(missing)
+      const found = new Map(rows.map((r) => [Number(r.number), displayText(r.text)]))
+      if (cache.size + missing.length > CACHE_MAX) invalidate()
+      for (const number of missing) {
+        // Cache the miss too ('' meaning "no usable name"), so an id absent from
+        // the table does not re-query on every page view.
+        const text = found.get(number) ?? ''
+        cache.set(number, text)
+        if (text !== '') out.set(number, text)
+      }
+    } catch (err) {
+      log.warn('cliloc lookup failed', { message: err.message })
+    }
+  }
+
+  return out
+}
+
+/** Single-id convenience. Returns `null` when there is no usable name. */
+async function resolve(number) {
+  const found = await resolveMany([number])
+  return found.get(number) ?? null
+}
+
+module.exports = {
+  SETTING_KEY,
+  getClientPath,
+  setClientPath,
+  refresh,
+  refreshOnBoot,
+  status,
+  resolveMany,
+  resolve,
+  invalidate,
+}

server/src/model/shardMarket/shardMarket.db.js

@@ -0,0 +1,299 @@
+const { pool, query } = require('../../utils/db')
+
+// Raw SQL for the player-vendor market index (Protocol 3.0 vendor.listing).
+//
+// Two tables, both INGEST-OWNED: `shard_vendors` (one row per shop) and
+// `shard_vendor_items` (one row per priced listing). Nothing else in the codebase
+// writes to either. No foreign keys, consistent with every other shard_* table.
+
+// Insert batch size for one vendor's listings. A shop is capped at
+// MarketMaxListings (250 by default) on the shard side, so in practice this is
+// one batch — it exists for the operator who raised that cap.
+const BATCH = 500
+
+// LIKE wildcards in user input. `%` and `_` are not special to the parameterized
+// query — they are special to LIKE itself — so a search for "50% off" would
+// otherwise match everything containing "50" and a search for "_" would match
+// every single-character name. Escaped with a backslash, which is MariaDB's
+// default LIKE escape (no ESCAPE clause needed).
+const likeTerm = (q) => `%${String(q).replace(/[\\%_]/g, (c) => `\\${c}`)}%`
+
+/**
+ * Replace one vendor's whole row and listing set, in one transaction.
+ *
+ * Delete-then-insert rather than a diff, because the frame is AUTHORITATIVE for
+ * that vendor: the shard's sweep only emits a shop whose contents, prices or
+ * location moved, and when it does it sends the whole shop. Reconciling it item
+ * by item would be more code for the same result and would leave sold items
+ * behind on any path the reconciliation missed.
+ *
+ * All-or-nothing matters here for a specific reason: the two writes are "the
+ * shop" and "what is in it", and a failure between them leaves a shop advertising
+ * an inventory it no longer has (or none at all) — visibly wrong on the page, and
+ * indistinguishable from a genuinely empty shop.
+ */
+async function replaceVendor(vendor, items) {
+  const conn = await pool.getConnection()
+  try {
+    await conn.beginTransaction()
+
+    await conn.query(
+      `INSERT INTO shard_vendors
+         (serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house,
+          item_count, item_total, truncated, t)
+       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+       ON DUPLICATE KEY UPDATE shop_name = VALUES(shop_name), owner_serial = VALUES(owner_serial),
+         owner_name = VALUES(owner_name), map = VALUES(map), x = VALUES(x), y = VALUES(y),
+         z = VALUES(z), region = VALUES(region), house = VALUES(house),
+         item_count = VALUES(item_count), item_total = VALUES(item_total),
+         truncated = VALUES(truncated), t = VALUES(t),
+         -- Touched explicitly rather than left to ON UPDATE CURRENT_TIMESTAMP:
+         -- MariaDB does not fire that when every column is written back
+         -- unchanged, and a shop that is re-published identically is still
+         -- FRESHLY CONFIRMED. Without this the staleness banner would age a
+         -- perfectly current shop forever.
+         updated_at = CURRENT_TIMESTAMP`,
+      [
+        vendor.serial,
+        vendor.shopName ?? null,
+        vendor.ownerSerial ?? null,
+        vendor.ownerName ?? null,
+        vendor.map ?? null,
+        Number.isFinite(vendor.x) ? vendor.x : null,
+        Number.isFinite(vendor.y) ? vendor.y : null,
+        Number.isFinite(vendor.z) ? vendor.z : null,
+        vendor.region ?? null,
+        vendor.house ?? null,
+        items.length,
+        Number.isFinite(vendor.itemTotal) ? vendor.itemTotal : items.length,
+        vendor.truncated ? 1 : 0,
+        Number.isFinite(vendor.t) ? vendor.t : null,
+      ],
+    )
+
+    await conn.query('DELETE FROM shard_vendor_items WHERE vendor_serial = ?', [vendor.serial])
+
+    const rows = items.map((i) => [
+      vendor.serial,
+      i.serial,
+      i.itemId,
+      i.hue,
+      i.amount,
+      i.price,
+      i.name,
+      i.cliloc,
+      i.displayName,
+      i.child ? 1 : 0,
+    ])
+
+    for (let i = 0; i < rows.length; i += BATCH) {
+      await conn.batch(
+        `INSERT INTO shard_vendor_items
+           (vendor_serial, serial, item_id, hue, amount, price, name, cliloc, display_name, child)
+         VALUES (?,?,?,?,?,?,?,?,?,?)`,
+        rows.slice(i, i + BATCH),
+      )
+    }
+
+    await conn.commit()
+    return { items: rows.length }
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+/** Drop one vendor and its listings (vendor.listing.remove). */
+async function removeVendor(serial) {
+  const conn = await pool.getConnection()
+  try {
+    await conn.beginTransaction()
+    await conn.query('DELETE FROM shard_vendor_items WHERE vendor_serial = ?', [serial])
+    await conn.query('DELETE FROM shard_vendors WHERE serial = ?', [serial])
+    await conn.commit()
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+// ── Search ─────────────────────────────────────────────────────────────────
+//
+// The unit of a search RESULT is a listing, not a vendor: "who sells a vanquishing
+// kryss and for how much" is the question, and answering it per vendor would make
+// the caller flatten the shops back out. The vendor's columns ride along on the
+// join so a result row is self-contained.
+
+function searchWhere({ q, minPrice, maxPrice, itemId, map, region }) {
+  const where = ['i.price > 0']
+  const params = []
+
+  if (q) {
+    // Both the resolved display name and the item's own literal, because an item
+    // with a player-set name (most of what is actually worth searching for on a
+    // player-run shard) may have a generic cliloc.
+    where.push('(i.display_name LIKE ? OR i.name LIKE ?)')
+    params.push(likeTerm(q), likeTerm(q))
+  }
+  if (Number.isFinite(minPrice)) {
+    where.push('i.price >= ?')
+    params.push(minPrice)
+  }
+  if (Number.isFinite(maxPrice)) {
+    where.push('i.price <= ?')
+    params.push(maxPrice)
+  }
+  if (Number.isFinite(itemId)) {
+    where.push('i.item_id = ?')
+    params.push(itemId)
+  }
+  if (map) {
+    where.push('v.map = ?')
+    params.push(map)
+  }
+  if (region) {
+    where.push('v.region = ?')
+    params.push(region)
+  }
+
+  return { sql: `WHERE ${where.join(' AND ')}`, params }
+}
+
+// Whitelisted, because this interpolates into the statement. `recent` sorts by
+// the vendor's freshness, which is the only way to see what has just been listed
+// on a shard whose sweep is minutes wide.
+const SORTS = {
+  price_asc: 'i.price ASC, i.id ASC',
+  price_desc: 'i.price DESC, i.id ASC',
+  recent: 'v.updated_at DESC, i.id ASC',
+}
+
+async function searchListings({ q, minPrice, maxPrice, itemId, map, region, sort, limit, offset }) {
+  const { sql, params } = searchWhere({ q, minPrice, maxPrice, itemId, map, region })
+  const order = SORTS[sort] || SORTS.price_asc
+
+  const rows = await query(
+    `SELECT i.serial, i.item_id, i.hue, i.amount, i.price, i.name, i.cliloc, i.display_name, i.child,
+            v.serial AS vendor_serial, v.shop_name, v.owner_serial, v.owner_name,
+            v.map, v.x, v.y, v.z, v.region, v.house, v.updated_at
+       FROM shard_vendor_items i
+       JOIN shard_vendors v ON v.serial = i.vendor_serial
+       ${sql}
+      ORDER BY ${order}
+      LIMIT ? OFFSET ?`,
+    [...params, limit, offset],
+  )
+
+  const counted = await query(
+    `SELECT COUNT(*) AS n
+       FROM shard_vendor_items i
+       JOIN shard_vendors v ON v.serial = i.vendor_serial
+       ${sql}`,
+    params,
+  )
+
+  return { rows, total: Number(counted[0]?.n) || 0 }
+}
+
+async function getVendor(serial) {
+  const rows = await query(
+    `SELECT serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house,
+            item_count, item_total, truncated, t, updated_at
+       FROM shard_vendors WHERE serial = ?`,
+    [serial],
+  )
+  return rows[0] || null
+}
+
+async function listVendorItems(serial, { limit, offset }) {
+  return query(
+    `SELECT serial, item_id, hue, amount, price, name, cliloc, display_name, child
+       FROM shard_vendor_items
+      WHERE vendor_serial = ?
+      ORDER BY price ASC, id ASC
+      LIMIT ? OFFSET ?`,
+    [serial, limit, offset],
+  )
+}
+
+/**
+ * What the market page's header needs: how big the index is, and how stale it may
+ * be. `staleAt` is the OLDEST vendor row — the round-robin sweep means a shop can
+ * be a full cycle behind, and the page says so rather than implying live prices.
+ */
+async function meta() {
+  const rows = await query(
+    `SELECT COUNT(*) AS vendors, MIN(updated_at) AS stale_at, MAX(updated_at) AS fresh_at
+       FROM shard_vendors`,
+  )
+  const items = await query('SELECT COUNT(*) AS n FROM shard_vendor_items')
+  return {
+    vendors: Number(rows[0]?.vendors) || 0,
+    items: Number(items[0]?.n) || 0,
+    staleAt: rows[0]?.stale_at || null,
+    freshAt: rows[0]?.fresh_at || null,
+  }
+}
+
+/** The distinct facets and regions holding vendors — drives the page's filters. */
+async function listPlaces() {
+  const maps = await query(
+    'SELECT DISTINCT map FROM shard_vendors WHERE map IS NOT NULL ORDER BY map',
+  )
+  const regions = await query(
+    'SELECT DISTINCT region FROM shard_vendors WHERE region IS NOT NULL ORDER BY region',
+  )
+  return { maps: maps.map((r) => r.map), regions: regions.map((r) => r.region) }
+}
+
+// ── Cliloc re-resolution ───────────────────────────────────────────────────
+
+/**
+ * One page of listings whose name still needs resolving, for the bulk pass that
+ * runs after a cliloc import.
+ *
+ * Keyed on `id > after` rather than OFFSET: the pass updates the very rows it is
+ * scanning, and an OFFSET walk over a table being rewritten skips rows. Every
+ * row with a cliloc is re-read, not just the unresolved ones, because an import
+ * can also CHANGE a name — a shard overlay relabelling a stock item is the whole
+ * reason overlays exist.
+ */
+async function listResolvableItems(after, limit) {
+  return query(
+    `SELECT id, cliloc, name, display_name
+       FROM shard_vendor_items
+      WHERE cliloc IS NOT NULL AND cliloc > 0 AND id > ?
+      ORDER BY id
+      LIMIT ?`,
+    [after, limit],
+  )
+}
+
+/** Write back a batch of re-resolved display names. */
+async function updateDisplayNames(pairs) {
+  if (pairs.length === 0) return 0
+  const conn = await pool.getConnection()
+  try {
+    await conn.batch('UPDATE shard_vendor_items SET display_name = ? WHERE id = ?', pairs)
+    return pairs.length
+  } finally {
+    conn.release()
+  }
+}
+
+module.exports = {
+  replaceVendor,
+  removeVendor,
+  searchListings,
+  getVendor,
+  listVendorItems,
+  meta,
+  listPlaces,
+  listResolvableItems,
+  updateDisplayNames,
+  likeTerm,
+}

server/src/model/shardMarket/shardMarket.model.js

@@ -0,0 +1,329 @@
+// ── Player-vendor market index (Protocol 3.0 vendor.listing) ───────────────
+//
+// The shard-wide shop index: what every player vendor is selling, for how much,
+// and where it is standing. This is the website's half of the search the in-game
+// Vendor Search gump offers — the same data, the same opt-out, reachable without
+// logging in to the game.
+//
+// Ingest is per-vendor and authoritative: the shard's round-robin sweep emits one
+// `vendor.listing` frame per shop whose contents, prices or location moved, and
+// the frame is the whole shop (see docs/link/v3.md §8 and BridgeMarket.cs). This
+// module normalizes it into shard_vendors + shard_vendor_items and, crucially,
+// resolves each listing's cliloc to a DISPLAY NAME on the way in — a search for
+// "kryss" is a search over names, and the shard only ever sends numbers.
+
+const db = require('./shardMarket.db')
+const clilocs = require('../shardClilocs/shardClilocs.model')
+const log = require('../../utils/logger')('shard-market')
+
+// Defense in depth on top of the shard's own MarketMaxListings cap. The shard is
+// trusted, but it is a separately-versioned component: a frame from a plugin
+// whose cap was raised (or a shard running modified scripts) must not be able to
+// turn one ingest into an unbounded transaction.
+const MAX_ITEMS_PER_VENDOR = 5000
+
+// Column widths in schema.sql. Truncating here rather than letting MariaDB do it
+// keeps the behavior the same in strict mode, where an over-length value is an
+// ERROR and would fail the whole vendor rather than shortening one name.
+const MAX_NAME = 160
+const MAX_SHOP = 160
+const MAX_OWNER = 64
+const MAX_MAP = 40
+const MAX_REGION = 80
+const MAX_SERIAL = 20
+
+const clip = (value, max) => {
+  if (value == null) return null
+  const s = String(value)
+  return s.length > max ? s.slice(0, max) : s
+}
+
+const int = (value, fallback = 0) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? Math.trunc(n) : fallback
+}
+
+// ── Ingest ─────────────────────────────────────────────────────────────────
+
+/**
+ * Flatten one `vendor.listing` frame into the row shapes the DB layer wants.
+ *
+ * `location` arrives as a nested object rather than flat map/x/y/region, and that
+ * shape is load-bearing rather than cosmetic: the visibility projection matches
+ * literal JSON keys, so ONE `market.location` rule can hide a vendor's
+ * whereabouts only if `location` is a single key on both the live frame and the
+ * stored read model. Flattening it here for storage and re-nesting it on read is
+ * what keeps that true on both paths.
+ *
+ * Exported for tests — it is the part with rules in it, and it is pure.
+ */
+function flattenFrame(ev) {
+  const loc = (ev && ev.location) || {}
+  return {
+    serial: clip(ev.serial, MAX_SERIAL),
+    shopName: clip(ev.shopName, MAX_SHOP),
+    ownerSerial: clip(ev.ownerSerial, MAX_SERIAL),
+    ownerName: clip(ev.ownerName, MAX_OWNER),
+    map: clip(loc.map, MAX_MAP),
+    x: Number.isFinite(loc.x) ? Math.trunc(loc.x) : null,
+    y: Number.isFinite(loc.y) ? Math.trunc(loc.y) : null,
+    z: Number.isFinite(loc.z) ? Math.trunc(loc.z) : null,
+    region: clip(loc.region, MAX_REGION),
+    house: clip(loc.house, MAX_SHOP),
+    // What the SHOP holds, which is not what the frame carries when it was
+    // truncated. Kept apart so the page can say "showing 250 of 3,104" rather
+    // than presenting a partial shop as a complete one.
+    itemTotal: int(ev.total, int(ev.count, 0)),
+    truncated: ev.truncated === true,
+    t: Number.isFinite(ev.t) ? ev.t : null,
+  }
+}
+
+/**
+ * Resolve each listing's display name.
+ *
+ * Order of preference is the item's own literal `name` first, then the cliloc.
+ * That is the opposite of what "resolve the id" suggests and it is right: a
+ * literal name only exists because a player set one ("Bob's vanquishing kryss"),
+ * and it is strictly more specific than the generic cliloc the item still
+ * carries.
+ *
+ * One batched lookup per frame rather than per item; `resolveMany` is cached and
+ * never throws, so a cliloc table that is missing entirely just leaves
+ * `displayName` null and the page renders item ids, exactly as it did before the
+ * table existed.
+ */
+async function shapeItems(ev) {
+  const raw = Array.isArray(ev.items) ? ev.items.slice(0, MAX_ITEMS_PER_VENDOR) : []
+
+  const wanted = raw
+    .map((i) => int(i && i.cliloc, 0))
+    .filter((n) => n > 0)
+
+  const names = await clilocs.resolveMany(wanted)
+
+  return raw
+    .filter((i) => i && i.serial)
+    .map((i) => {
+      const literal = clip(i.name, MAX_NAME)
+      const cliloc = int(i.cliloc, 0) || null
+      return {
+        serial: clip(i.serial, MAX_SERIAL),
+        itemId: int(i.itemId, 0),
+        hue: int(i.hue, 0),
+        amount: int(i.amount, 1),
+        price: int(i.price, 0),
+        name: literal,
+        cliloc,
+        displayName: literal || (cliloc ? clip(names.get(cliloc) ?? null, MAX_NAME) : null),
+        child: i.child === true,
+      }
+    })
+    // Unpriced rows are inventory, not listings. The shard already drops them;
+    // this is the same rule enforced where the table is written, so a plugin that
+    // stops enforcing it cannot put un-buyable rows on the market page.
+    .filter((i) => i.price > 0)
+}
+
+/** Ingest one `vendor.listing` frame. */
+async function upsertVendor(ev) {
+  if (!ev || !ev.serial) return
+  const vendor = flattenFrame(ev)
+  const items = await shapeItems(ev)
+  await db.replaceVendor(vendor, items)
+}
+
+/** Ingest one `vendor.listing.remove` frame. */
+async function removeVendor(serial) {
+  if (!serial) return
+  await db.removeVendor(String(serial).slice(0, MAX_SERIAL))
+}
+
+// ── Read models ────────────────────────────────────────────────────────────
+//
+// `location` is re-nested (see flattenFrame) so the stored read model and the
+// live wire frame present the same keys to the visibility projection.
+
+const place = (r) => ({
+  map: r.map,
+  x: r.x,
+  y: r.y,
+  z: r.z,
+  region: r.region,
+  house: r.house,
+})
+
+// A listing as the search returns it: the item, plus enough of its shop to be
+// actionable without a second request. `displayName` falls back to nothing rather
+// than to a fabricated "Item 3922" — the client decides how to render an
+// unresolved id, and inventing a name here would make it indistinguishable from
+// a real one.
+const shapeListing = (r) => ({
+  serial: r.serial,
+  itemId: r.item_id,
+  hue: r.hue,
+  amount: r.amount,
+  price: Number(r.price),
+  name: r.name,
+  cliloc: r.cliloc,
+  displayName: r.display_name,
+  child: !!r.child,
+  vendor: {
+    serial: r.vendor_serial,
+    shopName: r.shop_name,
+    ownerSerial: r.owner_serial,
+    ownerName: r.owner_name,
+    location: place(r),
+    updatedAt: r.updated_at,
+  },
+})
+
+const shapeVendor = (r) => ({
+  serial: r.serial,
+  shopName: r.shop_name,
+  ownerSerial: r.owner_serial,
+  ownerName: r.owner_name,
+  location: place(r),
+  count: r.item_count,
+  total: r.item_total,
+  truncated: !!r.truncated,
+  updatedAt: r.updated_at,
+})
+
+const shapeItem = (r) => ({
+  serial: r.serial,
+  itemId: r.item_id,
+  hue: r.hue,
+  amount: r.amount,
+  price: Number(r.price),
+  name: r.name,
+  cliloc: r.cliloc,
+  displayName: r.display_name,
+  child: !!r.child,
+})
+
+/**
+ * Search the index. Returns a page of LISTINGS (not vendors) plus the
+ * unpaginated total and the staleness stamp the page's banner needs.
+ */
+async function search({
+  q = '',
+  minPrice,
+  maxPrice,
+  itemId,
+  map = '',
+  region = '',
+  sort = 'price_asc',
+  limit = 50,
+  offset = 0,
+} = {}) {
+  const { rows, total } = await db.searchListings({
+    q: q.trim(),
+    minPrice: Number.isFinite(minPrice) ? minPrice : undefined,
+    maxPrice: Number.isFinite(maxPrice) ? maxPrice : undefined,
+    itemId: Number.isFinite(itemId) ? itemId : undefined,
+    map: map.trim(),
+    region: region.trim(),
+    sort,
+    limit,
+    offset,
+  })
+
+  const info = await db.meta()
+
+  return {
+    listings: rows.map(shapeListing),
+    total,
+    limit,
+    offset,
+    // Repeated on every search response rather than left to a separate /meta
+    // call: the banner that says how old these prices are must age with the
+    // results it labels, and a client that fetched it once would keep showing a
+    // stamp from before the page it is looking at.
+    staleAt: info.staleAt,
+    vendors: info.vendors,
+  }
+}
+
+/** One shop and its listings. `null` when the index has never seen that serial. */
+async function getVendor(serial, { limit = 250, offset = 0 } = {}) {
+  const row = await db.getVendor(serial)
+  if (!row) return null
+  const items = await db.listVendorItems(serial, { limit, offset })
+  return { ...shapeVendor(row), items: items.map(shapeItem) }
+}
+
+/** Index size, staleness, and the facet/region filter options. */
+async function meta() {
+  const [info, places] = await Promise.all([db.meta(), db.listPlaces()])
+  return { ...info, ...places }
+}
+
+// ── Cliloc re-resolution ───────────────────────────────────────────────────
+
+// Batch size for the post-import pass. Big enough that a 40k-row table is ~40
+// round trips, small enough that a single batch is not a long-held connection.
+const RESOLVE_BATCH = 1000
+
+/**
+ * Re-resolve every listing's display name against the current cliloc table.
+ *
+ * Called after a cliloc import, and it has to be: the market's diff sweep will
+ * NOT re-send an unchanged shop just because the site learned what its items are
+ * called, so without this an operator who configures clilocs after the first
+ * market sweep sees item ids until every shop happens to change. That is the same
+ * class of staleness the spawn atlas avoids by re-parsing on boot — here the
+ * source of truth for names moved, not the data.
+ *
+ * Never throws. It is a cosmetic backfill on a table that is already serving; a
+ * failure means names stay as they were, which is exactly the pre-import state.
+ */
+async function refreshDisplayNames() {
+  let after = 0
+  let scanned = 0
+  let changed = 0
+
+  try {
+    for (;;) {
+      const rows = await db.listResolvableItems(after, RESOLVE_BATCH)
+      if (rows.length === 0) break
+
+      after = rows[rows.length - 1].id
+      scanned += rows.length
+
+      const names = await clilocs.resolveMany(rows.map((r) => Number(r.cliloc)))
+
+      const pairs = []
+      for (const row of rows) {
+        // The literal name still wins, so a re-resolution never overwrites a
+        // player-set name with the generic cliloc behind it.
+        const next = row.name
+          ? clip(row.name, MAX_NAME)
+          : clip(names.get(Number(row.cliloc)) ?? null, MAX_NAME)
+        if (next !== row.display_name) pairs.push([next, row.id])
+      }
+
+      changed += await db.updateDisplayNames(pairs)
+    }
+
+    if (changed > 0) log.info('market display names refreshed', { scanned, changed })
+    return { scanned, changed }
+  } catch (err) {
+    log.warn('market display-name refresh failed', { message: err.message, scanned, changed })
+    return { scanned, changed, error: err.message }
+  }
+}
+
+module.exports = {
+  upsertVendor,
+  removeVendor,
+  search,
+  getVendor,
+  meta,
+  refreshDisplayNames,
+  flattenFrame,
+  shapeItems,
+  shapeListing,
+  shapeVendor,
+  MAX_ITEMS_PER_VENDOR,
+}

server/src/model/uoLinkConfig/uoLinkConfig.model.js

@@ -7,7 +7,10 @@
 const db = require('./uoLinkConfig.db')
 const secretBox = require('../../utils/secretBox')
 
-const DEFAULT_PROTOCOL = Number(process.env.UOLINK_PROTOCOL) || 1
+// The wire protocol this build speaks (link/sidecar/src/main.rs PROTOCOL_VERSION).
+// Only used before an admin has saved anything — the stored row wins once it exists,
+// and UOLINK_PROTOCOL still overrides for an operator running an older sidecar.
+const DEFAULT_PROTOCOL = Number(process.env.UOLINK_PROTOCOL) || 3
 
 function toSafe(row) {
   if (!row) {

server/src/router/v1/admin/shard.router.js

@@ -25,6 +25,7 @@ const { body, param } = require('express-validator')
 const shardOps = require('./shardOps.controller')
 const shardVisibility = require('./shardVisibility.controller')
 const shardAtlas = require('./shardAtlas.controller')
+const shardClilocs = require('./shardClilocs.controller')
 const selfShard = require('../player/shard.controller')
 const { requireRole } = require('../../../utils/auth')
 const validate = require('../../../middleware/validate')
@@ -304,6 +305,55 @@ shardRouter.put(
   shardAtlas.setPath,
 )
 
+// ── Cliloc table (admin only) ─────────────────────────────────────────────
+// UO's id → display-string map, converted once by the operator from their own
+// client (docs/website/CLILOCS.md). Sits beside the atlas for the same reason:
+// it is static content derived from operator-supplied files rather than anything
+// the sidecar sends, and operating it is shard administration.
+//
+// There is deliberately NO public counterpart. The table is never served as a
+// table — 123k rows would dwarf any page that used it, and the Android client
+// consumes the same already-resolved JSON. Names are applied server-side to the
+// responses that need them.
+shardRouter.get(
+  '/clilocs',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Cliloc table status: sources, drift, entry count (admin only)'
+  // #swagger.description = 'Where the cliloc sources are, whether they can be read, how many entries are loaded, and whether the files on disk have drifted from them. The table is built from a SET of sources — the converted client table plus every operator-maintained overlay under `custom/`, which is how shard-added and shard-edited items get names. `missingSources` lists any source that was loaded before and is now gone; an import refuses that without `approve`. A shard with nothing configured is a supported state — item names simply render as ids.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Cliloc status', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocStatus" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  shardClilocs.getStatus,
+)
+shardRouter.post(
+  '/clilocs/import',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Re-import the cliloc table from its source files (admin only)'
+  // #swagger.description = 'Applies a client patch, or a change to the shard\'s own overlay files, without a restart. `force` reimports even when the source hashes match what is loaded. `approve` accepts a refresh in which a previously-loaded source has VANISHED — refused by default, because an unmounted volume and a deliberate deletion are indistinguishable from the server, and the wrong guess silently drops every name that file contributed. A missing path — or the common mistake of pointing at the client\'s own COMPRESSED Cliloc.enu — answers 200 with status "unavailable" and the reason, rather than 500: the refresh contract reports outcomes instead of throwing, and the admin needs to be told which file to convert.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: false, content: { "application/json": { schema: { type: "object", properties: { force: { type: "boolean", description: "Reimport even if the sources are unchanged." }, approve: { type: "boolean", description: "Accept a refresh in which a previously-loaded source has vanished." } } } } } } */
+  /* #swagger.responses[200] = { description: 'What happened', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocRefreshResult" } } } } */
+  adminOnly,
+  body('force').optional().isBoolean(),
+  body('approve').optional().isBoolean(),
+  validate,
+  shardClilocs.importClilocs,
+)
+shardRouter.put(
+  '/clilocs/path',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Set the cliloc source the site reads from (admin only)'
+  // #swagger.description = 'Accepts either the converted base file itself or a directory to search. Overlays are read from a `custom/` directory beside it either way — pointing at a file does not forfeit them. Persisted as a setting, which wins over the UO_CLIENT_PATH deploy default so the mount can move without a redeploy. Blank clears it and resolution is skipped on the next boot. Deliberately does not import as a side effect — the response carries the refreshed status so the panel can offer that as the next step.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["path"], properties: { path: { type: "string", description: "Path to the converted cliloc file, or a directory containing one. Blank disables resolution." } } } } } } */
+  /* #swagger.responses[200] = { description: 'Cliloc status after the change', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocStatus" } } } } */
+  adminOnly,
+  body('path').isString().isLength({ max: 512 }),
+  validate,
+  shardClilocs.setPath,
+)
+
 // ── Feature visibility (admin only) ───────────────────────────────────
 // Who can see which shard surface, and which sensitive fields within it. This
 // decides what ANONYMOUS visitors get, so it sits above the moderator tier.

server/src/router/v1/admin/shardClilocs.controller.js

@@ -0,0 +1,106 @@
+// ── Admin · Cliloc table ───────────────────────────────────────────────────
+//
+// Operating the cliloc import: where the converted cliloc file is, whether it
+// has drifted from what is loaded, and a forced reimport after a client patch
+// (docs/website/CLILOCS.md).
+//
+// The policy lives in the model. This controller does three things and no more:
+// it validates input, it maps a refresh RESULT onto an HTTP status, and it
+// records the action in the admin activity log.
+//
+// **A refresh result is not an exception.** `shardClilocs.refresh()` reports
+// `unavailable` / `failed` rather than throwing, because the boot path must never
+// be stopped by a bad file. That contract is preserved here: a missing file, or
+// the single most likely operator mistake — pointing at the client's own
+// COMPRESSED `Cliloc.enu` — is a 200 carrying `status: 'unavailable'` and the
+// reason, not a 500. A 500 would say only "something broke"; the operator needs
+// to be told which file to convert.
+
+const clilocs = require('../../../model/shardClilocs/shardClilocs.model')
+const market = require('../../../model/shardMarket/shardMarket.model')
+const activity = require('../../../model/activity/activity.model')
+
+const log = require('../../../utils/logger')('admin-shard-clilocs')
+
+// GET /admin/shard/clilocs — what is loaded, what the file looks like, whether
+// they disagree. There is no public counterpart: the cliloc table is never
+// served as a table, only applied to names the site already returns.
+async function getStatus(req, res) {
+  try {
+    return res.json(await clilocs.status())
+  } catch (err) {
+    log.error('getStatus', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/clilocs/import — reload after a client patch or a change to
+// the shard's own overlay files, without a restart.
+//
+// `force` reimports even when the source hashes match what is loaded (the escape
+// hatch for "the database is wrong but the files are not").
+//
+// `approve` accepts a refresh in which a previously-loaded source has VANISHED.
+// That is refused by default because an unmounted volume and a deliberate
+// deletion look identical from the server — the lighter cousin of the atlas's
+// approve/reject flow, and the reason it can be a flag here rather than a
+// pending table is that nothing is stored to approve: the import re-reads the
+// files at approval time by construction.
+async function importClilocs(req, res) {
+  try {
+    const force = !!req.body?.force
+    const approve = !!req.body?.approve
+    const result = await clilocs.refresh({ force, approve })
+
+    // The marketplace denormalizes resolved item names into
+    // shard_vendor_items.display_name, and the shard's market sweep will NOT
+    // re-send an unchanged shop just because the site learned what its items are
+    // called — so without this pass, an operator who imports clilocs after the
+    // first sweep keeps seeing item ids until every shop happens to change.
+    // Awaited (rather than fired and forgotten) so the panel's "imported" is
+    // honest about the names being live; the pass is a bounded walk of one table
+    // and never throws.
+    if (result.status === 'imported') await market.refreshDisplayNames()
+
+    await activity.log({
+      req,
+      action: 'shard.clilocs.import',
+      detail: {
+        force,
+        approve,
+        status: result.status,
+        count: result.count ?? null,
+        missingSources: result.missingSources ?? result.acceptedMissing ?? null,
+      },
+    })
+    return res.json(result)
+  } catch (err) {
+    log.error('importClilocs', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// PUT /admin/shard/clilocs/path — point the site at a different cliloc file.
+//
+// Persisted as a setting, which wins over the UO_CLIENT_PATH env default so an
+// operator can move the mount without a redeploy. Blank clears it, which turns
+// resolution off (boot skips, the loaded table keeps serving) — a legitimate
+// thing to want, so it is allowed rather than validated away.
+//
+// Deliberately does NOT import as a side effect, for the same reason the atlas
+// path does not: changing where the table reads from and reloading it are
+// separate decisions. The response carries the refreshed status so the panel can
+// offer the import immediately.
+async function setPath(req, res) {
+  try {
+    const value = String(req.body?.path ?? '').trim()
+    await clilocs.setClientPath(value, req.user?.id ?? null)
+    await activity.log({ req, action: 'shard.clilocs.path', detail: { path: value } })
+    return res.json(await clilocs.status())
+  } catch (err) {
+    log.error('setClilocPath', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = { getStatus, importClilocs, setPath }

server/src/router/v1/player/shard.controller.js

@@ -10,6 +10,7 @@
 const uoLinkClient = require('../../../utils/uoLinkClient')
 const shardLinks = require('../../../model/shardLinks/shardLinks.model')
 const shardState = require('../../../model/shardState/shardState.model')
+const shardClilocs = require('../../../model/shardClilocs/shardClilocs.model')
 const settings = require('../../../model/settings/settings.model')
 const { salesForAccounts } = require('../../../utils/shardSales')
 const activity = require('../../../model/activity/activity.model')
@@ -18,9 +19,62 @@ const log = require('../../../utils/logger')('player-shard')
 
 const SERIAL_RE = /^0x[0-9a-fA-F]+$/
 
+/**
+ * Resolve the cliloc ids on a profile into display names.
+ *
+ * Items on the wire carry a `LabelNumber`, not a name — `BridgeProfile.WriteItem`
+ * sends `cliloc` on every equipment entry and `name` only for the minority of
+ * items a player has renamed. Reward titles are the same shape: the shard sends
+ * a cliloc number as a string, which the sheet previously had to SKIP because it
+ * had no way to turn it into words.
+ *
+ * Resolution happens here rather than in the browser because the table is ~123k
+ * rows: shipping it to render a dozen names would dwarf the page, and the
+ * Android client consumes this same JSON and would otherwise need its own copy.
+ *
+ * A shard with no cliloc table configured resolves nothing and the sheet renders
+ * ids exactly as it did before — this is decoration, and it is applied in the
+ * same best-effort block as the guild/governor cross-links.
+ */
+async function resolveProfileClilocs(profile) {
+  const wanted = []
+
+  const equipment = Array.isArray(profile.equipment) ? profile.equipment : []
+  for (const item of equipment) {
+    if (Number.isInteger(item?.cliloc)) wanted.push(item.cliloc)
+  }
+
+  // Reward titles arrive as strings that may be either a literal ("Knight of
+  // Trinsic") or a cliloc number in string form. Only the numeric ones need us.
+  const reward = Array.isArray(profile.titles?.reward) ? profile.titles.reward : []
+  const rewardNumbers = reward.map((r) => (/^\d+$/.test(String(r)) ? Number(r) : null))
+  for (const n of rewardNumbers) if (n !== null) wanted.push(n)
+
+  if (wanted.length === 0) return
+
+  const names = await shardClilocs.resolveMany(wanted)
+  if (names.size === 0) return
+
+  for (const item of equipment) {
+    // A player-given name always wins over the type name: an item called "Bob's
+    // lucky axe" should not be relabelled "hatchet".
+    if (item?.name) continue
+    const resolved = names.get(item?.cliloc)
+    if (resolved) item.clilocName = resolved
+  }
+
+  if (rewardNumbers.some((n) => n !== null)) {
+    profile.titles.rewardResolved = reward.map((raw, i) => {
+      const n = rewardNumbers[i]
+      return n === null ? String(raw) : names.get(n) ?? null
+    })
+  }
+}
+
 // Decorate a char.profile with cross-links from our own board data: the guild the
-// character leads and any city governorship on its account. Best-effort — a
-// failure here never fails the profile (it's a nicety, not the sheet).
+// character leads and any city governorship on its account, plus resolved cliloc
+// names. Best-effort — a failure here never fails the profile (it's a nicety,
+// not the sheet).
 async function enrichCharProfile(profile) {
   if (!profile) return profile
   try {
@@ -30,6 +84,7 @@ async function enrichCharProfile(profile) {
       const govs = await shardState.listGovernorshipsForAccounts([profile.acct])
       if (govs.length) profile.governorOf = govs.map((g) => g.city)
     }
+    await resolveProfileClilocs(profile)
   } catch (err) {
     log.warn('enrichCharProfile failed', { serial: profile.serial, message: err.message })
   }

server/src/router/v1/public/shard.controller.js

@@ -11,6 +11,7 @@
 
 const shardEvents = require('../../../model/shardEvents/shardEvents.model')
 const shardState = require('../../../model/shardState/shardState.model')
+const shardMarket = require('../../../model/shardMarket/shardMarket.model')
 const uoLinkConfig = require('../../../model/uoLinkConfig/uoLinkConfig.model')
 const broadcast = require('../../../utils/shardBroadcast')
 const visibility = require('../../../utils/shardVisibility')
@@ -299,6 +300,84 @@ async function getPointsBoard(req, res) {
   }
 }
 
+// ── Marketplace (Protocol 3.0 vendor.listing) ──────────────────────────────
+//
+// The shard-wide player-vendor index. Served entirely from our own tables — the
+// sidecar is never touched on this path — so shops stay browsable while the shard
+// is down, labelled with how stale they may be.
+//
+// The staleness label is not decoration. The shard sweeps vendors round-robin, so
+// a shop can legitimately be a full cycle behind; a page that implied live prices
+// would send people to a vendor whose item sold twenty minutes ago.
+
+// The serial spelling the bridge uses everywhere: "0x" and hex. Constrained
+// before it reaches the model, like SYSTEM_RE above.
+const SERIAL_RE = /^0x[0-9A-Fa-f]{1,16}$/
+
+const intParam = (value) => {
+  const n = Number.parseInt(value, 10)
+  return Number.isFinite(n) ? n : undefined
+}
+
+// GET /public/shard/market — search the index.
+//
+// Returns LISTINGS, not vendors: "who sells a vanquishing kryss and for how much"
+// is the question, and a vendor-shaped result would make every caller flatten the
+// shops back out.
+async function getMarket(req, res) {
+  try {
+    const page = await shardMarket.search({
+      q: typeof req.query.q === 'string' ? req.query.q : '',
+      minPrice: intParam(req.query.minPrice),
+      maxPrice: intParam(req.query.maxPrice),
+      itemId: intParam(req.query.itemId),
+      map: typeof req.query.map === 'string' ? req.query.map : '',
+      region: typeof req.query.region === 'string' ? req.query.region : '',
+      sort: typeof req.query.sort === 'string' ? req.query.sort : 'price_asc',
+      limit: intParam(req.query.limit) ?? 50,
+      offset: intParam(req.query.offset) ?? 0,
+    })
+    return res.json(await visibility.project('market', page, req))
+  } catch (err) {
+    log.error('shard.getMarket', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/market/meta — index size, staleness, and the filter options
+// (which facets and regions actually hold vendors). Separate from the search so
+// the page can build its filters without running a query it will throw away.
+async function getMarketMeta(req, res) {
+  try {
+    return res.json(await visibility.project('market', await shardMarket.meta(), req))
+  } catch (err) {
+    log.error('shard.getMarketMeta', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/market/vendors/:serial — one shop and its listings.
+//
+// 404 for a serial the index has never seen, which also covers a vendor that has
+// since been dismissed or hidden: to an anonymous caller "no such shop" is the
+// only honest answer, and distinguishing the two would leak that a vendor exists
+// but was hidden.
+async function getMarketVendor(req, res) {
+  const { serial } = req.params
+  if (!SERIAL_RE.test(serial)) return res.status(400).json({ message: 'Invalid vendor serial.' })
+  try {
+    const vendor = await shardMarket.getVendor(serial, {
+      limit: intParam(req.query.limit) ?? 250,
+      offset: intParam(req.query.offset) ?? 0,
+    })
+    if (!vendor) return res.status(404).json({ message: 'Unknown vendor.' })
+    return res.json(await visibility.project('market', vendor, req))
+  } catch (err) {
+    log.error('shard.getMarketVendor', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
 // GET /public/shard/features — the shard features THIS caller can actually see,
 // so the SPA (and the Android client) can hide nav entries instead of rendering
 // links that 403. Deliberately reports only what the viewer may reach: the list
@@ -335,6 +414,9 @@ module.exports = {
   getRuleset,
   getPointsBoards,
   getPointsBoard,
+  getMarket,
+  getMarketMeta,
+  getMarketVendor,
   getFeatures,
   stream,
 }

server/src/router/v1/public/shard.router.js

@@ -25,6 +25,7 @@ const { param, query } = require('express-validator')
 
 const shard = require('./shard.controller')
 const validate = require('../../../middleware/validate')
+const { marketLimiter } = require('../../../middleware/rateLimit')
 const { requireFeature } = require('../../../utils/shardVisibility')
 
 const shardRouter = express.Router()
@@ -167,6 +168,71 @@ shardRouter.get(
   /* #swagger.responses[404] = { description: 'The shard has never published that system' } */
   shard.getPointsBoard,
 )
+// ── Marketplace ────────────────────────────────────────────────────────────
+//
+// Rate-limited, unlike every other route in this file. These are the first
+// genuinely expensive PUBLIC reads on the site — a LIKE scan plus a COUNT over
+// what is typically the largest shard_* table, reachable with no session.
+shardRouter.get(
+  '/market',
+  requireFeature('market'),
+  marketLimiter,
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Search the player-vendor marketplace'
+  // #swagger.description = 'Every priced listing on every player vendor the shard publishes — the same index the in-game Vendor Search gump reads, and it honours the same per-vendor opt-out, so a player who hid their shop in game is hidden here too. Results are LISTINGS, each carrying enough of its shop to be actionable. Served from the site\'s own tables (the sidecar is not touched), so it renders while the shard is down; `staleAt` is the oldest vendor row and the page must say how far behind the index can be — the shard sweeps vendors round-robin, so prices are inherently up to one full cycle old. Item names are resolved server-side against the cliloc table (docs/website/CLILOCS.md); on a shard that has not configured one, `displayName` is null and clients render the item id.'
+  // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the resolved item name or the item\'s own literal name (max 60 chars).' }
+  // #swagger.parameters['minPrice'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Lowest price to include.' }
+  // #swagger.parameters['maxPrice'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Highest price to include.' }
+  // #swagger.parameters['itemId'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Exact ItemID (art id) match, for "more like this".' }
+  // #swagger.parameters['map'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet. Facet names come from the shard\'s own data; an unknown one returns an empty page.' }
+  // #swagger.parameters['region'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one named region.' }
+  // #swagger.parameters['sort'] = { in: 'query', required: false, schema: { type: 'string', enum: ['price_asc','price_desc','recent'] }, description: 'Default price_asc. `recent` orders by when the shop was last seen.' }
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Page size, 1..100 (default 50).' }
+  // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Rows to skip (default 0).' }
+  /* #swagger.responses[200] = { description: 'A page of listings plus the unpaginated total and the staleness stamp', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketPage" } } } } */
+  /* #swagger.responses[403] = { description: 'The market feature is gated above this caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'The market feature is disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Rate limited', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }),
+  query('minPrice').optional({ values: 'falsy' }).isInt({ min: 0, max: 999999999 }),
+  query('maxPrice').optional({ values: 'falsy' }).isInt({ min: 0, max: 999999999 }),
+  query('itemId').optional({ values: 'falsy' }).isInt({ min: 0, max: 65535 }),
+  query('map').optional({ values: 'falsy' }).isString().isLength({ max: 40 }),
+  query('region').optional({ values: 'falsy' }).isString().isLength({ max: 80 }),
+  query('sort').optional({ values: 'falsy' }).isIn(['price_asc', 'price_desc', 'recent']),
+  query('limit').optional().isInt({ min: 1, max: 100 }),
+  query('offset').optional().isInt({ min: 0, max: 100000 }),
+  validate,
+  shard.getMarket,
+)
+shardRouter.get(
+  '/market/meta',
+  requireFeature('market'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Marketplace size, staleness and filter options'
+  // #swagger.description = 'How many vendors and listings the index holds, how stale it may be (`staleAt` = the oldest vendor row, `freshAt` = the newest), and which facets and regions actually hold vendors — so a client can build its filters without running a search it will discard.'
+  /* #swagger.responses[200] = { description: 'Marketplace metadata', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketMeta" } } } } */
+  shard.getMarketMeta,
+)
+shardRouter.get(
+  '/market/vendors/:serial',
+  requireFeature('market'),
+  marketLimiter,
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'One player vendor and everything it is selling'
+  // #swagger.description = 'A single shop by its vendor serial, with its listings. `truncated` (and `total` exceeding `count`) means the shop holds more than the shard publishes per frame — a commodity reseller with thousands of stacks is a real thing, and the page says so rather than presenting a partial shop as complete. Returns 404 for a serial the index has never seen, which also covers a vendor since dismissed or hidden.'
+  /* #swagger.parameters['serial'] = { in: 'path', required: true, description: 'Vendor serial, e.g. 0x40001234', schema: { type: 'string' } } */
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Listings to return, 1..500 (default 250).' }
+  // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Listings to skip (default 0).' }
+  /* #swagger.responses[200] = { description: 'The vendor', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketVendor" } } } } */
+  /* #swagger.responses[400] = { description: 'Malformed vendor serial' } */
+  /* #swagger.responses[404] = { description: 'No such vendor in the index' } */
+  param('serial').isString().isLength({ max: 20 }),
+  query('limit').optional().isInt({ min: 1, max: 500 }),
+  query('offset').optional().isInt({ min: 0, max: 100000 }),
+  validate,
+  shard.getMarketVendor,
+)
 shardRouter.get(
   '/features',
   // #swagger.tags = ['Public · Shard']

server/src/server.js

@@ -15,6 +15,8 @@ const settings = require('./model/settings/settings.model')
 const revokedSessions = require('./model/revokedSessions/revokedSessions.model')
 const mobileAuthBridge = require('./model/mobileAuthBridge/mobileAuthBridge.model')
 const shardAtlas = require('./model/shardAtlas/shardAtlas.model')
+const shardClilocs = require('./model/shardClilocs/shardClilocs.model')
+const shardMarket = require('./model/shardMarket/shardMarket.model')
 const createLogger = require('./utils/logger')
 const { evaluateBotInternalKey } = require('./utils/botInternalKey')
 const brand = require('./config/brand')
@@ -89,6 +91,21 @@ async function start() {
   // REMOVE a facet is staged for admin approval instead of being applied.
   await shardAtlas.refreshOnBoot()
 
+  // Refresh the cliloc table (UO's id → display-string map) from the file the
+  // operator converted out of their own client. Same contract as the atlas:
+  // hash-gated so an unchanged file costs one read, and best-effort so a missing
+  // or wrong-format file never stops the site coming up — it just means item
+  // names render as ids, which is what they did before the table existed.
+  const clilocResult = await shardClilocs.refreshOnBoot()
+
+  // A cliloc import changes what item names RESOLVE to, and the marketplace
+  // stores those names denormalized (shard_vendor_items.display_name) so it can
+  // index and search them. The shard's market sweep will not re-send an unchanged
+  // shop just because the site learned what its items are called, so the backfill
+  // has to be pulled rather than waited for. Only after an actual import — the
+  // common boot is hash-gated to a no-op and must stay one.
+  if (clilocResult && clilocResult.status === 'imported') await shardMarket.refreshDisplayNames()
+
   const mode = await settings.get('site_mode')
   log.info(`site mode: ${String(mode || 'live').toUpperCase()}`)
 

server/src/utils/clilocParse.js

@@ -0,0 +1,287 @@
+// Cliloc parsing — the pure half.
+//
+// A "cliloc" is UO's localization table: an integer id mapped to a display
+// string. Items carry a `LabelNumber` rather than a name, so without this table
+// the site can only render `id 1023721` where the game shows "quarter staff".
+// The shard already sends the id on every equipment entry (`char.profile`'s
+// `cliloc` field) and will send one per marketplace listing — the *number* was
+// never the missing piece, the *table* was.
+//
+// This module is fs-free on purpose, exactly like `spawnAtlasParse.js`: the
+// suite runs in CI where there is no UO client, so every parser here is driven
+// from inline fixtures. `clilocSource.js` is the only thing that touches disk.
+//
+// ── Two input formats, and why ─────────────────────────────────────────────
+//
+// The client's own `Cliloc.enu` is COMPRESSED (Mythic format) on any modern
+// client, and decompressing it is a bit-level port of an inverse-BWT coder that
+// nothing in this stack needs at runtime. ServUO's own bundled `Ultima.StringList`
+// cannot read it either — which is why `VendorSearch.GetItemName` is already inert
+// on such a shard and the plugin could not supply names even if we asked it to.
+//
+// So the operator converts once, from their own client, and points the site at
+// the result (see docs/website/CLILOCS.md). Two shapes are accepted because
+// different tools produce different things:
+//
+//   • PLAIN BINARY — the pre-compression cliloc layout: a 6-byte header, then
+//     records of {int32 number, byte flag, uint16 length, UTF-8 bytes}.
+//   • DELIMITED TEXT — `number<TAB|,|;>text` per line, which is what the common
+//     GUI exports emit. Quoted CSV fields and a header row are tolerated.
+//
+// Nothing derived from the client is ever committed: the converted file lives at
+// an operator-supplied path and is gitignored, the same rule the spawn atlas art
+// map already follows.
+
+/** Raised for a file we can identify but deliberately refuse to guess at. */
+class ClilocFormatError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.name = 'ClilocFormatError'
+    this.code = code
+  }
+}
+
+/**
+ * Bumped when this parser produces DIFFERENT data from an IDENTICAL source file.
+ *
+ * Stored beside the source hash so the boot path can tell "same file, but the
+ * parser moved on" from "same file, nothing to do". Without it a corrected parse
+ * would ship and never reach an install whose cliloc file never changes — the
+ * trap `spawnAtlasSource.PARSER_VERSION` documents.
+ */
+const PARSER_VERSION = 1
+
+// The plain layout's header is `02 00 00 00 01 00` — a 4-byte version and a
+// 2-byte language marker. Only the size matters for parsing; the values are
+// checked to sniff the format, not to validate it.
+const HEADER_BYTES = 6
+const RECORD_HEADER_BYTES = 7 // int32 number + byte flag + uint16 length
+
+// Every compressed cliloc file the client ships begins with a DWORD whose high
+// byte is 0x8E (the XOR key UOFiddler calls `HeaderXorKey`, 0x8E2C9A3D). That is
+// the single cheapest way to tell an operator they exported the wrong file —
+// without it, the plain parser happily reads compressed bytes as ~19k records of
+// negative ids and 60 KB "strings" before dying somewhere in the middle, and the
+// resulting error names the wrong problem.
+const MYTHIC_HIGH_BYTE = 0x8e
+
+/** True when `buffer` is a Mythic-compressed cliloc rather than the plain layout. */
+function isCompressedCliloc(buffer) {
+  return buffer.length >= 4 && buffer[3] === MYTHIC_HIGH_BYTE
+}
+
+/**
+ * Parse the plain binary cliloc layout.
+ *
+ * Strict about truncation, and that strictness is load-bearing: a half-copied or
+ * partly-written file is the realistic failure here, and it must fail loudly
+ * rather than import a silently short table that then renders half the world as
+ * `id 1023721`. A record that runs past the end of the buffer throws.
+ */
+function parseClilocBinary(buffer) {
+  if (!Buffer.isBuffer(buffer)) throw new ClilocFormatError('Not a buffer', 'NOT_BUFFER')
+  if (isCompressedCliloc(buffer)) {
+    throw new ClilocFormatError(
+      'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' +
+        'Convert it to the plain format first — see docs/website/CLILOCS.md.',
+      'COMPRESSED',
+    )
+  }
+  if (buffer.length < HEADER_BYTES) {
+    throw new ClilocFormatError('File is shorter than a cliloc header', 'TRUNCATED')
+  }
+
+  const entries = []
+  let offset = HEADER_BYTES
+
+  while (offset < buffer.length) {
+    if (offset + RECORD_HEADER_BYTES > buffer.length) {
+      throw new ClilocFormatError(
+        `Truncated record header at byte ${offset} (${entries.length} entries read)`,
+        'TRUNCATED',
+      )
+    }
+    const number = buffer.readInt32LE(offset)
+    const flag = buffer.readUInt8(offset + 4)
+    // The length is written by the client as an unsigned 16-bit value. Reading it
+    // signed (as ServUO's own SDK does) turns any string over 32 KB into a
+    // negative length; real tables top out around 12 KB, so this has no effect on
+    // current data and costs nothing to get right.
+    const length = buffer.readUInt16LE(offset + 5)
+    offset += RECORD_HEADER_BYTES
+
+    if (offset + length > buffer.length) {
+      throw new ClilocFormatError(
+        `Truncated record body at byte ${offset} (${entries.length} entries read)`,
+        'TRUNCATED',
+      )
+    }
+    entries.push({ number, flag, text: buffer.toString('utf8', offset, offset + length) })
+    offset += length
+  }
+
+  return entries
+}
+
+// A delimited line splits on the FIRST separator only: cliloc text is full of
+// commas ("a scroll of magery, unfinished") and splitting on all of them would
+// truncate every such entry at its first comma.
+const TEXT_SEPARATORS = ['\t', ',', ';']
+
+/** Unwrap one CSV field: strip surrounding quotes and unescape doubled quotes. */
+function unquote(value) {
+  const trimmed = value.trim()
+  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed.slice(1, -1).replace(/""/g, '"')
+  }
+  return trimmed
+}
+
+/**
+ * Parse a delimited text export: `number<sep>text` per line.
+ *
+ * Tolerant by design — this is whatever an operator's GUI tool produced, not a
+ * format we control. A header row, blank lines, `#` comments and a trailing
+ * flags column are all ignored. A line whose first field is not an integer is
+ * skipped rather than fatal, because that is exactly what a header row is.
+ *
+ * The one thing it will NOT do is return an empty table quietly: a file that
+ * yields no entries at all is a wrong file, not an empty one.
+ */
+function parseClilocText(text) {
+  const entries = []
+  for (const line of String(text).split(/\r?\n/)) {
+    // The line is deliberately NOT trimmed before the separator search. Roughly
+    // half of a real cliloc table is empty strings (unused ids), which export as
+    // `1005008<TAB>` — and trimming eats that trailing separator, leaving a bare
+    // number that then looks like a header row and is skipped. That silently
+    // dropped 55,994 of 123,490 entries. Individual FIELDS are trimmed instead,
+    // by `unquote`.
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue
+
+    // Pick the separator that actually appears first, so a tab-delimited line
+    // whose text contains a comma still splits on the tab.
+    let cut = -1
+    for (const sep of TEXT_SEPARATORS) {
+      const at = line.indexOf(sep)
+      if (at !== -1 && (cut === -1 || at < cut)) cut = at
+    }
+    if (cut === -1) continue
+
+    // An EMPTY first field must not become id 0: `Number('')` is 0, not NaN, so
+    // a line that merely starts with a separator would otherwise import as a
+    // bogus cliloc 0 instead of being skipped.
+    const head = unquote(line.slice(0, cut))
+    if (head === '') continue
+    const number = Number(head)
+    if (!Number.isInteger(number)) continue // header row, or a wrapped line
+
+    let rest = line.slice(cut + 1)
+    // Some exports carry `number,flag,text`. A bare integer in the second field
+    // is a flag; anything else is the text itself (and a text field that IS just
+    // a number is indistinguishable, so it stays as the text — the safer miss).
+    let flag = 0
+    for (const sep of TEXT_SEPARATORS) {
+      const at = rest.indexOf(sep)
+      if (at === -1) continue
+      const head = unquote(rest.slice(0, at))
+      if (/^\d{1,3}$/.test(head) && rest.slice(at + 1).trim() !== '') {
+        flag = Number(head)
+        rest = rest.slice(at + 1)
+      }
+      break
+    }
+
+    entries.push({ number, flag, text: unquote(rest) })
+  }
+
+  if (entries.length === 0) {
+    throw new ClilocFormatError('No cliloc entries found in the text export', 'EMPTY')
+  }
+  return entries
+}
+
+/**
+ * Parse either supported shape, sniffing which one this is.
+ *
+ * The sniff is on the binary header rather than the file extension: operators
+ * name these things whatever they like, and an `.enu` that is really a TSV (or a
+ * `.txt` that is really binary) should still import.
+ */
+function parseCliloc(buffer) {
+  const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer)
+
+  if (isCompressedCliloc(buf)) {
+    throw new ClilocFormatError(
+      'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' +
+        'Convert it to the plain format first — see docs/website/CLILOCS.md.',
+      'COMPRESSED',
+    )
+  }
+
+  // The plain layout always opens with version 2 / language 1. Anything else is
+  // treated as text, which is the recoverable guess: a mis-sniffed text file
+  // yields "no entries found", while a mis-sniffed binary yields nonsense.
+  if (buf.length >= HEADER_BYTES && buf.readInt32LE(0) === 2 && buf.readUInt16LE(4) === 1) {
+    return parseClilocBinary(buf)
+  }
+  return parseClilocText(buf.toString('utf8'))
+}
+
+// ── Display ────────────────────────────────────────────────────────────────
+
+// Cliloc strings interpolate arguments the client supplies out of an item's
+// property list: `~1_val~`, `~2_NAME~`, `~1_ITEM~`. We never have those — the
+// bridge sends the id, not the packet — so a name carrying them must be reduced
+// to what is actually knowable rather than shown with the raw tokens in it.
+const PLACEHOLDER_RE = /~\d+_[^~]*~/g
+
+/**
+ * Reduce a raw cliloc string to something displayable.
+ *
+ * Placeholders are dropped and the leftover punctuation tidied, so
+ * `"[~1_stuff~]"` becomes `""` (correctly nothing — the whole string was the
+ * argument) and `"cold damage ~1_val~%"` becomes `"cold damage"`.
+ *
+ * **Punctuation is only tidied when a placeholder was actually removed.** The
+ * trailing `%` above is the unit belonging to the number we never had, and the
+ * brackets in `[~1_stuff~]` only ever wrapped the argument — but a string with
+ * no placeholder has no such debris, and trimming it anyway corrupts real names.
+ * A shard's `"Runic Gateway Sigil (v2)"` came back as `"(v2"` while this was
+ * unconditional.
+ *
+ * Returns `''` when nothing survives, which callers treat as "no name" and fall
+ * back to the item id — better than showing a bracket.
+ */
+const DEBRIS = /^[\s\-–—,.;:%[\]()]+|[\s\-–—,.;:%[\]()]+$/g
+
+function displayText(raw) {
+  if (raw == null) return ''
+  const source = String(raw)
+  const hadPlaceholder = PLACEHOLDER_RE.test(source)
+  PLACEHOLDER_RE.lastIndex = 0 // the regex is global; `test` advances it
+
+  if (!hadPlaceholder) return source.replace(/\s+/g, ' ').trim()
+
+  return source
+    .replace(PLACEHOLDER_RE, ' ')
+    .replace(/\s+/g, ' ')
+    .replace(/\s+([,.;:!?])/g, '$1')
+    .replace(DEBRIS, '')
+    .trim()
+}
+
+/** True when a raw cliloc string is nothing but interpolated arguments. */
+const isPlaceholderOnly = (raw) => raw != null && String(raw).trim() !== '' && displayText(raw) === ''
+
+module.exports = {
+  ClilocFormatError,
+  PARSER_VERSION,
+  HEADER_BYTES,
+  isCompressedCliloc,
+  parseCliloc,
+  parseClilocBinary,
+  parseClilocText,
+  displayText,
+  isPlaceholderOnly,
+}

server/src/utils/clilocSource.js

@@ -0,0 +1,316 @@
+// Cliloc table — the filesystem layer.
+//
+// `clilocParse.js` holds the pure parsers; this module is the only thing that
+// touches cliloc files on disk, and it is shared by both callers:
+//
+//   - the server, which refreshes the table on boot (`shardClilocs.model.js`)
+//   - the admin panel, which can force a reimport without a restart
+//
+// The files are the OPERATOR'S (see docs/website/CLILOCS.md). Nothing derived
+// from them is committed: the repo holds no string table, exactly as it holds no
+// map snapshot and no artwork. That rule is why this module reads a configured
+// path instead of a path inside the repo.
+//
+// ── Why this reads a SET of files, not one ────────────────────────────────
+//
+// Shards edit items and add new ones. Those carry cliloc ids that a stock client
+// table does not have — and forcing a 5 MB client re-export every time an
+// operator adds one item would be miserable enough that the table would simply
+// go stale, which is the exact failure the spawn atlas was redesigned to avoid.
+//
+// So this mirrors `spawnAtlasSource.readSources()`: a BASE table (the converted
+// client file) plus every operator-maintained OVERLAY beside it, all re-read on
+// every boot and hash-gated as a SET. Adding, editing or removing any overlay
+// counts as drift and re-imports. Later sources win, so an overlay both adds new
+// ids and overrides stock ones.
+//
+// Measured on a real shard: the script tree references 16,434 cliloc ids and only
+// 37 are absent from the stock client table. Tens of entries against a 67k base
+// is what makes the overlay the right shape rather than a second full table.
+//
+// Reading and hashing ~5 MB costs a few milliseconds and a full parse ~50 ms, so
+// the boot path hashes first and only parses when something actually changed.
+
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+
+const { ClilocFormatError, PARSER_VERSION, parseCliloc, isCompressedCliloc } = require('./clilocParse')
+
+/**
+ * Filenames looked for as the BASE table when the configured path is a directory.
+ *
+ * Ordered by how specific they are: an explicitly converted file wins over
+ * something that merely sits in a client folder, so an operator who dropped a
+ * `cliloc.plain.enu` next to the original compressed `cliloc.enu` gets the one
+ * they made rather than the one that will be rejected.
+ *
+ * Matching is case-insensitive against the real directory listing, because the
+ * client ships `Cliloc.enu` on Windows and the site usually runs on Linux, where
+ * a hardcoded lowercase open would simply miss.
+ */
+const CANDIDATE_NAMES = [
+  'clilocs.tsv',
+  'clilocs.csv',
+  'clilocs.plain',
+  'cliloc.plain',
+  'cliloc.plain.enu',
+  'cliloc.enu.plain',
+  'clilocs.txt',
+  'cliloc.enu',
+]
+
+/**
+ * Where shard-specific additions and overrides live: a `custom/` directory
+ * beside the base table.
+ *
+ * ServUO has **no server-side convention** for custom clilocs — they live in the
+ * patched client file a shard distributes to its players, and nothing in the
+ * tree declares them. There is therefore nothing to discover, and this is the
+ * one place in the cliloc pipeline that is a convention we chose rather than one
+ * the shard already has. It is a directory rather than a single file so an
+ * operator can keep additions grouped however they like (per system, per patch)
+ * without the site caring.
+ */
+const CUSTOM_DIR = 'custom'
+const CUSTOM_EXTENSIONS = ['.tsv', '.csv', '.txt', '.enu', '.plain']
+
+class ClilocSourceError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.name = 'ClilocSourceError'
+    this.code = code
+  }
+}
+
+function sha256(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex')
+}
+
+/**
+ * Resolve the configured path to `{ root, base }`.
+ *
+ * Accepts either a direct file path or a directory to search, because operators
+ * reasonably supply both — "here is the file" and "here is the folder I put it
+ * in" are equally natural answers to the admin panel's prompt. When it is a
+ * file, `root` is the directory CONTAINING it, so overlays work either way: an
+ * operator who pointed at a file should not have to re-point at its folder just
+ * to add a `custom/` directory next to it.
+ */
+function resolveBase(configured) {
+  if (!configured || String(configured).trim() === '') {
+    throw new ClilocSourceError('No cliloc path configured', 'NO_PATH')
+  }
+  const target = String(configured).trim()
+
+  let stat
+  try {
+    stat = fs.statSync(target)
+  } catch {
+    throw new ClilocSourceError(`Cliloc path does not exist: ${target}`, 'NOT_FOUND')
+  }
+
+  if (stat.isFile()) return { root: path.dirname(target), base: target }
+
+  if (!stat.isDirectory()) {
+    throw new ClilocSourceError(`Cliloc path is neither a file nor a directory: ${target}`, 'NOT_FOUND')
+  }
+
+  let listing
+  try {
+    listing = fs.readdirSync(target)
+  } catch {
+    throw new ClilocSourceError(`Cliloc directory is not readable: ${target}`, 'NOT_FOUND')
+  }
+
+  const byLower = new Map(listing.map((name) => [name.toLowerCase(), name]))
+  for (const candidate of CANDIDATE_NAMES) {
+    const actual = byLower.get(candidate)
+    if (actual) return { root: target, base: path.join(target, actual) }
+  }
+
+  throw new ClilocSourceError(
+    `No cliloc file found in ${target} (looked for ${CANDIDATE_NAMES.join(', ')})`,
+    'NO_FILE',
+  )
+}
+
+/** Overlay files under `<root>/custom/`, sorted so precedence is deterministic. */
+function listCustom(root) {
+  const dir = path.join(root, CUSTOM_DIR)
+  let listing
+  try {
+    listing = fs.readdirSync(dir, { withFileTypes: true })
+  } catch (err) {
+    // No overlay directory is the normal case, not an error.
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return []
+    throw new ClilocSourceError(`Cliloc overlay directory is not readable: ${dir}`, 'UNREADABLE')
+  }
+  return listing
+    .filter((e) => e.isFile() && CUSTOM_EXTENSIONS.includes(path.extname(e.name).toLowerCase()))
+    .map((e) => e.name)
+    .sort()
+    .map((name) => path.join(dir, name))
+}
+
+function readFileOrThrow(file) {
+  try {
+    return fs.readFileSync(file)
+  } catch {
+    throw new ClilocSourceError(`Cliloc file is not readable: ${file}`, 'UNREADABLE')
+  }
+}
+
+/**
+ * Read every cliloc source under the configured path.
+ *
+ * Returns `{ root, files: [{ label, kind, file, buffer, sha256, bytes, compressed }] }`
+ * with the base first and overlays after, in the order they must be merged.
+ *
+ * Labels are root-relative and forward-slashed so a hash map compares equal
+ * across platforms — the same directory read on Windows and Linux must produce
+ * the same fingerprint, or every boot would look like a change. (The same
+ * reasoning, and the same bug, as `spawnAtlasSource.readSources`.)
+ */
+function readSources(configured) {
+  const { root, base } = resolveBase(configured)
+
+  const describe = (file, kind) => {
+    const buffer = readFileOrThrow(file)
+    return {
+      label: path.relative(root, file).split(path.sep).join('/'),
+      kind,
+      file,
+      buffer,
+      sha256: sha256(buffer),
+      bytes: buffer.length,
+      compressed: isCompressedCliloc(buffer),
+    }
+  }
+
+  const files = [describe(base, 'base')]
+  for (const overlay of listCustom(root)) files.push(describe(overlay, 'custom'))
+
+  return { root, files }
+}
+
+/**
+ * A fingerprint of every source: `{ "<label>": "<sha256>" }`, plus the base's
+ * details for the admin panel.
+ *
+ * `compressed` is reported here rather than left to the parse because the admin
+ * panel calls this and NOT `readCliloc` (parsing 5 MB on every status poll would
+ * be wasteful). Without it, pointing the setting at an unconverted client
+ * directory reports a perfectly readable file with pending drift — "ready to
+ * import" — and the operator only learns otherwise when the import fails. The
+ * check is four bytes of a buffer already in hand.
+ */
+function hashSources(configured) {
+  const { root, files } = readSources(configured)
+  const hashes = {}
+  for (const file of files) hashes[file.label] = file.sha256
+  const base = files[0]
+  return {
+    root,
+    hashes,
+    file: base.file,
+    bytes: base.bytes,
+    compressed: files.some((f) => f.compressed),
+    customCount: files.length - 1,
+  }
+}
+
+/** True when two source fingerprints describe the same set of files. */
+function sameSources(a, b) {
+  if (!a || !b) return false
+  const aKeys = Object.keys(a).sort()
+  const bKeys = Object.keys(b).sort()
+  if (aKeys.length !== bKeys.length) return false
+  return aKeys.every((key, i) => key === bKeys[i] && a[key] === b[key])
+}
+
+/**
+ * Labels present in `loaded` that are absent from `current`.
+ *
+ * This is the multi-source hazard that a single file did not have. One corrupt
+ * file fails the parse loudly, but a source that has simply VANISHED — an
+ * unmounted volume, a half-copied deploy — parses perfectly and imports a table
+ * quietly missing everything that file contributed. That is the same ambiguity
+ * the spawn atlas escalates for a disappearing facet, so it is escalated here
+ * too rather than applied.
+ */
+function missingSources(current, loaded) {
+  if (!loaded) return []
+  return Object.keys(loaded).filter((label) => !Object.hasOwn(current, label))
+}
+
+/**
+ * Read and parse every source, merged into one entry list.
+ *
+ * Later sources win: the base client table first, then each overlay in sorted
+ * order, so an overlay both ADDS ids the client never had and OVERRIDES stock
+ * ones the shard has re-purposed.
+ *
+ * Returns `{ entries, source }`. Throws `ClilocSourceError` for anything about
+ * the paths and `ClilocFormatError` for anything about the contents — different
+ * problems for an operator (wrong place vs wrong file), and the admin panel says
+ * which. A format error names the file it came from, because "which of my six
+ * overlay files is malformed" is otherwise a guessing game.
+ */
+function readCliloc(configured) {
+  const { root, files } = readSources(configured)
+
+  const merged = new Map()
+  const perSource = []
+
+  for (const file of files) {
+    let entries
+    try {
+      entries = parseCliloc(file.buffer)
+    } catch (err) {
+      if (err instanceof ClilocFormatError) {
+        throw new ClilocFormatError(`${file.label}: ${err.message}`, err.code)
+      }
+      throw err
+    }
+
+    let added = 0
+    let overrode = 0
+    for (const entry of entries) {
+      if (!Number.isInteger(entry.number)) continue
+      if (merged.has(entry.number)) overrode++
+      else added++
+      merged.set(entry.number, entry)
+    }
+    perSource.push({ label: file.label, kind: file.kind, entries: entries.length, added, overrode })
+  }
+
+  return {
+    entries: [...merged.values()],
+    source: {
+      root,
+      file: files[0].file,
+      sha256: files[0].sha256,
+      bytes: files[0].bytes,
+      hashes: Object.fromEntries(files.map((f) => [f.label, f.sha256])),
+      parserVersion: PARSER_VERSION,
+      sources: perSource,
+    },
+  }
+}
+
+module.exports = {
+  ClilocFormatError,
+  ClilocSourceError,
+  PARSER_VERSION,
+  CANDIDATE_NAMES,
+  CUSTOM_DIR,
+  CUSTOM_EXTENSIONS,
+  resolveBase,
+  listCustom,
+  readSources,
+  hashSources,
+  sameSources,
+  missingSources,
+  readCliloc,
+}

server/src/utils/shardIngest.js

@@ -15,7 +15,9 @@
 const shardEventsModel = require('../model/shardEvents/shardEvents.model')
 const shardStateModel = require('../model/shardState/shardState.model')
 const shardLinksModel = require('../model/shardLinks/shardLinks.model')
+const shardMarketModel = require('../model/shardMarket/shardMarket.model')
 const uoLinkConfigModel = require('../model/uoLinkConfig/uoLinkConfig.model')
+const settingsModel = require('../model/settings/settings.model')
 const broadcaster = require('./shardBroadcast')
 const pushDispatch = require('./pushDispatch')
 const defaultLog = require('./logger')('shard-ingest')
@@ -62,6 +64,31 @@ function shouldLog(event) {
   return LOGGED_KINDS.has(event.kind)
 }
 
+// ServUO's stock Server.cfg name. An operator who never set one publishes this
+// verbatim, so it carries no more information than a blank — matched
+// case-insensitively and trim-tolerantly, but ONLY as an exact whole value: a
+// shard genuinely called "My Shard Reborn" keeps its name.
+const STOCK_SHARD_NAME = 'my shard'
+
+/**
+ * The name to publish for the shard: its own, or this instance's when it has
+ * effectively not given one.
+ *
+ * Deliberately not a general "blank means brand" rule applied across the wire —
+ * it is scoped to this one field, where the two names denote the same thing.
+ */
+async function resolveShardName(shard, deps) {
+  const given = String(shard ?? '').trim()
+  if (given !== '' && given.toLowerCase() !== STOCK_SHARD_NAME) return given
+  try {
+    return (await deps.settings.getInstanceName()) || given
+  } catch {
+    // A ruleset that publishes the stock name is still better than one that
+    // fails to store because the settings read hiccuped.
+    return given
+  }
+}
+
 // Apply the state-change side effect for a kind (if any). Returns a promise.
 async function applyStateChange(event, deps) {
   const { shardState, uoLinkConfig, log } = deps
@@ -179,6 +206,15 @@ async function applyStateChange(event, deps) {
     // would put a duplicate row in the event log on every reconnect, and
     // server.hello already marks each of those.
     case 'world.ruleset':
+      // A shard whose operator never edited Server.cfg publishes ServUO's stock
+      // "My Shard". That is the shard saying *unnamed*, not a name, so the site
+      // answers with its own — the rules page reading "My Shard" under a header
+      // reading UOMysticmoon is the shard failing to introduce itself.
+      //
+      // Normalized HERE rather than on read because the ruleset is also live: the
+      // same `event` object is handed to the SSE broadcast a few lines below, and
+      // a read-time fix would be undone by the next reconnect's frame.
+      event.shard = await resolveShardName(event.shard, deps)
       await shardState.setRuleset(event)
       return
     // Board state, like guild.update — the newest frame for a system replaces the
@@ -187,6 +223,19 @@ async function applyStateChange(event, deps) {
     case 'points.board':
       await shardState.upsertPointsBoard(event)
       return
+    // Player-vendor market index. Each frame is authoritative for one shop, so
+    // the model replaces that vendor's whole listing set rather than merging.
+    //
+    // NOT in LOGGED_KINDS, and this is the strongest case of the three v3 kinds:
+    // one frame carries up to 250 listings, the sweep re-emits a shop on any
+    // price change, and appending each of those to the event log would make
+    // shard_events mostly a price history nobody reads. The market IS the state.
+    case 'vendor.listing':
+      await deps.shardMarket.upsertVendor(event)
+      return
+    case 'vendor.listing.remove':
+      await deps.shardMarket.removeVendor(event.serial)
+      return
     case 'account.unlinked':
       // A player ran [unlink in game (or a site-side unlink echoed back) — drop
       // our local link mirror so attribution stops immediately.
@@ -209,7 +258,9 @@ function resolveDeps(deps) {
     shardEvents: deps.shardEvents || shardEventsModel,
     shardState: deps.shardState || shardStateModel,
     shardLinks: deps.shardLinks || shardLinksModel,
+    shardMarket: deps.shardMarket || shardMarketModel,
     uoLinkConfig: deps.uoLinkConfig || uoLinkConfigModel,
+    settings: deps.settings || settingsModel,
     broadcast: deps.broadcast || broadcaster.broadcast,
     pushDispatch: deps.pushDispatch || pushDispatch.fromShardEvent,
     log: deps.log || defaultLog,

server/src/utils/shardVisibility.js

@@ -113,7 +113,21 @@ const FEATURES = {
   // Shop name, owner character name and vendor location are already globally
   // visible in-game via the stock Vendor Search gump, so publishing them is not
   // a new disclosure — but they stay configurable so an admin can tighten them.
-  market: { audience: 'anonymous', fields: { ownerName: 'anonymous', location: 'anonymous' } },
+  //
+  // `ownerName` and `location` were pre-wired here by Part A, before the frame
+  // existed; both were re-checked against the real `vendor.listing` and both are
+  // genuine keys on it (unlike leaderboards' `characterName`, which was inert).
+  // `location` is a NESTED object on the wire and on the read model precisely so
+  // that one rule hides map, coordinates, region and house together — five flat
+  // keys would be five rules that drift apart.
+  //
+  // `ownerSerial` is listed alongside `ownerName` for the same reason `houses`
+  // lists both: an admin who hides the owner's name and is left with a serial
+  // that every other board resolves back to that name has not hidden anything.
+  market: {
+    audience: 'anonymous',
+    fields: { ownerName: 'anonymous', ownerSerial: 'anonymous', location: 'anonymous' },
+  },
 }
 
 const FEATURE_NAMES = Object.keys(FEATURES)

server/src/utils/uoLinkClient.js

@@ -58,7 +58,7 @@ async function call(path, { method = 'GET', body } = {}) {
 
     const headers = {
       'Content-Type': 'application/json',
-      'X-UOLink-Version': String(config.protocol || 1),
+      'X-UOLink-Version': String(config.protocol || 3),
     }
     if (config.token) headers.Authorization = `Bearer ${config.token}`
 
@@ -135,6 +135,11 @@ const getRuleset = () => call('/ruleset')
 // under `boards`); the per-system read 404s for a system the shard never published.
 const getPoints = () => call('/points')
 const getPointsBoard = (system) => call(`/points/${encodeURIComponent(system)}`)
+// Protocol 3.0: the player-vendor market index. The one PAGED sidecar read — a
+// whole-world market does not fit in a response — so it answers with
+// `{ vendors, total, limit, offset }` and the caller walks it (see uoLinkSocket).
+const getMarket = ({ limit = 200, offset = 0 } = {}) =>
+  call(`/market?limit=${encodeURIComponent(limit)}&offset=${encodeURIComponent(offset)}`)
 
 // ── Commands ──────────────────────────────────────────────────────────────
 const confirmLink = (code, websiteUserId) =>
@@ -201,6 +206,7 @@ module.exports = {
   getRuleset,
   getPoints,
   getPointsBoard,
+  getMarket,
   confirmLink,
   linkLookup,
   createAccount,

server/src/utils/uoLinkSocket.js

@@ -63,6 +63,55 @@ async function ingestEach(events) {
   for (const ev of events) await shardIngest.ingest(ev, { fromBackfill: true })
 }
 
+// ── Market backfill ────────────────────────────────────────────────────────
+//
+// The market is the only board that does not fit in one response, so /market is
+// paged and this walks it. Two bounds, both deliberate:
+//
+//   • MARKET_SNAPSHOT_MAX caps the walk. A pathological world (or a sidecar whose
+//     store was never pruned) must not be able to hang startup — backfill runs
+//     before the site is serving the live feed, so an unbounded loop here is
+//     downtime, not slowness.
+//   • The loop stops on a SHORT page as well as on `total`, because a concurrent
+//     sweep can shrink the index underneath the walk and paging to a stale total
+//     would spin.
+//
+// Vendors are upserted, never reconciled-by-replacement. A vendor absent from the
+// snapshot is absent because the sidecar dropped it on vendor.listing.remove —
+// which our own ingest already processed — so clearing the table first would only
+// create a window where the market page is empty.
+const MARKET_SNAPSHOT_MAX = 5000
+const MARKET_PAGE = 200
+
+async function backfillMarket() {
+  let offset = 0
+  let seen = 0
+
+  for (;;) {
+    const res = await uoLinkClient.getMarket({ limit: MARKET_PAGE, offset })
+    if (!res.ok || !res.data || !Array.isArray(res.data.vendors)) return
+
+    const page = res.data.vendors
+    if (page.length === 0) break
+
+    await ingestEach(page)
+    seen += page.length
+    offset += page.length
+
+    if (page.length < MARKET_PAGE) break
+    if (seen >= MARKET_SNAPSHOT_MAX) {
+      log.warn('market snapshot truncated at the safety cap', {
+        cap: MARKET_SNAPSHOT_MAX,
+        total: res.data.total,
+      })
+      break
+    }
+    if (Number.isFinite(res.data.total) && offset >= res.data.total) break
+  }
+
+  if (seen > 0) log.info('snapshotted player-vendor market from /market', { count: seen })
+}
+
 // Pull recent events from the sidecar's own store and replay them through the
 // dispatcher (fromBackfill = no SSE re-broadcast). dedupe_key + INSERT IGNORE
 // make this idempotent, so overlap with what we already stored is harmless.
@@ -93,9 +142,15 @@ async function backfill() {
     // snapshot() (which asserts an array under `key`). The shard also re-emits
     // world.ruleset on its own connect — this covers the other order, where the
     // sidecar was already up and holding the ruleset when WE reconnected.
+    //
+    // Routed through the dispatcher rather than straight to shardState, exactly as
+    // ingestEach does for the array-shaped boards: the two orders must produce the
+    // same stored frame, and calling setRuleset directly here made this a second
+    // write path that silently skipped the shard-name normalization the live frame
+    // gets. One writer, one set of rules.
     const ruleset = await uoLinkClient.getRuleset()
     if (ruleset.ok && ruleset.data && ruleset.data.ruleset) {
-      await shardState.setRuleset(ruleset.data.ruleset)
+      await shardIngest.ingest(ruleset.data.ruleset, { fromBackfill: true })
       log.info('snapshotted shard ruleset from /ruleset', { rev: ruleset.data.ruleset.rev })
     }
 
@@ -106,6 +161,8 @@ async function backfill() {
     // which is the right answer for a month-scale standing.
     await snapshot(() => uoLinkClient.getPoints(), 'boards', ingestEach, 'snapshotted points boards from /points')
 
+    await backfillMarket()
+
     const presence = await uoLinkClient.getPresence()
     if (presence.ok && presence.data && typeof presence.data.count === 'number') {
       await shardState.setPresence(presence.data)
@@ -146,7 +203,7 @@ async function connect() {
     return
   }
 
-  state.protocol = config.protocol || 1
+  state.protocol = config.protocol || 3
   helloSeen = false
   const url = buildUrl(config.wsUrl, config.token)
 

server/swagger/swagger.js

@@ -910,6 +910,97 @@ const doc = {
           updatedAt: { type: 'string', format: 'date-time' },
         },
       },
+      ShardMarketLocation: {
+        type: 'object',
+        nullable: true,
+        description:
+          "Where a vendor is standing. ONE nested object rather than flat map/x/y/region because it is one admin-configurable field (`market.location`) — the whole object is omitted when that field is gated above the caller.",
+        properties: {
+          map: { type: 'string', nullable: true, example: 'Trammel' },
+          x: { type: 'integer', nullable: true, example: 1421 },
+          y: { type: 'integer', nullable: true, example: 1699 },
+          z: { type: 'integer', nullable: true, example: 0 },
+          region: { type: 'string', nullable: true, example: 'Britain' },
+          house: { type: 'string', nullable: true, example: "Darrow's Villa", description: "The house SIGN's name, not the house type. Null for a vendor standing outside one." },
+        },
+      },
+      ShardMarketListing: {
+        type: 'object',
+        description:
+          'One priced listing on a player vendor, carrying enough of its shop to be actionable without a second request.',
+        properties: {
+          serial: { type: 'string', example: '0x40012ABC' },
+          itemId: { type: 'integer', example: 3922, description: 'ItemID (the art/graphic id).' },
+          hue: { type: 'integer', example: 0 },
+          amount: { type: 'integer', example: 1 },
+          price: { type: 'integer', example: 25000 },
+          name: { type: 'string', nullable: true, description: "The item's own literal name, set by a player. Null for most items." },
+          cliloc: { type: 'integer', nullable: true, example: 1023721, description: "The item's LabelNumber." },
+          displayName: {
+            type: 'string',
+            nullable: true,
+            example: 'quarter staff',
+            description: 'Resolved server-side from `name` (preferred, being player-set and more specific) else `cliloc`. Null on a shard with no cliloc table configured — render the item id.',
+          },
+          child: { type: 'boolean', example: false, description: 'Priced by an enclosing container rather than itself, exactly as the in-game Vendor Search reports it.' },
+          vendor: {
+            type: 'object',
+            properties: {
+              serial: { type: 'string', example: '0x40001234' },
+              shopName: { type: 'string', nullable: true, example: "Darrow's Bargains" },
+              ownerSerial: { type: 'string', nullable: true, example: '0x1A2B', description: 'Omitted when the market `ownerSerial` field is gated above the caller.' },
+              ownerName: { type: 'string', nullable: true, example: 'Darrow', description: 'Omitted when the market `ownerName` field is gated above the caller.' },
+              location: { $ref: '#/components/schemas/ShardMarketLocation' },
+              updatedAt: { type: 'string', format: 'date-time', description: 'When the shard last published this shop.' },
+            },
+          },
+        },
+      },
+      ShardMarketPage: {
+        type: 'object',
+        description: 'A page of marketplace listings plus the unpaginated total and the staleness stamp.',
+        properties: {
+          listings: { type: 'array', items: { $ref: '#/components/schemas/ShardMarketListing' } },
+          total: { type: 'integer', example: 1284, description: 'Matching listings, ignoring paging.' },
+          limit: { type: 'integer', example: 50 },
+          offset: { type: 'integer', example: 0 },
+          vendors: { type: 'integer', example: 137, description: 'Vendors in the whole index.' },
+          staleAt: {
+            type: 'string',
+            format: 'date-time',
+            nullable: true,
+            description: 'The OLDEST vendor row. The shard sweeps vendors round-robin, so the index can be a full cycle behind and a client must say so rather than implying live prices.',
+          },
+        },
+      },
+      ShardMarketVendor: {
+        type: 'object',
+        description: 'One player vendor and its listings.',
+        properties: {
+          serial: { type: 'string', example: '0x40001234' },
+          shopName: { type: 'string', nullable: true, example: "Darrow's Bargains" },
+          ownerSerial: { type: 'string', nullable: true },
+          ownerName: { type: 'string', nullable: true, example: 'Darrow' },
+          location: { $ref: '#/components/schemas/ShardMarketLocation' },
+          count: { type: 'integer', example: 250, description: 'Listings the shard published for this shop.' },
+          total: { type: 'integer', example: 3104, description: 'Listings the shop actually holds.' },
+          truncated: { type: 'boolean', example: true, description: '`total` exceeds `count` — the shop holds more than the shard publishes per frame.' },
+          updatedAt: { type: 'string', format: 'date-time' },
+          items: { type: 'array', items: { $ref: '#/components/schemas/ShardMarketListing' } },
+        },
+      },
+      ShardMarketMeta: {
+        type: 'object',
+        description: 'Marketplace size, staleness and the filter options a client needs to build its UI.',
+        properties: {
+          vendors: { type: 'integer', example: 137 },
+          items: { type: 'integer', example: 18422 },
+          staleAt: { type: 'string', format: 'date-time', nullable: true },
+          freshAt: { type: 'string', format: 'date-time', nullable: true },
+          maps: { type: 'array', items: { type: 'string' }, example: ['Felucca', 'Trammel'], description: "Facets that actually hold vendors. From the shard's own data — never a hardcoded list." },
+          regions: { type: 'array', items: { type: 'string' }, example: ['Britain', 'Luna'] },
+        },
+      },
       ShardFeatures: {
         type: 'object',
         description:
@@ -1161,6 +1252,102 @@ const doc = {
           removedFacets: { type: 'array', items: { type: 'string' } },
         },
       },
+      ClilocStatus: {
+        type: 'object',
+        description:
+          'Admin view of cliloc state: where the converted file is, whether it is readable, how many entries are loaded, and whether the file has drifted from them. `configured: false` is a supported state — item names then render as ids.',
+        properties: {
+          configured: { type: 'boolean', example: true },
+          path: { type: 'string', example: '/srv/uo-client' },
+          file: { type: 'string', nullable: true, description: 'The file actually resolved, when the path is a directory.', example: '/srv/uo-client/clilocs.tsv' },
+          fileReadable: { type: 'boolean', example: true },
+          problem: { type: 'string', nullable: true, description: 'Why the file cannot be used, when it cannot. Set (with code COMPRESSED) for a readable-but-unconverted client file.', example: null },
+          code: { type: 'string', nullable: true, description: 'Machine-readable cause of `problem`.', enum: ['NO_PATH', 'NOT_FOUND', 'NO_FILE', 'UNREADABLE', 'COMPRESSED'] },
+          drift: { type: 'boolean', nullable: true, description: 'True when any source hash differs from the loaded table. NULL when the sources could not be read or are not usable.', example: false },
+          count: { type: 'integer', description: 'Entries currently loaded.', example: 67496 },
+          sources: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Every source found now, root-relative, base first then overlays in merge order.',
+            example: ['clilocs.plain', 'custom/uomysticmoon.tsv'],
+          },
+          loadedSources: {
+            type: 'array',
+            nullable: true,
+            description: 'What each source contributed at the last import.',
+            items: {
+              type: 'object',
+              properties: {
+                label: { type: 'string', example: 'custom/uomysticmoon.tsv' },
+                kind: { type: 'string', enum: ['base', 'custom'], example: 'custom' },
+                entries: { type: 'integer', example: 37 },
+                added: { type: 'integer', description: 'Ids this source introduced.', example: 25 },
+                overrode: { type: 'integer', description: 'Ids it replaced from an earlier source.', example: 12 },
+              },
+            },
+          },
+          missingSources: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Sources loaded previously and now absent. An import refuses these without `approve`.',
+            example: [],
+          },
+          importedAt: { type: 'string', format: 'date-time', nullable: true },
+          sourceBytes: { type: 'integer', nullable: true, example: 4973525 },
+        },
+      },
+      ClilocRefreshResult: {
+        type: 'object',
+        description:
+          'Outcome of a cliloc refresh. Reported rather than thrown, so a missing or compressed file is an answer and not a 500.',
+        properties: {
+          status: {
+            type: 'string',
+            enum: ['skipped', 'unavailable', 'unchanged', 'imported', 'needsReview', 'failed'],
+            description: '`needsReview` means a previously-loaded source has vanished and nothing was applied; re-run with `approve` to accept it.',
+            example: 'imported',
+          },
+          reason: { type: 'string', nullable: true },
+          code: {
+            type: 'string',
+            nullable: true,
+            description: 'Machine-readable cause. `COMPRESSED` means the client\'s own Cliloc.enu was supplied instead of a converted one.',
+            enum: ['NO_PATH', 'NOT_FOUND', 'NO_FILE', 'UNREADABLE', 'COMPRESSED', 'TRUNCATED', 'EMPTY', 'NOT_BUFFER'],
+          },
+          path: { type: 'string', nullable: true },
+          file: { type: 'string', nullable: true },
+          count: { type: 'integer', nullable: true, description: 'Entries stored (blank strings are dropped).', example: 67496 },
+          parsed: { type: 'integer', nullable: true, description: 'Entries read across every source before blanks were dropped.', example: 123527 },
+          blank: { type: 'integer', nullable: true, example: 55994 },
+          sources: {
+            type: 'array',
+            nullable: true,
+            description: 'Per-source breakdown: what each file contributed and how much of it overrode an earlier source.',
+            items: {
+              type: 'object',
+              properties: {
+                label: { type: 'string' },
+                kind: { type: 'string', enum: ['base', 'custom'] },
+                entries: { type: 'integer' },
+                added: { type: 'integer' },
+                overrode: { type: 'integer' },
+              },
+            },
+          },
+          missingSources: {
+            type: 'array',
+            nullable: true,
+            items: { type: 'string' },
+            description: 'On `needsReview`: the sources that vanished. Nothing was applied.',
+          },
+          acceptedMissing: {
+            type: 'array',
+            nullable: true,
+            items: { type: 'string' },
+            description: 'On `imported` with `approve`: the vanished sources the admin accepted.',
+          },
+        },
+      },
       ShardLinkRequest: {
         type: 'object',
         required: ['code'],

server/test/clilocParse.test.js

@@ -0,0 +1,227 @@
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+
+const {
+  ClilocFormatError,
+  parseCliloc,
+  parseClilocBinary,
+  parseClilocText,
+  isCompressedCliloc,
+  displayText,
+  isPlaceholderOnly,
+} = require('../src/utils/clilocParse')
+
+// These parsers are pure and fs-free precisely so this suite can run in CI,
+// where there is no UO client and no converted cliloc file. Every fixture below
+// is built from the real layout, and the strings are verbatim entries from a
+// real Cliloc.enu (123,490 entries) rather than invented ones.
+
+// ── Fixture builders ───────────────────────────────────────────────────────
+
+/** Build a plain-format cliloc buffer: 6-byte header, then records. */
+function buildBinary(entries, { header1 = 2, header2 = 1 } = {}) {
+  const parts = [Buffer.alloc(6)]
+  parts[0].writeInt32LE(header1, 0)
+  parts[0].writeUInt16LE(header2, 4)
+  for (const e of entries) {
+    const text = Buffer.from(e.text, 'utf8')
+    const head = Buffer.alloc(7)
+    head.writeInt32LE(e.number, 0)
+    head.writeUInt8(e.flag ?? 0, 4)
+    head.writeUInt16LE(text.length, 5)
+    parts.push(head, text)
+  }
+  return Buffer.concat(parts)
+}
+
+// ── Binary ─────────────────────────────────────────────────────────────────
+
+test('parseClilocBinary: reads a plain-format table', () => {
+  const buf = buildBinary([
+    { number: 1015012, text: 'Greater Heal' },
+    { number: 1023721, text: 'quarter staff' },
+    { number: 1025913, flag: 1, text: 'bonnet' },
+  ])
+  assert.deepEqual(parseClilocBinary(buf), [
+    { number: 1015012, flag: 0, text: 'Greater Heal' },
+    { number: 1023721, flag: 0, text: 'quarter staff' },
+    { number: 1025913, flag: 1, text: 'bonnet' },
+  ])
+})
+
+test('parseClilocBinary: length is UNSIGNED 16-bit', () => {
+  // ServUO's own SDK reads this field into a signed short, which turns any
+  // string over 32 KB into a negative length. Real tables top out around 12 KB
+  // so nothing is broken today, but the field is written unsigned and reading it
+  // that way costs nothing.
+  const text = 'x'.repeat(40000)
+  const [entry] = parseClilocBinary(buildBinary([{ number: 1000000, text }]))
+  assert.equal(entry.text.length, 40000)
+})
+
+test('parseClilocBinary: multi-byte UTF-8 survives (length is in BYTES)', () => {
+  const [entry] = parseClilocBinary(buildBinary([{ number: 1000000, text: 'Ilshenar — Ver Lor Reg' }]))
+  assert.equal(entry.text, 'Ilshenar — Ver Lor Reg')
+})
+
+test('parseClilocBinary: a truncated record body throws rather than importing short', () => {
+  // The realistic corruption is a half-copied file. It must fail loudly: a
+  // silently short table renders as "some items named, some not", which is
+  // indistinguishable from having no table at all.
+  const buf = buildBinary([{ number: 1023721, text: 'quarter staff' }])
+  const truncated = buf.subarray(0, buf.length - 4)
+  assert.throws(() => parseClilocBinary(truncated), (err) => {
+    assert.ok(err instanceof ClilocFormatError)
+    assert.equal(err.code, 'TRUNCATED')
+    return true
+  })
+})
+
+test('parseClilocBinary: a truncated record HEADER throws too', () => {
+  const buf = Buffer.concat([buildBinary([{ number: 1023721, text: 'quarter staff' }]), Buffer.alloc(3)])
+  assert.throws(() => parseClilocBinary(buf), (err) => err.code === 'TRUNCATED')
+})
+
+test('parseClilocBinary: an empty table (header only) is valid', () => {
+  assert.deepEqual(parseClilocBinary(buildBinary([])), [])
+})
+
+// ── Compressed detection ───────────────────────────────────────────────────
+
+test('isCompressedCliloc: recognises the Mythic marker', () => {
+  // Every cliloc the client ships opens with a DWORD whose high byte is 0x8E.
+  // Real first bytes of Cliloc.enu (e8 79 67 8e) and Cliloc.deu (99 5d 26 8e).
+  assert.equal(isCompressedCliloc(Buffer.from([0xe8, 0x79, 0x67, 0x8e])), true)
+  assert.equal(isCompressedCliloc(Buffer.from([0x99, 0x5d, 0x26, 0x8e])), true)
+  assert.equal(isCompressedCliloc(buildBinary([])), false)
+})
+
+test('parseCliloc: a compressed file is rejected by NAME, not parsed into nonsense', () => {
+  // This is the whole reason the marker check exists. Without it the plain
+  // parser reads compressed bytes as ~19k records of negative ids and 60 KB
+  // "strings" before dying somewhere in the middle — and the resulting error
+  // names truncation, which is the wrong problem to hand an operator.
+  const compressed = Buffer.concat([Buffer.from([0xe8, 0x79, 0x67, 0x8e]), Buffer.alloc(64, 0x41)])
+  assert.throws(() => parseCliloc(compressed), (err) => {
+    assert.equal(err.code, 'COMPRESSED')
+    assert.match(err.message, /CLILOCS\.md/)
+    return true
+  })
+})
+
+// ── Text ───────────────────────────────────────────────────────────────────
+
+test('parseClilocText: tab-delimited, skipping a header row', () => {
+  const entries = parseClilocText('number\ttext\n1023721\tquarter staff\n1015012\tGreater Heal\n')
+  assert.deepEqual(entries, [
+    { number: 1023721, flag: 0, text: 'quarter staff' },
+    { number: 1015012, flag: 0, text: 'Greater Heal' },
+  ])
+})
+
+test('parseClilocText: splits on the FIRST separator only', () => {
+  // Cliloc text is full of commas. Splitting on all of them would truncate every
+  // such entry at its first one.
+  const [entry] = parseClilocText('1044000,a scroll of magery, unfinished\n')
+  assert.equal(entry.text, 'a scroll of magery, unfinished')
+})
+
+test('parseClilocText: unwraps quoted CSV fields and doubled quotes', () => {
+  const [entry] = parseClilocText('1023721,"a ""quarter"" staff, plain"\n')
+  assert.equal(entry.text, 'a "quarter" staff, plain')
+})
+
+test('parseClilocText: reads an optional flag column', () => {
+  const [entry] = parseClilocText('1025913\t1\tbonnet\n')
+  assert.deepEqual(entry, { number: 1025913, flag: 1, text: 'bonnet' })
+})
+
+test('parseClilocText: text that is itself a number stays the text', () => {
+  // `number,text` where text is "100" is indistinguishable from `number,flag`
+  // with an empty text. Keeping it as the text is the safer miss — the other way
+  // silently deletes a real entry.
+  const [entry] = parseClilocText('1000000,100\n')
+  assert.equal(entry.text, '100')
+})
+
+test('parseClilocText: blank lines and # comments are ignored', () => {
+  const entries = parseClilocText('# exported by hand\n\n1023721\tquarter staff\n\n')
+  assert.equal(entries.length, 1)
+})
+
+test('parseClilocText: a file with no entries is an error, not an empty table', () => {
+  assert.throws(() => parseClilocText('nothing here\nnor here\n'), (err) => err.code === 'EMPTY')
+})
+
+test('parseClilocText: an empty leading field is skipped, not imported as id 0', () => {
+  // `Number('')` is 0, not NaN, so a line that merely starts with a separator
+  // would otherwise become a bogus cliloc 0.
+  assert.throws(() => parseClilocText('\tstray text\n,another\n'), (err) => err.code === 'EMPTY')
+})
+
+test('parseClilocText: keeps entries whose text is EMPTY', () => {
+  // About half of a real table is empty strings (unused ids). They must survive
+  // parsing — the import layer decides whether to store them, and both input
+  // formats have to agree on what the file contained.
+  const entries = parseClilocText('1005008\t\n1023721\tquarter staff\n')
+  assert.equal(entries.length, 2)
+  assert.deepEqual(entries[0], { number: 1005008, flag: 0, text: '' })
+})
+
+// ── Sniffing ───────────────────────────────────────────────────────────────
+
+test('parseCliloc: sniffs binary vs text from the header, not the extension', () => {
+  assert.equal(parseCliloc(buildBinary([{ number: 1023721, text: 'quarter staff' }]))[0].text, 'quarter staff')
+  assert.equal(parseCliloc(Buffer.from('1023721\tquarter staff\n'))[0].text, 'quarter staff')
+})
+
+test('parseCliloc: a binary-looking header that is not 2/1 falls through to text', () => {
+  // The recoverable guess: a mis-sniffed text file says "no entries found",
+  // while a mis-sniffed binary yields plausible nonsense.
+  assert.throws(() => parseCliloc(Buffer.from([9, 0, 0, 0, 9, 0, 65, 66])), (err) => err.code === 'EMPTY')
+})
+
+// ── Display ────────────────────────────────────────────────────────────────
+
+test('displayText: drops interpolated arguments we never receive', () => {
+  // The bridge sends a cliloc id, never the property packet that carries the
+  // arguments, so a name containing them has to be reduced to what is knowable.
+  assert.equal(displayText('cold damage ~1_val~%'), 'cold damage')
+  assert.equal(displayText('~1_NAME~ the ~2_TITLE~'), 'the')
+})
+
+test('displayText: a string that is nothing but arguments resolves to nothing', () => {
+  assert.equal(displayText('[~1_stuff~]'), '')
+  assert.equal(isPlaceholderOnly('[~1_stuff~]'), true)
+  assert.equal(isPlaceholderOnly('quarter staff'), false)
+})
+
+test('displayText: a trailing % is only stripped when a placeholder was removed', () => {
+  // "cold damage ~1_val~%" loses its % because that % was the unit belonging to
+  // the number we never had. A string that genuinely ends in one keeps it.
+  assert.equal(displayText('50%'), '50%')
+  assert.equal(displayText('cold damage ~1_val~%'), 'cold damage')
+})
+
+test('displayText: ordinary names pass through untouched', () => {
+  assert.equal(displayText('quarter staff'), 'quarter staff')
+  assert.equal(displayText('a scroll of magery, unfinished'), 'a scroll of magery, unfinished')
+  assert.equal(displayText('  spiked collar  '), 'spiked collar')
+})
+
+test('displayText: punctuation is only tidied when a placeholder was removed', () => {
+  // A shard's custom "Runic Gateway Sigil (v2)" came back as "(v2" while the
+  // bracket trim was unconditional. A string with no placeholder has no debris
+  // to clean, so it is left alone apart from whitespace.
+  assert.equal(displayText('Runic Gateway Sigil (v2)'), 'Runic Gateway Sigil (v2)')
+  assert.equal(displayText('scroll of power - greater'), 'scroll of power - greater')
+  assert.equal(displayText('[Companion] Great Dane'), '[Companion] Great Dane')
+  // …but the debris a placeholder leaves behind is still cleaned.
+  assert.equal(displayText('[~1_stuff~]'), '')
+  assert.equal(displayText('cold damage ~1_val~%'), 'cold damage')
+})
+
+test('displayText: null and undefined are empty, not "null"', () => {
+  assert.equal(displayText(null), '')
+  assert.equal(displayText(undefined), '')
+})

server/test/clilocSource.test.js

@@ -0,0 +1,194 @@
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const {
+  ClilocSourceError,
+  CUSTOM_DIR,
+  resolveBase,
+  listCustom,
+  readSources,
+  hashSources,
+  sameSources,
+  missingSources,
+  readCliloc,
+} = require('../src/utils/clilocSource')
+
+// The fs layer, exercised against real temp directories rather than mocks —
+// the behaviours that matter here (which file wins, what a directory listing
+// yields, what happens when one vanishes) are precisely the ones a mock would
+// define away.
+
+function tmpdir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cliloc-'))
+  return dir
+}
+
+const tsv = (entries) => entries.map(([n, t]) => `${n}\t${t}`).join('\n') + '\n'
+
+function write(dir, name, contents) {
+  const file = path.join(dir, name)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, contents)
+  return file
+}
+
+// ── Resolution ─────────────────────────────────────────────────────────────
+
+test('resolveBase: a directory picks the most specific candidate', () => {
+  const dir = tmpdir()
+  // A converted file sitting next to the client's own compressed one must win —
+  // otherwise pointing at a client folder finds the file that will be rejected.
+  write(dir, 'cliloc.enu', 'ignored')
+  write(dir, 'clilocs.tsv', tsv([[1023721, 'quarter staff']]))
+  assert.equal(path.basename(resolveBase(dir).base), 'clilocs.tsv')
+})
+
+test('resolveBase: a file path roots overlays at its DIRECTORY', () => {
+  // An operator who pointed at a file should not have to re-point at its folder
+  // just to add a custom/ directory beside it.
+  const dir = tmpdir()
+  const file = write(dir, 'clilocs.tsv', tsv([[1, 'a']]))
+  assert.deepEqual(resolveBase(file), { root: dir, base: file })
+})
+
+test('resolveBase: a missing path and an empty path are different errors', () => {
+  assert.throws(() => resolveBase(''), (err) => err.code === 'NO_PATH')
+  assert.throws(() => resolveBase(path.join(tmpdir(), 'nope')), (err) => err.code === 'NOT_FOUND')
+})
+
+test('resolveBase: a directory with no cliloc file names what it looked for', () => {
+  assert.throws(() => resolveBase(tmpdir()), (err) => {
+    assert.ok(err instanceof ClilocSourceError)
+    assert.equal(err.code, 'NO_FILE')
+    assert.match(err.message, /clilocs\.tsv/)
+    return true
+  })
+})
+
+// ── Overlays ───────────────────────────────────────────────────────────────
+
+test('listCustom: no overlay directory is normal, not an error', () => {
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1, 'a']]))
+  assert.deepEqual(listCustom(dir), [])
+})
+
+test('listCustom: sorted, and only recognised extensions', () => {
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1, 'a']]))
+  write(dir, `${CUSTOM_DIR}/b.tsv`, tsv([[2, 'b']]))
+  write(dir, `${CUSTOM_DIR}/a.csv`, tsv([[3, 'c']]))
+  write(dir, `${CUSTOM_DIR}/notes.md`, 'ignore me')
+  assert.deepEqual(listCustom(dir).map((f) => path.basename(f)), ['a.csv', 'b.tsv'])
+})
+
+test('readSources: base first, then overlays, with root-relative labels', () => {
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1, 'a']]))
+  write(dir, `${CUSTOM_DIR}/shard.tsv`, tsv([[2, 'b']]))
+  const { files } = readSources(dir)
+  // Forward-slashed so the same directory read on Windows and Linux fingerprints
+  // identically — otherwise every boot on one of them looks like a change.
+  assert.deepEqual(files.map((f) => [f.label, f.kind]), [
+    ['clilocs.tsv', 'base'],
+    ['custom/shard.tsv', 'custom'],
+  ])
+})
+
+// ── Merging ────────────────────────────────────────────────────────────────
+
+test('readCliloc: an overlay ADDS ids the base never had', () => {
+  // The whole point: shards add items, and those carry cliloc ids no stock
+  // client table has.
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1023721, 'quarter staff']]))
+  write(dir, `${CUSTOM_DIR}/shard.tsv`, tsv([[1180001, 'Runic Gateway Sigil']]))
+  const byNumber = new Map(readCliloc(dir).entries.map((e) => [e.number, e.text]))
+  assert.equal(byNumber.get(1023721), 'quarter staff')
+  assert.equal(byNumber.get(1180001), 'Runic Gateway Sigil')
+})
+
+test('readCliloc: an overlay OVERRIDES a stock id', () => {
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1023721, 'quarter staff']]))
+  write(dir, `${CUSTOM_DIR}/shard.tsv`, tsv([[1023721, 'gnarled staff of testing']]))
+  const byNumber = new Map(readCliloc(dir).entries.map((e) => [e.number, e.text]))
+  assert.equal(byNumber.get(1023721), 'gnarled staff of testing')
+})
+
+test('readCliloc: later overlays beat earlier ones, deterministically', () => {
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[7, 'base']]))
+  write(dir, `${CUSTOM_DIR}/01-first.tsv`, tsv([[7, 'first']]))
+  write(dir, `${CUSTOM_DIR}/02-second.tsv`, tsv([[7, 'second']]))
+  const byNumber = new Map(readCliloc(dir).entries.map((e) => [e.number, e.text]))
+  assert.equal(byNumber.get(7), 'second')
+})
+
+test('readCliloc: reports what each source contributed', () => {
+  // An operator who adds an overlay wants to see it took effect; "overrode: 0"
+  // on a file meant to re-label stock items says it did not.
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1, 'a'], [2, 'b']]))
+  write(dir, `${CUSTOM_DIR}/shard.tsv`, tsv([[2, 'B!'], [3, 'c']]))
+  const { source } = readCliloc(dir)
+  assert.deepEqual(source.sources, [
+    { label: 'clilocs.tsv', kind: 'base', entries: 2, added: 2, overrode: 0 },
+    { label: 'custom/shard.tsv', kind: 'custom', entries: 2, added: 1, overrode: 1 },
+  ])
+})
+
+test('readCliloc: a malformed overlay names the file it came from', () => {
+  // "Which of my six overlay files is broken" is otherwise a guessing game.
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1, 'a']]))
+  write(dir, `${CUSTOM_DIR}/broken.tsv`, 'no separators here\nnor here\n')
+  assert.throws(() => readCliloc(dir), (err) => {
+    assert.equal(err.code, 'EMPTY')
+    assert.match(err.message, /^custom\/broken\.tsv: /)
+    return true
+  })
+})
+
+test('readCliloc: a compressed BASE is still rejected by name', () => {
+  const dir = tmpdir()
+  write(dir, 'cliloc.enu', Buffer.concat([Buffer.from([0xe8, 0x79, 0x67, 0x8e]), Buffer.alloc(32, 0x41)]))
+  assert.throws(() => readCliloc(dir), (err) => err.code === 'COMPRESSED')
+})
+
+// ── Drift over the SET ─────────────────────────────────────────────────────
+
+test('hashSources: fingerprints every source, and counts the overlays', () => {
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1, 'a']]))
+  write(dir, `${CUSTOM_DIR}/shard.tsv`, tsv([[2, 'b']]))
+  const fp = hashSources(dir)
+  assert.deepEqual(Object.keys(fp.hashes).sort(), ['clilocs.tsv', 'custom/shard.tsv'])
+  assert.equal(fp.customCount, 1)
+})
+
+test('sameSources: adding or editing an overlay counts as drift', () => {
+  const dir = tmpdir()
+  write(dir, 'clilocs.tsv', tsv([[1, 'a']]))
+  const before = hashSources(dir).hashes
+
+  write(dir, `${CUSTOM_DIR}/shard.tsv`, tsv([[2, 'b']]))
+  const added = hashSources(dir).hashes
+  assert.equal(sameSources(before, added), false, 'a new overlay is drift')
+
+  write(dir, `${CUSTOM_DIR}/shard.tsv`, tsv([[2, 'b changed']]))
+  const edited = hashSources(dir).hashes
+  assert.equal(sameSources(added, edited), false, 'an edited overlay is drift')
+  assert.equal(sameSources(edited, hashSources(dir).hashes), true, 'an untouched set is not')
+})
+
+test('missingSources: a vanished source is detected, an added one is not "missing"', () => {
+  const loaded = { 'clilocs.tsv': 'aaa', 'custom/shard.tsv': 'bbb' }
+  assert.deepEqual(missingSources({ 'clilocs.tsv': 'aaa' }, loaded), ['custom/shard.tsv'])
+  assert.deepEqual(missingSources({ ...loaded, 'custom/new.tsv': 'ccc' }, loaded), [])
+  // Nothing loaded yet (a first import) is not a vanished source.
+  assert.deepEqual(missingSources({ 'clilocs.tsv': 'aaa' }, null), [])
+})

server/test/shardIngest.market.test.js

@@ -0,0 +1,114 @@
+const { test, beforeEach } = require('node:test')
+const assert = require('node:assert/strict')
+
+const shardIngest = require('../src/utils/shardIngest')
+
+// Protocol 3.0 vendor.listing / vendor.listing.remove routing. Same shape as
+// shardIngest.points.test.js: stubbed deps, asserting where the dispatcher sends
+// the frame and whether it is appended to the event log.
+function makeDeps() {
+  const calls = { upserts: [], removes: [], appended: [], broadcast: [] }
+  const noop = async () => {}
+  return {
+    calls,
+    shardEvents: { append: async (row) => { calls.appended.push(row); return true } },
+    shardState: {
+      // Present so any stray routing is a harmless no-op rather than a crash.
+      clearOnline: noop, upsertOnline: noop, setOffline: noop, upsertHouse: noop,
+      addEconomySample: noop, setRuleset: noop, upsertPointsBoard: noop,
+    },
+    shardMarket: {
+      upsertVendor: async (ev) => { calls.upserts.push(ev) },
+      removeVendor: async (serial) => { calls.removes.push(serial) },
+    },
+    shardLinks: { removeByAccount: noop },
+    uoLinkConfig: { recordStatus: noop },
+    broadcast: (ev) => { calls.broadcast.push(ev) },
+    pushDispatch: async () => {},
+    log: { warn() {}, info() {}, error() {} },
+  }
+}
+
+const FRAME = {
+  kind: 'vendor.listing',
+  t: 1000,
+  serial: '0x40001234',
+  shopName: "Darrow's Bargains",
+  ownerSerial: '0x1A2B',
+  ownerName: 'Darrow',
+  location: { map: 'Trammel', x: 1421, y: 1699, z: 0, region: 'Britain', house: "Darrow's Villa" },
+  count: 2,
+  total: 2,
+  truncated: false,
+  items: [
+    { serial: '0x40012ABC', itemId: 3922, hue: 0, amount: 1, price: 25000, name: null, cliloc: 1023721 },
+    { serial: '0x40012ABD', itemId: 7026, hue: 1157, amount: 3, price: 500, name: 'a shard sigil', cliloc: 1041243 },
+  ],
+}
+
+beforeEach(() => shardIngest.reset())
+
+test('vendor.listing routes to the market model with the whole frame', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest(FRAME, deps)
+  assert.equal(deps.calls.upserts.length, 1)
+  const stored = deps.calls.upserts[0]
+  assert.equal(stored.serial, '0x40001234')
+  assert.equal(stored.location.region, 'Britain')
+  assert.equal(stored.items.length, 2)
+})
+
+test('vendor.listing.remove routes to removeVendor with the serial', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest({ kind: 'vendor.listing.remove', t: 2000, serial: '0x40001234' }, deps)
+  assert.deepEqual(deps.calls.removes, ['0x40001234'])
+  assert.equal(deps.calls.upserts.length, 0)
+})
+
+// The market IS the state. One frame carries up to 250 listings and the sweep
+// re-emits a shop on any price change, so logging would turn shard_events into a
+// price history nobody reads — the strongest case of the three v3 kinds.
+test('neither market kind is appended to the event log', async () => {
+  const deps = makeDeps()
+  const a = await shardIngest.ingest(FRAME, deps)
+  const b = await shardIngest.ingest({ kind: 'vendor.listing.remove', serial: '0x40001234' }, deps)
+  assert.equal(a.logged, false)
+  assert.equal(b.logged, false)
+  assert.equal(deps.calls.appended.length, 0)
+  assert.equal(shardIngest.LOGGED_KINDS.has('vendor.listing'), false)
+  assert.equal(shardIngest.LOGGED_KINDS.has('vendor.listing.remove'), false)
+})
+
+// Broadcast is unconditional at this layer — whether it actually reaches anyone
+// is shardBroadcast's call, and the market feature ships with its stream off.
+test('vendor.listing is handed to the broadcaster', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest(FRAME, deps)
+  assert.equal(deps.calls.broadcast.length, 1)
+  assert.equal(deps.calls.broadcast[0].kind, 'vendor.listing')
+})
+
+test('a backfilled vendor.listing still stores but does not broadcast', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest(FRAME, { ...deps, fromBackfill: true })
+  assert.equal(deps.calls.upserts.length, 1)
+  assert.equal(deps.calls.broadcast.length, 0)
+})
+
+// The reconnect backfill replays the whole index through this path, so a single
+// bad vendor must not abort it.
+test('an upsertVendor failure does not throw or stop the broadcast', async () => {
+  const deps = makeDeps()
+  deps.shardMarket.upsertVendor = async () => { throw new Error('db down') }
+  const r = await shardIngest.ingest(FRAME, deps)
+  assert.equal(r.logged, false)
+  assert.equal(deps.calls.broadcast.length, 1)
+})
+
+// Each vendor is its own row; the frame is authoritative for that vendor only.
+test('two vendors are stored independently', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest(FRAME, deps)
+  await shardIngest.ingest({ ...FRAME, serial: '0x40009999', shopName: 'Second Shop' }, deps)
+  assert.deepEqual(deps.calls.upserts.map((v) => v.serial), ['0x40001234', '0x40009999'])
+})

server/test/shardIngest.ruleset.test.js

@@ -96,3 +96,66 @@ test('a setRuleset failure does not throw or stop the broadcast', async () => {
   assert.equal(r.logged, false)
   assert.equal(deps.calls.broadcast.length, 1)
 })
+
+// ── Shard name fallback ────────────────────────────────────────────────────
+//
+// ServUO ships Server.cfg with `Name=My Shard`. An operator who never edited it
+// publishes that verbatim, which says "unnamed" rather than naming anything — so
+// the site answers with its own instance name instead of printing the stock
+// default under a header carrying the real one.
+//
+// Applied at INGEST, not on read, because world.ruleset is also broadcast live:
+// the same object goes to the SSE fan-out, so a read-time fix would be undone by
+// the next reconnect's frame. These tests assert both halves.
+
+function withSettings(deps, name) {
+  return { ...deps, settings: { getInstanceName: async () => name } }
+}
+
+test('the stock ServUO shard name is replaced with the instance name', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest({ ...FRAME, shard: 'My Shard' }, withSettings(deps, 'UOMysticmoon'))
+  assert.equal(deps.calls.rulesetSet[0].shard, 'UOMysticmoon')
+})
+
+test('the substituted name reaches the live broadcast, not just the store', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest({ ...FRAME, shard: 'My Shard' }, withSettings(deps, 'UOMysticmoon'))
+  assert.equal(deps.calls.broadcast.length, 1)
+  assert.equal(deps.calls.broadcast[0].shard, 'UOMysticmoon')
+})
+
+test('a missing or blank shard name gets the same treatment', async () => {
+  for (const shard of [undefined, null, '', '   ']) {
+    const deps = makeDeps()
+    await shardIngest.ingest({ ...FRAME, shard }, withSettings(deps, 'UOMysticmoon'))
+    assert.equal(deps.calls.rulesetSet[0].shard, 'UOMysticmoon')
+  }
+})
+
+// The match is on the whole value, case- and padding-insensitive. A shard that
+// deliberately calls itself "My Shard Reborn" has named itself and keeps it.
+test('a real name that merely contains the stock one is left alone', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest({ ...FRAME, shard: 'My Shard Reborn' }, withSettings(deps, 'UOMysticmoon'))
+  assert.equal(deps.calls.rulesetSet[0].shard, 'My Shard Reborn')
+
+  const padded = makeDeps()
+  await shardIngest.ingest({ ...FRAME, shard: '  MY SHARD  ' }, withSettings(padded, 'UOMysticmoon'))
+  assert.equal(padded.calls.rulesetSet[0].shard, 'UOMysticmoon')
+})
+
+test('a shard that named itself is never overridden by the brand', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest(FRAME, withSettings(deps, 'Some Other Brand'))
+  assert.equal(deps.calls.rulesetSet[0].shard, 'UOMysticmoon')
+})
+
+// The settings read is a DB call on a path that must never fail ingest.
+test('a settings read failure leaves the frame storable', async () => {
+  const deps = makeDeps()
+  const boom = { ...deps, settings: { getInstanceName: async () => { throw new Error('db down') } } }
+  await shardIngest.ingest({ ...FRAME, shard: 'My Shard' }, boom)
+  assert.equal(deps.calls.rulesetSet.length, 1)
+  assert.equal(deps.calls.rulesetSet[0].shard, 'My Shard')
+})

server/test/shardMarket.model.test.js

@@ -0,0 +1,260 @@
+// Point the DB at a closed port BEFORE requiring anything that builds a pool.
+// Nothing here reaches the database: these are the model's PURE parts — the
+// flatten/shape rules the frame passes through on the way in and out — plus the
+// visibility projection over the shapes they produce.
+process.env.DB_HOST = '127.0.0.1'
+process.env.DB_PORT = '59999'
+
+const { test, after } = require('node:test')
+const assert = require('node:assert/strict')
+
+const market = require('../src/model/shardMarket/shardMarket.model')
+const clilocs = require('../src/model/shardClilocs/shardClilocs.model')
+const clilocDb = require('../src/model/shardClilocs/shardClilocs.db')
+const visibility = require('../src/utils/shardVisibility')
+const db = require('../src/utils/db')
+
+after(() => db.close())
+
+// Stand in for the cliloc table. Without this each unresolved lookup waits out
+// the pool's 10s acquire timeout against the dead port — the model swallows the
+// failure exactly as it would in production (an operator who never converted a
+// cliloc file is in a supported state), so the RESULT is the same either way;
+// this only stops the suite spending half a minute proving it.
+const TABLE = new Map([[1023721, 'quarter staff']])
+clilocDb.lookup = async (numbers) =>
+  numbers.filter((n) => TABLE.has(n)).map((n) => ({ number: n, text: TABLE.get(n) }))
+
+const FRAME = {
+  kind: 'vendor.listing',
+  t: 1000,
+  serial: '0x40001234',
+  shopName: "Darrow's Bargains",
+  ownerSerial: '0x1A2B',
+  ownerName: 'Darrow',
+  location: { map: 'Trammel', x: 1421, y: 1699, z: 0, region: 'Britain', house: "Darrow's Villa" },
+  count: 2,
+  total: 2,
+  truncated: false,
+  items: [],
+}
+
+// ── flattenFrame ───────────────────────────────────────────────────────────
+
+test('flattenFrame lifts the nested location into columns', () => {
+  const v = market.flattenFrame(FRAME)
+  assert.equal(v.serial, '0x40001234')
+  assert.equal(v.map, 'Trammel')
+  assert.equal(v.x, 1421)
+  assert.equal(v.region, 'Britain')
+  assert.equal(v.house, "Darrow's Villa")
+})
+
+// A vendor standing in the street has no house, and a frame from an older plugin
+// may have no location at all. Neither is an error.
+test('flattenFrame tolerates a missing location entirely', () => {
+  const v = market.flattenFrame({ serial: '0x1', shopName: null })
+  assert.equal(v.map, null)
+  assert.equal(v.x, null)
+  assert.equal(v.region, null)
+  assert.equal(v.house, null)
+})
+
+// `total` is what the SHOP holds; `count` is what the frame carried. A truncated
+// shop must not report its published slice as its size, or the page says
+// "showing 250 of 250" for a vendor holding three thousand stacks.
+test('flattenFrame keeps the shop total separate from the published count', () => {
+  const v = market.flattenFrame({ ...FRAME, count: 250, total: 3104, truncated: true })
+  assert.equal(v.itemTotal, 3104)
+  assert.equal(v.truncated, true)
+})
+
+// An older plugin sends no `total`. Falling back to `count` is right — it is the
+// only number available and it is correct whenever nothing was truncated.
+test('flattenFrame falls back to count when total is absent', () => {
+  const v = market.flattenFrame({ ...FRAME, count: 7, total: undefined })
+  assert.equal(v.itemTotal, 7)
+})
+
+test('flattenFrame clips over-length strings rather than letting the insert fail', () => {
+  const v = market.flattenFrame({ ...FRAME, ownerName: 'x'.repeat(200) })
+  assert.equal(v.ownerName.length, 64)
+})
+
+// ── shapeItems ─────────────────────────────────────────────────────────────
+//
+// resolveMany never throws and, with no cliloc table reachable, resolves nothing
+// — which is exactly the state of a shard whose operator never converted one, so
+// these run against the real function rather than a stub.
+
+test('shapeItems prefers the item\'s literal name over its cliloc', async () => {
+  const items = await market.shapeItems({
+    items: [{ serial: '0x1', itemId: 3922, price: 100, name: 'a shard sigil', cliloc: 1023721 }],
+  })
+  assert.equal(items[0].displayName, 'a shard sigil')
+  // The cliloc is kept regardless, so a later import can still re-resolve it.
+  assert.equal(items[0].cliloc, 1023721)
+})
+
+test('shapeItems resolves the cliloc when the item has no literal name', async () => {
+  const items = await market.shapeItems({
+    items: [{ serial: '0x1', itemId: 3922, price: 100, name: null, cliloc: 1023721 }],
+  })
+  assert.equal(items[0].displayName, 'quarter staff')
+})
+
+// The supported state for a shard whose operator never converted a cliloc file:
+// no name, not a fabricated one. Clients render the item id, exactly as they did
+// before the table existed.
+test('shapeItems leaves displayName null for an unknown cliloc', async () => {
+  const items = await market.shapeItems({
+    items: [{ serial: '0x1', itemId: 3922, price: 100, name: null, cliloc: 9999999 }],
+  })
+  assert.equal(items[0].displayName, null)
+})
+
+// Unpriced rows are inventory, not listings. The shard drops them too; enforcing
+// it here as well means a plugin that stops doing so cannot put un-buyable rows
+// on the market page.
+test('shapeItems drops unpriced listings', async () => {
+  const items = await market.shapeItems({
+    items: [
+      { serial: '0x1', itemId: 1, price: 0 },
+      { serial: '0x2', itemId: 2, price: -1 },
+      { serial: '0x3', itemId: 3, price: 5 },
+    ],
+  })
+  assert.deepEqual(items.map((i) => i.serial), ['0x3'])
+})
+
+test('shapeItems caps a pathological frame', async () => {
+  const many = Array.from({ length: market.MAX_ITEMS_PER_VENDOR + 50 }, (_, i) => ({
+    serial: `0x${i}`,
+    itemId: 1,
+    price: 1,
+  }))
+  const items = await market.shapeItems({ items: many })
+  assert.equal(items.length, market.MAX_ITEMS_PER_VENDOR)
+})
+
+test('shapeItems tolerates a frame with no items array', async () => {
+  assert.deepEqual(await market.shapeItems({}), [])
+})
+
+// ── Visibility projection ──────────────────────────────────────────────────
+//
+// The regression that matters. Part A pre-wired `market.ownerName` and
+// `market.location` before the frame existed, and the sibling rule it pre-wired
+// for leaderboards (`characterName`) turned out to be INERT because projectValue
+// matches literal JSON keys. These assert the market rules actually bite — on the
+// read model AND on the wire frame, which is why both carry the same key names.
+
+const config = visibility.compileDefaults()
+
+const listing = market.shapeListing({
+  serial: '0x40012ABC',
+  item_id: 3922,
+  hue: 0,
+  amount: 1,
+  price: 25000,
+  name: null,
+  cliloc: 1023721,
+  display_name: 'quarter staff',
+  child: 0,
+  vendor_serial: '0x40001234',
+  shop_name: "Darrow's Bargains",
+  owner_serial: '0x1A2B',
+  owner_name: 'Darrow',
+  map: 'Trammel',
+  x: 1421,
+  y: 1699,
+  z: 0,
+  region: 'Britain',
+  house: "Darrow's Villa",
+  updated_at: new Date(0),
+})
+
+test('market defaults expose owner and location (they are already public in game)', () => {
+  const out = visibility.projectFeature('market', listing, 'anonymous', config)
+  assert.equal(out.vendor.ownerName, 'Darrow')
+  assert.equal(out.vendor.location.region, 'Britain')
+})
+
+test('tightening market.ownerName hides it from below that rung', () => {
+  const tightened = { ...config, market: { ...config.market, fields: { ...config.market.fields, ownerName: 'staff' } } }
+  const anon = visibility.projectFeature('market', listing, 'anonymous', tightened)
+  const staff = visibility.projectFeature('market', listing, 'staff', tightened)
+  assert.equal('ownerName' in anon.vendor, false)
+  assert.equal(staff.vendor.ownerName, 'Darrow')
+  // The shop name is a separate field and must survive — hiding the owner is not
+  // the same as hiding the shop.
+  assert.equal(anon.vendor.shopName, "Darrow's Bargains")
+})
+
+// The whole reason `location` is one nested object: a single rule has to take the
+// facet, the coordinates, the region and the house together. Five flat keys would
+// be five rules that drift apart.
+test('tightening market.location hides the whole location object at once', () => {
+  const tightened = { ...config, market: { ...config.market, fields: { ...config.market.fields, location: 'player' } } }
+  const anon = visibility.projectFeature('market', listing, 'anonymous', tightened)
+  const player = visibility.projectFeature('market', listing, 'player', tightened)
+  assert.equal('location' in anon.vendor, false)
+  assert.equal(player.vendor.location.map, 'Trammel')
+})
+
+// The same rules must bite on the LIVE frame, not just the stored read model —
+// the market's SSE stream is off by default but an admin can turn it on, and a
+// field rule that only worked on one of the two paths is exactly the leak §3.6.1
+// records.
+test('the same rules apply to the raw vendor.listing frame', () => {
+  const tightened = { ...config, market: { ...config.market, fields: { ...config.market.fields, ownerName: 'admin', location: 'admin' } } }
+  const out = visibility.projectFeature('market', FRAME, 'anonymous', tightened)
+  assert.equal('ownerName' in out, false)
+  assert.equal('location' in out, false)
+  assert.equal(out.shopName, "Darrow's Bargains")
+})
+
+// Rule 1 is not configurable and does not depend on the market rules at all: a
+// frame that somehow carried an account name must never publish it.
+test('acct and webId are stripped from a market payload regardless of config', () => {
+  const out = visibility.projectFeature(
+    'market',
+    { serial: '0x1', ownerAcct: 'darrow', webId: '42', shopName: 'Shop' },
+    'staff',
+    config,
+  )
+  assert.equal('ownerAcct' in out, false)
+  assert.equal('webId' in out, false)
+  assert.equal(out.shopName, 'Shop')
+})
+
+// Both kinds must be attributed to a feature, or rule 2 makes them admin-only by
+// omission — which would be a silent failure rather than a loud one.
+test('both market kinds are mapped to the market feature', () => {
+  assert.equal(visibility.KIND_FEATURE.get('vendor.listing'), 'market')
+  assert.equal(visibility.KIND_FEATURE.get('vendor.listing.remove'), 'market')
+})
+
+// The market's live firehose is off by default (a page of whole vendor
+// inventories is the site's biggest bandwidth item and no page needs it live),
+// but the REST reads are unaffected — which is what `visibleKinds` ignoring the
+// stream flag encodes.
+test('market kinds are stream-suppressed by default but still readable', () => {
+  assert.equal(visibility.DEFAULT_STREAM_OFF.has('market'), true)
+  assert.equal(visibility.kindVisibleTo('vendor.listing', 'anonymous', config), false)
+  assert.equal(visibility.PUBLIC_KINDS.has('vendor.listing'), false)
+  assert.ok(visibility.visibleKinds('anonymous', config).includes('vendor.listing'))
+})
+
+test('an admin who enables the stream gets the frames', () => {
+  const on = { ...config, market: { ...config.market, stream: true } }
+  assert.equal(visibility.kindVisibleTo('vendor.listing', 'anonymous', on), true)
+})
+
+// Guards the stub above against silently doing nothing: if the model stopped
+// going through db.lookup, every shapeItems assertion would still "pass" by
+// resolving nothing, which is also what a real miss looks like.
+test('the cliloc resolver is the path shapeItems resolves through', async () => {
+  const found = await clilocs.resolveMany([1023721])
+  assert.equal(found.get(1023721), 'quarter staff')
+})

server/tools/cliloc-export/Program.cs

@@ -0,0 +1,140 @@
+// Cliloc export — converts a modern client's COMPRESSED Cliloc.enu into the
+// plain format the website can read (docs/website/CLILOCS.md).
+//
+// Why this exists at all: every current UO client ships its cliloc files in the
+// compressed "Mythic" format — the first DWORD's high byte is 0x8E — and the
+// plain layout the website parses is what those files looked like before that
+// change. Decompressing is a bit-level inverse-BWT coder that the site has no
+// business carrying at runtime, and ServUO's own bundled `Ultima.StringList`
+// cannot read it either (which is why `VendorSearch.GetItemName` is already
+// inert on such a shard, and why the shard cannot supply names instead).
+//
+// So the conversion happens ONCE, here, against a decompressor that already
+// exists and is maintained: UOFiddler's `Ultima.dll`.
+//
+// ── Why reflection rather than a project reference ────────────────────────
+//
+// UOFiddler ships as net10.0. Referencing it from a project built by an older
+// SDK fails at COMPILE time with CS1705 ("uses System.Runtime 10.0 which has a
+// higher version than referenced assembly"). Loading it reflectively moves that
+// question to run time, where `RollForward: LatestMajor` answers it — so this
+// builds on whatever SDK an operator happens to have and runs on the newest
+// runtime installed.
+//
+// ── Why not StringList.SaveStringList ────────────────────────────────────
+//
+// It looks like exactly the right method and it is not: it RE-COMPRESSES on
+// save, because its purpose is round-tripping a file back into the client. The
+// output is byte-identical to the compressed input. The plain records below are
+// written by hand for that reason.
+//
+// Usage:
+//   dotnet run -- <Ultima.dll> <Cliloc.enu> <output> [--tsv]
+//
+// Nothing produced by this tool is committed. See docs/website/CLILOCS.md.
+
+using System;
+using System.Collections;
+using System.IO;
+using System.Reflection;
+using System.Text;
+
+internal static class Program
+{
+    private static int Main(string[] args)
+    {
+        if (args.Length < 3)
+        {
+            Console.Error.WriteLine("usage: clilocexport <path-to-Ultima.dll> <cliloc-file> <output-file> [--tsv]");
+            Console.Error.WriteLine("  Ultima.dll ships with UOFiddler (https://github.com/polserver/UOFiddler).");
+            return 2;
+        }
+
+        var (ultimaDll, input, output) = (args[0], args[1], args[2]);
+        var asTsv = Array.IndexOf(args, "--tsv") >= 0;
+
+        // The language code only names the file when StringList resolves the path
+        // itself; here the path is explicit, so it is cosmetic.
+        var language = Path.GetExtension(input).TrimStart('.');
+        if (string.IsNullOrWhiteSpace(language)) language = "enu";
+
+        var assembly = Assembly.LoadFrom(Path.GetFullPath(ultimaDll));
+        var stringListType = assembly.GetType("Ultima.StringList")
+            ?? throw new InvalidOperationException("Ultima.StringList not found — is that really UOFiddler's Ultima.dll?");
+
+        // (language, path, decompress). `decompress: true` is the whole point;
+        // the loader falls back to a plain read on its own if the file turns out
+        // not to be compressed, so an already-converted file passes through.
+        var ctor = stringListType.GetConstructor(new[] { typeof(string), typeof(string), typeof(bool) })
+            ?? throw new InvalidOperationException("Unexpected Ultima.StringList API — this tool targets UOFiddler 4.21+.");
+
+        var stringList = ctor.Invoke(new object[] { language, Path.GetFullPath(input), true });
+
+        // A partial parse is reported rather than thrown. Surfacing it matters:
+        // the output would otherwise be a quietly short table, which is exactly
+        // the failure mode the website's parser refuses to import.
+        var warning = stringListType.GetProperty("LoadWarning")?.GetValue(stringList) as string;
+        if (!string.IsNullOrWhiteSpace(warning)) Console.Error.WriteLine("warning: " + warning);
+
+        var entries = (IEnumerable)stringListType.GetProperty("Entries")!.GetValue(stringList)!;
+        var entryType = assembly.GetType("Ultima.StringEntry")!;
+        var numberProp = entryType.GetProperty("Number")!;
+        var textProp = entryType.GetProperty("Text")!;
+        var flagProp = entryType.GetProperty("Flag")!;
+
+        int written = 0, skipped = 0, maxBytes = 0;
+
+        if (asTsv)
+        {
+            using var writer = new StreamWriter(output, false, new UTF8Encoding(false));
+            foreach (var entry in entries)
+            {
+                var number = (int)numberProp.GetValue(entry)!;
+                var text = (string?)textProp.GetValue(entry) ?? "";
+                maxBytes = Math.Max(maxBytes, Encoding.UTF8.GetByteCount(text));
+                // A tab or newline inside a cliloc string would break the row.
+                // Neither occurs in real tables, but silently emitting a broken
+                // file is worse than collapsing the whitespace.
+                writer.WriteLine($"{number}\t{text.Replace('\t', ' ').Replace('\r', ' ').Replace('\n', ' ')}");
+                written++;
+            }
+        }
+        else
+        {
+            using var stream = new FileStream(output, FileMode.Create, FileAccess.Write);
+            using var binary = new BinaryWriter(stream);
+            binary.Write(2);        // int32 — the plain-format version marker
+            binary.Write((short)1); // int16 — language marker
+
+            foreach (var entry in entries)
+            {
+                var number = (int)numberProp.GetValue(entry)!;
+                var text = (string?)textProp.GetValue(entry) ?? "";
+                var flag = Convert.ToByte(Convert.ToInt32(flagProp.GetValue(entry)));
+
+                var utf8 = Encoding.UTF8.GetBytes(text);
+                maxBytes = Math.Max(maxBytes, utf8.Length);
+
+                // The length field is 16 bits. Real tables peak around 12 KB, so
+                // this has never fired — but writing a truncated length would
+                // corrupt every record after it, so an oversize entry is dropped
+                // and counted instead.
+                if (utf8.Length > ushort.MaxValue) { skipped++; continue; }
+
+                binary.Write(number);
+                binary.Write(flag);
+                binary.Write((ushort)utf8.Length);
+                binary.Write(utf8);
+                written++;
+            }
+        }
+
+        Console.WriteLine($"wrote {written} entries to {output} (maxTextBytes={maxBytes}, skippedOversize={skipped})");
+        if (written == 0)
+        {
+            Console.Error.WriteLine("no entries were written — is that a cliloc file?");
+            return 1;
+        }
+        return 0;
+    }
+}

server/tools/cliloc-export/README.md

@@ -0,0 +1,64 @@
+# cliloc-export
+
+Converts a UO client's **compressed** `Cliloc.enu` into the plain format the
+website can read.
+
+This is a one-off operator utility, not part of the website build. Nothing in the
+Node application references it and CI never touches it. Full background —
+including why the conversion is necessary at all — is in
+[`docs/website/CLILOCS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/edge/website/CLILOCS.md).
+
+## The short version
+
+Every current UO client ships its cliloc files in the compressed "Mythic"
+container (the first DWORD's high byte is `0x8E`). The website parses the plain
+layout those files used before that change. Decompressing is an inverse-BWT coder
+that the site has no business carrying at runtime — and ServUO's own bundled
+`Ultima.StringList` cannot read it either, so the shard cannot supply item names
+on our behalf.
+
+So: convert once, here, using a decompressor that already exists and is already
+maintained — [UOFiddler](https://github.com/polserver/UOFiddler)'s `Ultima.dll`.
+
+## Usage
+
+```bash
+dotnet build -c Release
+
+# plain binary (recommended — exact)
+dotnet run -- "<UOFiddler>/Ultima.dll" "<UO client>/Cliloc.enu" /srv/uo-data/clilocs.plain
+
+# tab-delimited text (convenient; does not preserve leading/trailing whitespace)
+dotnet run -- "<UOFiddler>/Ultima.dll" "<UO client>/Cliloc.enu" /srv/uo-data/clilocs.tsv --tsv
+```
+
+Then point the site at the output: **Admin → Shard → cliloc path**, or the
+`UO_CLIENT_PATH` environment variable. The setting wins over the environment.
+
+Expected output for a stock English client:
+
+```
+wrote 123490 entries to /srv/uo-data/clilocs.plain (maxTextBytes=12150, skippedOversize=0)
+```
+
+The site stores ~67,500 of those — roughly half a cliloc table is empty strings
+for ids the client reserves and never uses.
+
+## Two implementation notes worth keeping
+
+**`Ultima.dll` is loaded reflectively, not referenced.** UOFiddler ships as
+net10.0; a project reference from an older SDK fails at *compile* time with
+CS1705. Reflection moves that to run time, where `RollForward: LatestMajor`
+answers it — so this builds on whatever SDK you have and runs on the newest
+runtime installed.
+
+**`StringList.SaveStringList` is not the export path**, despite looking exactly
+like it. It *re-compresses* on save, because its purpose is round-tripping a file
+back into the client — its output is byte-identical to its input. The plain
+records are written by hand for that reason.
+
+## Output is never committed
+
+UO's strings are EA's. `.gitignore` covers this project's build output and the
+conventional in-repo output location, but the supported arrangement is a path
+**outside** the repository entirely.

server/tools/cliloc-export/clilocexport.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!--
+    A one-off operator utility, not part of the website build. Nothing in the
+    Node application references it and CI never touches it; it exists so an
+    operator can convert their client's compressed cliloc file without clicking
+    through a GUI. See README.md and docs/website/CLILOCS.md.
+
+    TargetFramework is deliberately net8.0 — the OLDEST runtime this needs — so
+    it builds on whatever SDK an operator already has. UOFiddler's Ultima.dll is
+    net10.0 and is loaded reflectively at run time rather than referenced, which
+    is what keeps that version difference from being a compile error; the
+    RollForward below is what lets the resulting binary run on it.
+  -->
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <AssemblyName>clilocexport</AssemblyName>
+    <RootNamespace>ClilocExport</RootNamespace>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>disable</ImplicitUsings>
+    <RollForward>LatestMajor</RollForward>
+    <InvariantGlobalization>true</InvariantGlobalization>
+  </PropertyGroup>
+
+</Project>