@globalbrain/sefirot 4.50.0 → 4.52.0

package/lib/blocks/lens/components/LensCatalog.vue

@@ -7,11 +7,13 @@ import { useMutation, useQuery } from '../../../composables/Api'
 import { useLang, useTrans } from '../../../composables/Lang'
 import { usePower } from '../../../composables/Power'
 import { useSnackbars } from '../../../stores/Snackbars'
+import { day } from '../../../support/Day'
 import { type FieldData } from '../FieldData'
 import { type LensQuery, type LensQuerySort } from '../LensQuery'
 import { type LensResult } from '../LensResult'
 import { useCatalogUrlQuerySync } from '../composables/CatalogUrlQuerySync'
 import { provideLensEdit } from '../composables/LensEdit'
+import { extractServerMessage, isAuthError } from '../validation/ServerErrors'
 import LensCatalogControl, { type FilterPresets } from './LensCatalogControl.vue'
 import LensCatalogFooter from './LensCatalogFooter.vue'
 import LensCatalogStateFilter from './LensCatalogStateFilter.vue'
@@ -147,24 +149,47 @@ export interface Props {
   // *custom* `indexField`, however, must be listed in `select` explicitly (an
   // empty/default `select` drops it from the rendered columns, leaving the rows
   // with no opener).
-  editable?: boolean
-
-  // Whether new records can be created (enables create mode in the sheet
-  // and the exposed `openCreate()` method). Requires `editable`.
+  //
+  // Turning this on also enables `creatable`, `deletable`, and `inlineEditable`
+  // by default; pass `false` to any of them to opt out.
+  //
+  // Pass a predicate `(record) => boolean` instead of `true` to allow editing
+  // only some rows (e.g. from a per-record policy): the inline affordance and
+  // the sheet's per-field edit are hidden for the rows it rejects.
+  editable?: boolean | ((record: Record<string, any>) => boolean)
+
+  // Whether records can be deleted from the sheet. Defaults to enabled for an
+  // editable catalog. Pass `false` to hide the delete button entirely, or a
+  // predicate `(record) => boolean` to allow deleting only some rows (e.g. from
+  // a per-record policy). Delete is reachable only through the sheet, so this
+  // has no effect unless the catalog is `editable`.
+  deletable?: boolean | ((record: Record<string, any>) => boolean)
+
+  // Whether new records can be created (enables create mode in the sheet and
+  // the exposed `openCreate()` method). Defaults to enabled when the catalog is
+  // `editable`; pass `false` to disable.
   creatable?: boolean
 
   // Width of the record sheet (any valid CSS width). Defaults to `480px`.
   sheetWidth?: string
 
-  // Enable inline editing directly in the table: cells for `showOnUpdate`
-  // fields gain a hover edit affordance that opens an inline editor. Requires
-  // `editable` (it reuses the same CRUD edit context as the sheet).
-  inlineEdit?: boolean
+  // Enable inline editing directly in the table: cells for `showOnUpdate` fields
+  // gain a hover edit affordance that opens an inline editor (reusing the sheet's
+  // CRUD edit context). Defaults to enabled when the catalog is `editable`; pass
+  // `false` to restrict editing to the record sheet.
+  inlineEditable?: boolean
 }
 
 const props = withDefaults(defineProps<Props>(), {
   canFilter: true,
-  canSort: true
+  canSort: true,
+  // Default these on so an editable catalog gets create / delete / inline edit
+  // without opting in to each. A boolean prop can't tell "omitted" from `false`
+  // (Vue casts an absent boolean to `false`), so they default on here and the
+  // resolvers below gate them on `editable`; pass the prop `false` to opt out.
+  creatable: true,
+  deletable: true,
+  inlineEditable: true
 })
 
 const selected = defineModel<any[]>('selected')
@@ -182,16 +207,32 @@ const emit = defineEmits<{
 
 const { t } = useTrans({
   en: {
-    write_error: 'Your latest changes might not be saved. Please reload the page, and contact support if the problem persists.',
-    busy_warning: 'A save is still in progress — changes you make now may not be saved.',
+    save_failed: (label: string) => `We couldn’t save “${label}”.`,
+    save_failed_anon: 'We couldn’t save your change.',
+    delete_failed: (label: string) => `We couldn’t delete “${label}”.`,
+    delete_failed_anon: 'We couldn’t delete this record.',
+    write_error_reload: 'Please reload and try again.',
+    write_error_recover: 'Please reload to see the latest.',
+    busy_warning: 'Still saving — please wait a moment before changing the view.',
     refresh_text: 'Newer results are available.',
-    refresh_action: 'Refresh'
+    refresh_failed_text: 'Some changes couldn’t be saved. Refresh to restore the latest values.',
+    refresh_action: 'Refresh',
+    search_error: 'We couldn’t load the records.',
+    search_retry: 'Try again'
   },
   ja: {
-    write_error: '最新の変更が保存されていない可能性があります。ページを再読み込みし、問題が解決しない場合はサポートにお問い合わせください。',
-    busy_warning: '保存処理中です。ここでの変更は保存されない可能性があります。',
+    save_failed: (label: string) => `「${label}」を保存できませんでした。`,
+    save_failed_anon: '変更を保存できませんでした。',
+    delete_failed: (label: string) => `「${label}」を削除できませんでした。`,
+    delete_failed_anon: 'レコードを削除できませんでした。',
+    write_error_reload: 'ページを再読み込みして、もう一度お試しください。',
+    write_error_recover: 'ページを再読み込みして最新の状態をご確認ください。',
+    busy_warning: '保存中です。表示を変更する前に少しお待ちください。',
     refresh_text: '新しい結果があります。',
-    refresh_action: '更新'
+    refresh_failed_text: '保存できなかった変更があります。更新して最新の値に戻してください。',
+    refresh_action: '更新',
+    search_error: 'レコードを読み込めませんでした。',
+    search_retry: '再試行'
   }
 })
 
@@ -211,9 +252,12 @@ const hasInitialResults = ref(false)
 
 // A fresher server result fetched after the optimistic writes settled, awaiting
 // the user's explicit opt-in via the refresh button — never auto-applied (that
-// would momentarily revert the optimistic edits to stale data). Declared here
-// (ahead of the query handlers that clear it) so they can reference it.
-const latestState = ref<LensResult | null>(null)
+// would momentarily revert the optimistic edits to stale data). `fromError` marks
+// a stash produced by a *failed* write (the optimistic value diverged from the
+// canonical one), so the banner can explain it's a recovery rather than just
+// newer data. Declared here (ahead of the query handlers that clear it) so they
+// can reference it.
+const latestState = ref<{ result: LensResult; fromError: boolean } | null>(null)
 
 // Count of optimistic background writes currently in flight. Declared here
 // (ahead of the debounced refetch that consults it) so a queued refetch can bail
@@ -318,13 +362,79 @@ const { data: result, execute: refresh, loading } = useQuery(async (http) => {
   prevFetchResult = res
 
   return res
-})
+}, { immediate: false })
 
 // Keep `currentResult` pointing at the shown result. The reference changes only
 // on a wholesale replace; optimistic in-place edits keep the same object, so this
 // mirror always reflects them.
 watch(result, (r) => { currentResult = r ?? undefined }, { immediate: true })
 
+// Whether the most recent table search (initial load or a user-driven re-search)
+// failed. A failed fetch otherwise leaves the previous rows on screen with the
+// controls re-enabled — indistinguishable from the new query legitimately
+// returning them — so the list shows an inline error + retry instead.
+const searchError = ref(false)
+
+// Monotonic token so only the latest search may raise the error flag: with the
+// slow backend two searches can overlap, and an older one failing *after* a newer
+// one succeeded must not flash an error over the good rows now on screen.
+let searchRunSeq = 0
+
+// Run the main table search, tracking whether it failed. Drives the initial load
+// (the query's `immediate` is off so this owns it) and every `doRefresh`.
+async function runSearch(): Promise<void> {
+  const seq = ++searchRunSeq
+  // Snapshot `searchToken` too: a write / create / forced refresh / index-field
+  // change bumps it to supersede an in-flight search (so even on success the
+  // fetcher discards that search's rows and returns the current result instead).
+  // Such a superseded run must neither raise the error (its rejection is for a
+  // request we already decided to drop) nor clear it (its "success" is the stale
+  // current result, not the requested rows) — the follow-up (the write's
+  // reconcile, the forced result) settles the state instead.
+  const token = searchToken
+  try {
+    await refresh()
+    // Clear only on the latest, non-superseded run's success — an older run
+    // resolving late must not wipe a newer run's error, and a write-invalidated
+    // run resolving with the current result must not dismiss the error over rows
+    // that aren't the requested ones. Not cleared up front either: keeping the
+    // error visible until a retry actually succeeds avoids flashing the previous
+    // query's (interactable) rows back on screen mid-retry.
+    if (seq === searchRunSeq && token === searchToken) {
+      searchError.value = false
+      // These fresh rows for the current query supersede any pending recovery
+      // banner (a reconcile stash), so its button can't later overwrite them with
+      // an older snapshot. Query-change refetches already drop it; the retry path
+      // (doRefresh, which keeps the banner for a failed retry) doesn't, so a
+      // successful retry must clear it here.
+      latestState.value = null
+    }
+  } catch (e) {
+    // Auth / session-expiry (401 / 419) must reach the app's re-auth flow, not be
+    // parked on the inline retry state — matches the download / filter paths and
+    // the ServerErrors contract. Rethrow so the rejection propagates to the global
+    // handler as it did before this wrapper caught it.
+    if (isAuthError(e)) {
+      throw e
+    }
+    if (seq === searchRunSeq && token === searchToken) {
+      searchError.value = true
+    }
+  }
+}
+
+onMounted(runSearch)
+
+// When a search fails, the error state replaces the table but the control bar —
+// including its selected-actions (bulk) slot — stays mounted. Clear any selection
+// on entering the error so the user can't act on now-hidden rows from the previous
+// result while the UI says the current query failed.
+watch(searchError, (err) => {
+  if (err && selected.value?.length) {
+    selected.value = []
+  }
+})
+
 const doRefresh = useDebounceFn(() => {
   // A write or a blocking create may have started during the debounce window: the
   // busy lock guards the query handlers at click time, but not this deferred
@@ -334,7 +444,7 @@ const doRefresh = useDebounceFn(() => {
   // (Deliberate refreshes go through `forceRefresh`, which calls `refresh`
   // directly to bypass this guard.)
   if (pendingWrites.value > 0 || creating.value) { return }
-  return refresh()
+  return runSearch()
 }, 50)
 
 if (props.urlSync) {
@@ -353,7 +463,14 @@ if (props.urlSync) {
 }
 
 const _showEmptyState = computed(() => {
-  return props.showEmptyState && !hasInitialResults.value && result.value?.data.length === 0
+  // Exclude `searchError`: when a re-search fails the result still holds the
+  // previous (possibly zero-row) data, which would otherwise keep the empty-state
+  // slot showing — and it sits in this branch's `v-else`, so the inline error +
+  // retry would never render. Yield to the error state instead.
+  return props.showEmptyState
+    && !searchError.value
+    && !hasInitialResults.value
+    && result.value?.data.length === 0
 })
 
 const hasConditions = computed(() => {
@@ -458,6 +575,13 @@ const tableSelect = computed(() => {
   return withoutIndexField(result.value?.query.select ?? [])
 })
 
+// The effective row identifier when resolving / editing a row: the configured
+// `indexField`, or `id` by default. Distinct from the raw `props.indexField`,
+// whose `undefined` means "no index field configured" — `withIndexField` /
+// `withoutIndexField` rely on that to leave a non-editable catalog's columns
+// alone, so they deliberately keep using the prop directly rather than this.
+const idField = computed(() => props.indexField ?? 'id')
+
 // Whether the currently loaded rows actually carry the effective row identifier.
 // Editing / opening a row needs it (`resolveId`), but rows fetched while
 // `editable` was still false — or before an `indexField` change settled — won't
@@ -467,7 +591,7 @@ const tableSelect = computed(() => {
 const rowsCarryIndexField = computed(() => {
   const rows = result.value?.data
   if (!rows || rows.length === 0) { return true }
-  return (props.indexField ?? 'id') in rows[0]
+  return idField.value in rows[0]
 })
 
 // The row-identifier the table uses as its selection key. An explicit
@@ -526,6 +650,12 @@ function createInputFilters(queryFilters: any[], filters: any[]) {
 // reconcile result (the refreshed state supersedes it).
 function refetch(): void {
   latestState.value = null
+  // Supersede any in-flight search now, not only once the debounced run starts:
+  // a retry/search still loading for the previous query state would otherwise
+  // remain "latest" through the debounce window and, on resolving, clear the error
+  // or assign its rows after the query has already moved on. The next run captures
+  // the bumped token, so it isn't self-suppressed.
+  searchToken++
   doRefresh()
 }
 
@@ -667,8 +797,9 @@ const sheetError = ref(false)
 const reconciling = ref(false)
 const busy = computed(() => pendingWrites.value > 0 || reconciling.value)
 
-// Whether any write in the current in-flight batch failed; when so the reconcile
-// is skipped (the snackbar already told the user to reload).
+// Whether any write in the current in-flight batch failed; passed to the
+// post-batch reconcile so the refresh banner can label itself as a recovery for
+// the failed write's diverged row rather than just "newer data".
 let batchErrored = false
 
 // In-flight write chains keyed by record+field, so repeated writes to the same
@@ -693,10 +824,20 @@ let reconcileToken = 0
 // Resolve a record's identifier, unwrapping the id field's object shape
 // (`{ value, display, path }`) when present.
 function resolveId(record: Record<string, any>): any {
-  const v = record?.[props.indexField ?? 'id']
+  const v = record?.[idField.value]
   return v !== null && typeof v === 'object' ? v.value : v
 }
 
+// Resolve a human-facing label for a record — the index field's display value
+// (the id object's `{ value, display, path }` shape) falling back to the bare
+// identifier — to name the affected row in a write-failure snackbar. Null when
+// no usable label exists, so the snackbar can fall back to anonymous copy.
+function resolveLabel(record: Record<string, any>): string | null {
+  const v = record?.[idField.value]
+  const label = v !== null && typeof v === 'object' ? (v.display ?? v.value) : v
+  return label != null && label !== '' ? String(label) : null
+}
+
 const { execute: executeUpdate } = useMutation((http, id: any, values: Record<string, any>) =>
   http.post(`${endpointBase.value}/update`, {
     entity: entityName.value, id, values, settings: { lang }
@@ -737,6 +878,14 @@ function guardBusy(): boolean {
   return false
 }
 
+// `updated_at` is a server-managed timestamp that bumps on every write, so a
+// reconciled row's value always differs from the optimistic one even when nothing
+// else changed. It's excluded from the diff below (and patched to ~now on save) so
+// an edit never surfaces the refresh banner just for its own timestamp — the user
+// shouldn't be asked to reload the whole view over a change that obviously follows
+// from their edit. Always a datetime column, never user-editable.
+const UPDATED_AT_KEY = 'updated_at'
+
 // Value-level comparison (rows in order + total) deciding whether a reconcile
 // surfaced anything newer than the optimistic state on screen. `fresh` is the
 // canonical search-shaped result; `shown` is what's displayed, which may carry
@@ -751,6 +900,9 @@ function isSameResult(fresh: LensResult | null, shown: LensResult | null): boole
     const freshRow = fresh.data[i]
     const shownRow = shown.data[i]
     for (const key of Object.keys(freshRow)) {
+      // The always-bumped timestamp would make every edited row look "changed";
+      // skip it so it alone can't surface the refresh banner (see UPDATED_AT_KEY).
+      if (key === UPDATED_AT_KEY) { continue }
       if (JSON.stringify(freshRow[key]) !== JSON.stringify(shownRow?.[key])) {
         return false
       }
@@ -761,8 +913,11 @@ function isSameResult(fresh: LensResult | null, shown: LensResult | null): boole
 
 // After the last in-flight write settles, fetch the canonical state for the
 // current query and, only if it differs from what's shown, stash it behind the
-// refresh button. The server is fresh by now (the write completed).
-async function reconcile(): Promise<void> {
+// refresh button. The server is fresh by now (the write completed). `afterError`
+// is set when a write in the batch *failed*: its optimistic edit wasn't rolled
+// back, so the canonical state diverges and the stash becomes the user's one-click
+// path to restore it — the banner labels it accordingly.
+async function reconcile(afterError = false): Promise<void> {
   const token = ++reconcileToken
   reconciling.value = true
   try {
@@ -775,9 +930,13 @@ async function reconcile(): Promise<void> {
     // Authoritative: stash the canonical result when it differs from what's
     // shown, otherwise clear any (possibly stale) stash — an earlier overlapping
     // reconcile may have left a pre-edit result behind.
-    latestState.value = result.value && !isSameResult(fresh, result.value) ? fresh : null
+    latestState.value = result.value && !isSameResult(fresh, result.value)
+      ? { result: fresh, fromError: afterError }
+      : null
   } catch {
-    // Ignore — keep the optimistic state, offer no refresh.
+    // Ignore — keep the optimistic state, offer no refresh. After a failed write
+    // this means no recovery banner, so the failure snackbar's reload guidance is
+    // the fallback.
   } finally {
     if (token === reconcileToken) {
       reconciling.value = false
@@ -787,8 +946,15 @@ async function reconcile(): Promise<void> {
 
 function applyLatest(): void {
   if (!latestState.value) { return }
-  result.value = latestState.value
+  result.value = latestState.value.result
   latestState.value = null
+  // These are fresh authoritative rows for the current query, so drop any
+  // search-error state — e.g. a search failed, then a sheet save's reconcile
+  // surfaced this banner; applying it must reveal the rows, not stay on the retry.
+  searchError.value = false
+  // Supersede any in-flight retry started from that error state, so it can't
+  // assign over these rows or re-raise the error after they've been applied.
+  searchToken++
   prevFetchInput = null
   rebindOpenSheet()
 }
@@ -830,9 +996,19 @@ async function forceRefresh(): Promise<void> {
   // fresh result when it resolves — same token mechanism as the write/create
   // races. This refetch captures the bumped token, so it isn't self-suppressed.
   searchToken++
+  const token = searchToken
   prevFetchInput = null
   latestState.value = null
   await refresh()
+  // A deliberate reload landed fresh rows — clear any prior search-error state so
+  // the list shows them instead of a stale error. But only if this reload wasn't
+  // itself invalidated mid-flight (a write bumping `searchToken` makes the fetcher
+  // return the current result, not freshly-assigned rows) — otherwise we'd dismiss
+  // the error over the previous query's rows. (On failure this rethrows and the
+  // flag is left untouched; the create path handles its own fallback.)
+  if (token === searchToken) {
+    searchError.value = false
+  }
   rebindOpenSheet()
 }
 
@@ -867,7 +1043,7 @@ async function refreshCatalog(): Promise<void> {
 // `resolveId` would be `undefined`), which would let a delete/save act on the
 // wrong — or no — id during and after the refetch.
 watch(
-  () => (props.editable ? (props.indexField ?? 'id') : null),
+  () => (props.editable ? idField.value : null),
   (field, prev) => {
     if (!field || field === prev) { return }
     if (sheet.state.value && sheetMode.value === 'view') { sheet.off() }
@@ -882,14 +1058,40 @@ watch(
 )
 
 // Track an optimistic background write: count it as pending, surface a snackbar
-// on failure, and once the whole batch settles (with no failures) reconcile.
+// on failure, and once the whole batch settles reconcile (so a failed write's
+// diverged row can be restored via the refresh banner).
 function hasPendingWrite(recordId: any): boolean {
   return pendingByRecord.has(recordId)
 }
 
+// Compose the failure snackbar: name the affected row when we have a label, then
+// the server's reason (a policy / business-rule / validation message) when
+// present, and always a recovery hint. The optimistic value isn't rolled back, so
+// the user needs a way back to canonical state — the refresh banner offers a
+// one-click path when it appears, but it can't always (a failed recovery reconcile
+// shows none, and `isSameResult` can't see detail-only sheet fields absent from
+// the search), so the reload hint stays as the guaranteed fallback. With a reason
+// present, "reload to see the latest" (the change didn't take; reload to resync);
+// without one (network / 5xx / opaque), "reload and try again".
+function writeErrorText(op: 'save' | 'delete', label: string | null, reason: string | null): string {
+  const subject = op === 'delete'
+    ? (label != null ? t.delete_failed(label) : t.delete_failed_anon)
+    : (label != null ? t.save_failed(label) : t.save_failed_anon)
+  return reason
+    ? `${subject} ${reason} ${t.write_error_recover}`
+    : `${subject} ${t.write_error_reload}`
+}
+
 // Track an optimistic background write for `recordId`, serialized per `key` so
-// writes to the same cell reach the server in edit order.
-function trackWrite(recordId: any, key: string, run: () => Promise<unknown>): void {
+// writes to the same cell reach the server in edit order. `op` / `label` name the
+// affected row in the failure snackbar.
+function trackWrite(
+  recordId: any,
+  key: string,
+  op: 'save' | 'delete',
+  label: string | null,
+  run: () => Promise<unknown>
+): void {
   // A new write changes the displayed state. Clear any stashed reconcile result
   // and invalidate an in-flight reconcile (advance the token so its result is
   // dropped; clear its busy flag — `pendingWrites` keeps us busy), so neither
@@ -911,9 +1113,17 @@ function trackWrite(recordId: any, key: string, run: () => Promise<unknown>): vo
   writeChains.set(key, current)
 
   current
-    .catch(() => {
+    .catch((e) => {
       batchErrored = true
-      snackbars.push({ mode: 'danger', text: t.write_error })
+      // Name the affected row and prefer a server-provided reason (a policy /
+      // business-rule deny, a validation message) so a rejected write explains
+      // itself and the user can tell which edit failed when several are in flight.
+      // The optimistic edit isn't rolled back here; the post-batch reconcile
+      // surfaces the refresh banner to restore it.
+      snackbars.push({
+        mode: 'danger',
+        text: writeErrorText(op, label, extractServerMessage(e))
+      })
     })
     .finally(() => {
       // Only drop the chain entry if a newer write hasn't replaced it.
@@ -930,9 +1140,12 @@ function trackWrite(recordId: any, key: string, run: () => Promise<unknown>): vo
       if (pendingWrites.value === 0) {
         const errored = batchErrored
         batchErrored = false
-        if (!errored) {
-          reconcile()
-        }
+        // Reconcile on error too: a failed write left its optimistic edit on the
+        // row, so the canonical state now diverges and the refresh banner becomes
+        // the user's one-click path to restore it (labelled as a recovery). If the
+        // reconcile itself fails, no banner shows and the snackbar's reload
+        // guidance is the fallback.
+        reconcile(errored)
       }
     })
 }
@@ -948,13 +1161,21 @@ function save(record: Record<string, any>, values: Record<string, any>): void {
   // row, so a follow-up save / delete would resolve to the new, not-yet-synced id
   // and miss the in-flight record. Strip it so the invariant holds for every
   // caller. (The identifier is still settable on create, which uses `create()`.)
-  const indexField = props.indexField ?? 'id'
+  const indexField = idField.value
   if (indexField in values) {
     values = { ...values }
     delete values[indexField]
   }
   if (Object.keys(values).length === 0) { return }
   Object.assign(record, values)
+  // Optimistically advance the row's `updated_at` to ~now so the displayed
+  // timestamp reflects the edit immediately. The server sets the authoritative
+  // value; a little skew is fine and never surfaces the refresh banner, since the
+  // reconcile diff ignores this column. Display-only — deliberately not added to
+  // the persisted `values` (the server owns its own timestamping).
+  if (UPDATED_AT_KEY in record) {
+    record[UPDATED_AT_KEY] = day().toISOString()
+  }
   // Serialize per record+field so two quick edits to the same cell apply in
   // order; edits to disjoint fields run concurrently.
   const fields = Object.keys(values)
@@ -972,7 +1193,7 @@ function save(record: Record<string, any>, values: Record<string, any>): void {
       && k.slice(prefix.length).split(',').some((f) => fieldSet.has(f)))
     .map(([, chain]) => chain)
   const gate = Promise.allSettled(overlapping)
-  trackWrite(id, key, () => gate.then(() => executeUpdate(id, values)))
+  trackWrite(id, key, 'save', resolveLabel(record), () => gate.then(() => executeUpdate(id, values)))
 }
 
 // Create — blocking. The slow POST runs to completion, then the catalog is
@@ -1000,6 +1221,11 @@ async function create(values: Record<string, any>): Promise<Record<string, any>>
     // during the create (doRefresh bails on `creating`); create's own forceRefresh
     // bypasses that by calling refresh directly.
     searchToken++
+    // Don't clear `searchError` here: only a successful current-query refresh
+    // should (forceRefresh does so on success). The fallbacks below show the
+    // previous query's rows plus the new record — not the requested query — so
+    // dismissing the error there would present stale rows as if they matched.
+    //
     // From here a refresh failure must not reject (the caller would treat the
     // create as failed and re-submit a duplicate); fall back to showing the new
     // record optimistically.
@@ -1066,7 +1292,7 @@ function remove(record: Record<string, any>): void {
   // `Promise.allSettled([])` resolves immediately, so this is a no-op gate when
   // the record has no in-flight writes.
   const gate = Promise.allSettled(pendingForRecord)
-  trackWrite(id, `${id}:__delete__`, () => gate.then(() => executeDelete(id)))
+  trackWrite(id, `${id}:__delete__`, 'delete', resolveLabel(record), () => gate.then(() => executeDelete(id)))
 }
 
 async function openSheet(record: Record<string, any>): Promise<void> {
@@ -1121,9 +1347,10 @@ async function openSheet(record: Record<string, any>): Promise<void> {
 }
 
 function openCreate(): void {
-  // `creatable` is the prop that enables creation. Honor it here even though
-  // this method is exposed (and provided to children).
-  if (!props.creatable) {
+  // Creation is enabled by `creatable`, which defaults to on for an editable
+  // catalog. Honor it here even though this method is exposed (and provided to
+  // children).
+  if (!props.editable || !props.creatable) {
     return
   }
   // Supersede any in-flight openSheet `/show` so it can't open over the create
@@ -1136,6 +1363,27 @@ function openCreate(): void {
   sheet.on()
 }
 
+// Catalog-level editing gate: `editable` is set (boolean `true` or a predicate)
+// and the rows carry the index field needed to resolve a record's id.
+function editEnabled(): boolean {
+  return !!props.editable && rowsCarryIndexField.value
+}
+
+// Per-record refinement: a predicate `editable`/`deletable` decides each row, a
+// boolean applies to all.
+function canEdit(record: Record<string, any>): boolean {
+  return editEnabled() && (typeof props.editable === 'function' ? props.editable(record) : true)
+}
+
+// Delete is a stronger action than edit and rides the same editable sheet, so a
+// row must be editable before it can be deleted — building on `canEdit` makes a
+// per-record `editable` predicate gate delete too (a row it rejects is never
+// deletable). `deletable` then refines further: on unless explicitly `false`, or
+// its own per-record predicate.
+function canDelete(record: Record<string, any>): boolean {
+  return canEdit(record) && (typeof props.deletable === 'function' ? props.deletable(record) : props.deletable)
+}
+
 provideLensEdit({
   // Getters so the injected context tracks prop changes after mount (e.g.
   // permissions resolving async, or a flag toggling `editable` off): LensTable
@@ -1145,8 +1393,8 @@ provideLensEdit({
   // trigger a refetch to pull in the identifier, but it lands asynchronously —
   // keep editing off until the rows actually carry it, so a save in that window
   // can't `resolveId()` to `undefined`.
-  get editable() { return !!props.editable && rowsCarryIndexField.value },
-  get creatable() { return !!props.creatable },
+  get editable() { return editEnabled() },
+  get creatable() { return !!props.editable && props.creatable },
   // Use the same `__no_entity__` fallback as the search / CRUD requests so slot
   // side-channel saves (which read this) target the same entity, not an empty one.
   get entity() { return entityName.value },
@@ -1154,7 +1402,9 @@ provideLensEdit({
   // sheet opener and to block identifier edits, so it must track a prop that
   // resolves (or changes) after mount — otherwise the new identifier column stays
   // non-clickable while the old field is still treated as the id.
-  get indexField() { return props.indexField ?? 'id' },
+  get indexField() { return idField.value },
+  canEdit,
+  canDelete,
   resolveId,
   save,
   create,
@@ -1276,32 +1526,48 @@ defineExpose({
       </div>
       <SDivider />
       <div v-if="latestState && !busy" class="refresh-banner">
-        <span class="refresh-banner-text">{{ t.refresh_text }}</span>
+        <span class="refresh-banner-text">{{ latestState.fromError ? t.refresh_failed_text : t.refresh_text }}</span>
         <SButton size="mini" mode="info" :label="t.refresh_action" @click="applyLatest" />
       </div>
       <div class="list" :style="tableMaxHeight">
-        <LensTable
-          :result
-          :loading
-          :overrides="_overrides"
-          :select="tableSelect"
-          :index-field="tableIndexField"
-          :selected
-          :clickable-fields
-          :inline-edit
-          @filter-updated="onInlineFilterUpdated"
-          @sort-updated="onSortUpdated"
-          @update:selected="onUpdateSelected"
-          @cell-clicked="(v, r) => emit('cell-clicked', v, r)"
-        />
-        <LensCatalogFooter
-          v-if="result && result?.pagination.total > 0"
-          :class="{ 'is-busy': busy }"
-          :result
-          :loading
-          @prev="onPrev"
-          @next="onNext"
-        />
+        <div v-if="searchError" class="list-error">
+          <p class="list-error-text">{{ t.search_error }}</p>
+          <!-- Retry the same query via the busy-guarded `doRefresh` (not `refetch`,
+               which would clear a `latestState` recovery banner before the retry
+               resolves — a failed retry would then lose that known-good stash). -->
+          <SButton
+            size="small"
+            mode="info"
+            :label="t.search_retry"
+            :loading
+            :disabled="busy"
+            @click="doRefresh"
+          />
+        </div>
+        <template v-else>
+          <LensTable
+            :result
+            :loading
+            :overrides="_overrides"
+            :select="tableSelect"
+            :index-field="tableIndexField"
+            :selected
+            :clickable-fields
+            :inline-editable
+            @filter-updated="onInlineFilterUpdated"
+            @sort-updated="onSortUpdated"
+            @update:selected="onUpdateSelected"
+            @cell-clicked="(v, r) => emit('cell-clicked', v, r)"
+          />
+          <LensCatalogFooter
+            v-if="result && result?.pagination.total > 0"
+            :class="{ 'is-busy': busy }"
+            :result
+            :loading
+            @prev="onPrev"
+            @next="onNext"
+          />
+        </template>
       </div>
     </div>
 
@@ -1337,7 +1603,7 @@ defineExpose({
       :loading="sheetLoading"
       :error="sheetError"
       :fields="result.fields"
-      :index-field="indexField ?? 'id'"
+      :index-field="idField"
       :width="sheetWidth"
       @close="sheet.off"
     >
@@ -1414,6 +1680,23 @@ defineExpose({
   flex-grow: 1;
 }
 
+.list-error {
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  padding: 48px 16px;
+  text-align: center;
+}
+
+.list-error-text {
+  font-size: 14px;
+  line-height: 1.6;
+  color: var(--c-text-2);
+}
+
 .control-skeleton {
   height: 56px;
   background-color: var(--c-bg-1);

package/lib/blocks/lens/components/LensSheet.vue

@@ -9,10 +9,11 @@ import { provideDataListState } from '../../../composables/DataList'
 import { useTrans } from '../../../composables/Lang'
 import { usePower } from '../../../composables/Power'
 import { useValidation } from '../../../composables/Validation'
+import { useSnackbars } from '../../../stores/Snackbars'
 import { type FieldData } from '../FieldData'
 import { useFieldFactory } from '../composables/FieldFactory'
 import { useLensEdit } from '../composables/LensEdit'
-import { extractServerErrors } from '../validation/ServerErrors'
+import { extractServerErrors, extractServerMessage } from '../validation/ServerErrors'
 import LensSheetField from './LensSheetField.vue'
 
 const props = withDefaults(defineProps<{
@@ -46,7 +47,7 @@ const { t } = useTrans({
     confirm_delete: 'Delete this record?',
     new_record: 'New record',
     load_error:
-      'Couldn’t load this record. Please reload the page, and contact support if the problem persists.'
+      'We couldn’t load this record. Please reload the page and try again.'
   },
   ja: {
     create: '作成',
@@ -55,12 +56,13 @@ const { t } = useTrans({
     confirm_delete: 'このレコードを削除しますか？',
     new_record: '新規作成',
     load_error:
-      'このレコードを読み込めませんでした。ページを再読み込みし、問題が解決しない場合はサポートにお問い合わせください。'
+      'このレコードを読み込めませんでした。ページを再読み込みして、もう一度お試しください。'
   }
 })
 
 const edit = useLensEdit()
 const factory = useFieldFactory()
+const snackbars = useSnackbars()
 
 // Provide the data-list label width directly (instead of wrapping rows in
 // SDataList) so each LensSheetField wrapper doesn't make its SDataListItem a
@@ -126,6 +128,11 @@ const saving = ref(false)
 // sheet opened; `onCreate` re-checks it too.
 const creatable = computed(() => !!edit?.creatable)
 
+// Whether the open record may be deleted. Reactive (a getter on the edit
+// context) so the delete button hides if a per-record `deletable` predicate, or
+// a permission change, rejects it after the sheet has opened.
+const deletable = computed(() => !!props.record && !!edit?.canDelete(props.record))
+
 // Backend-only validation errors (e.g. `unique`) returned by a rejected
 // create, fed to Vuelidate via `$externalResults` so they surface on the
 // offending field. The create form's keys are the bare field keys, matching
@@ -197,13 +204,24 @@ async function onCreate() {
     await edit!.create(values)
     emit('close')
   } catch (e) {
-    // Surface backend validation errors (e.g. a duplicate `unique` value) on
-    // the offending fields; rethrow anything that isn't a 422.
+    // Surface backend validation errors (e.g. a duplicate `unique` value) on the
+    // offending fields. Failing that, surface a server-provided message (a policy
+    // / business-rule deny, or a form-level 422) as a snackbar and keep the sheet
+    // open with the input intact — rather than rethrowing into the global
+    // full-page error handler. Failures without a displayable message — network,
+    // 5xx, opaque, and auth / session expiry (which extractServerMessage excludes
+    // so the app can prompt re-auth) — still propagate.
     const errors = extractServerErrors(e)
-    if (!errors) {
-      throw e
+    if (errors) {
+      serverErrors.value = errors
+      return
+    }
+    const message = extractServerMessage(e)
+    if (message) {
+      snackbars.push({ mode: 'danger', text: message })
+      return
     }
-    serverErrors.value = errors
+    throw e
   } finally {
     saving.value = false
   }
@@ -255,7 +273,11 @@ function saveRecord(values: Record<string, any>): Promise<void> {
   // but saving against the partial row mid-`/show` (or after it failed) could
   // overwrite a not-yet-loaded detail field with an empty value — the built-in
   // fields avoid this by not rendering until the record is ready.
-  if (props.loading || props.error || !props.record || !edit) {
+  //
+  // Also honor the per-record edit gate: a custom slot editor funnels through
+  // here, so a row a `editable` predicate rejects must not be saved through the
+  // slot any more than through the built-in cell / field editors.
+  if (props.loading || props.error || !props.record || !edit || !edit.canEdit(props.record)) {
     return Promise.resolve()
   }
   edit.save(props.record, values)
@@ -270,6 +292,10 @@ const slotProps = computed(() => ({
   // record has loaded; `save` also hard-refuses while loading/error as a guard.
   loading: props.loading ?? false,
   error: props.error ?? false,
+  // Whether a per-record `editable` predicate allows editing this row, so a slot
+  // editor can disable its own controls for a rejected row; `save` enforces it
+  // regardless, but otherwise the refusal is only visible as a silent no-op.
+  canEdit: !!props.record && !!edit?.canEdit(props.record),
   save: saveRecord
 }))
 </script>
@@ -338,7 +364,7 @@ const slotProps = computed(() => ({
             @click="onCreate"
           />
         </template>
-        <template v-else-if="record && !loading && !error">
+        <template v-else-if="record && !loading && !error && deletable">
           <template v-if="confirmingDelete.state.value">
             <span class="confirm-text">{{ t.confirm_delete }}</span>
             <SButton size="medium" :label="t.cancel" @click="confirmingDelete.off" />
@@ -457,6 +483,10 @@ const slotProps = computed(() => ({
   border-top: 1px solid var(--c-divider);
 }
 
+.footer:empty {
+  display: none;
+}
+
 .confirm-text {
   margin-right: auto;
   font-size: 13px;

package/lib/blocks/lens/components/LensSheetField.vue

@@ -22,7 +22,7 @@ const { t } = useTrans({
 
 const edit = useLensEdit()
 
-const editable = computed(() => !!edit && (props.field as any).data?.showOnUpdate === true)
+const editable = computed(() => !!edit?.canEdit(props.record) && (props.field as any).data?.showOnUpdate === true)
 
 // Some field types do not implement a detail renderer or an editable input
 // (they `throw new Error('Not implemented.')`). Resolve them defensively so a
@@ -121,6 +121,14 @@ async function apply() {
     return
   }
 
+  // A per-record `editable` predicate can flip to reject this row while the editor
+  // is open (e.g. a refresh marks it locked). Re-check before persisting so an
+  // already-open editor can't save a row the policy now rejects.
+  if (!canEdit.value) {
+    editing.value = false
+    return
+  }
+
   // Optimistic: patch + persist in the background, then close immediately.
   edit!.save(props.record, {
     [props.fieldKey]: props.field.inputToPayload(model.value)

package/lib/blocks/lens/components/LensTable.vue

@@ -27,7 +27,7 @@ const props = defineProps<{
   indexField?: string
   // When set (and editing is enabled), cells for `showOnUpdate` fields
   // render a hover edit affordance that opens an inline editor.
-  inlineEdit?: boolean
+  inlineEditable?: boolean
 }>()
 
 const emit = defineEmits<{
@@ -68,11 +68,6 @@ const columnKeys = computed(() => {
   return visible.map((k) => (k === '__empty__' ? `__empty__::${emptyIndex++}` : k))
 })
 
-const orders = computed(() => [
-  ...columnKeys.value,
-  '__last_empty__'
-])
-
 const columns = computedAsync(async () => {
   const r = props.result
 
@@ -125,6 +120,13 @@ const columns = computedAsync(async () => {
     // off the configured index field for any field type — a slug/code identifier
     // opens the sheet just like an `id` — so other id-type columns (e.g. a
     // `company_id` reference link) keep their own navigation.
+    //
+    // Exception: an `id` field whose server value carries a `path` renders that
+    // path as a link; respect it so those rows navigate to the details page instead
+    // of opening the sheet (decided per row, so id's without a path still open it).
+    // Scoped to `id` fields — a custom index field that itself renders a link (e.g.
+    // a `link` / `slack_message` identifier) is still turned into the sheet opener,
+    // as is a column whose `cell` is undefined (falls straight through to the opener).
     if (
       edit?.editable
       && key === edit.indexField
@@ -132,15 +134,20 @@ const columns = computedAsync(async () => {
       const original = column.cell
       column.cell = (v: any, r: any): TableCell<any, any> => {
         const cell = typeof original === 'function' ? original(v, r) : original
+        if (overriddenFieldData.type === 'id' && cell && 'link' in cell && cell.link) {
+          return cell
+        }
         return {
-          ...(cell as TableCell<any, any>),
+          ...cell,
           link: null,
+          // @ts-expect-error avatar and day cells don't have info as color,
+          // but we don't use those for the index field anyway, so it's safe to force it here
           color: 'info',
           onClick: () => edit.openSheet(r)
-        } as TableCell<any, any>
+        }
       }
     } else if (
-      props.inlineEdit
+      props.inlineEditable
       && edit?.editable
       && key !== edit.indexField
       && overriddenFieldData.showOnUpdate === true
@@ -182,6 +189,18 @@ const columns = computedAsync(async () => {
   return columns
 }, {})
 
+// Render a column only once its definition exists. `columns` resolves
+// asynchronously (computedAsync), so when a column is toggled back on its key
+// lands in `columnKeys` a tick before `columns` rebuilds to include it. Emitting
+// that key in `orders` during the gap makes STable render the column with no cell
+// definition — STableCell then falls back to STableCellText with the raw value
+// (e.g. the `id` field's `{ value, display, path }` object), tripping a Vue
+// prop-type warning. Gating on presence in `columns` keeps the two in lockstep.
+const orders = computed(() => [
+  ...columnKeys.value.filter((key) => key in columns.value),
+  '__last_empty__'
+])
+
 const table = useTable({
   records,
   orders,

package/lib/blocks/lens/components/LensTableEditableCell.vue

@@ -3,11 +3,13 @@ import IconPencilSimple from '~icons/ph/pencil-simple'
 import { useElementBounding } from '@vueuse/core'
 import { computed, nextTick, onUnmounted, ref, shallowRef, watch } from 'vue'
 import SButton from '../../../components/SButton.vue'
+import SLink from '../../../components/SLink.vue'
 import SPill, { type Mode as PillMode } from '../../../components/SPill.vue'
 import SState, { type Mode as StateMode } from '../../../components/SState.vue'
 import { useManualDropdownPosition } from '../../../composables/Dropdown'
 import { useTrans } from '../../../composables/Lang'
 import { useValidation } from '../../../composables/Validation'
+import { day } from '../../../support/Day'
 import { type FieldData } from '../FieldData'
 import { useLensEdit } from '../composables/LensEdit'
 import { useLensInlineEdit } from '../composables/LensInlineEdit'
@@ -31,6 +33,10 @@ const inline = useLensInlineEdit()
 const myKey = computed(() => `${edit?.resolveId(props.record)}:${props.fieldKey}`)
 const editing = computed(() => inline?.activeKey.value === myKey.value)
 
+// A predicate `editable` on the catalog can disable editing per row; hide the
+// affordance and refuse to open the editor when this record is rejected.
+const canEdit = computed(() => !!edit?.canEdit(props.record))
+
 // If the backing value is replaced while this editor is open — a refresh banner
 // apply, a parent `refresh()`, or a requery that keeps this row visible — the
 // `model` captured back in `start()` is now stale, and saving it would overwrite
@@ -81,6 +87,18 @@ const displayState = computed<{ label: string; mode?: StateMode } | null>(() =>
   return cell && cell.type === 'state' ? { label: cell.label, mode: cell.mode } : null
 })
 
+// A text cell carrying a `link` (or `onClick`) — e.g. a LinkField — renders as a
+// link rather than bare text, mirroring the read-only STableCellText so a column
+// that was clickable before inline editing was enabled stays clickable instead of
+// degrading to plain text. The text itself comes from `displayValue` below.
+const displayLink = computed<{ link: string | null; onClick?: (v: any, r: any) => void } | null>(() => {
+  const cell = resolvedCell.value
+  if (cell && cell.type === 'text' && (cell.link != null || typeof cell.onClick === 'function')) {
+    return { link: cell.link ?? null, onClick: cell.onClick }
+  }
+  return null
+})
+
 // Falls back to a plain representation for non-text displays (pills and state
 // cells are rendered as their own components in the template above).
 const displayValue = computed(() => {
@@ -89,6 +107,14 @@ const displayValue = computed(() => {
     return resolved.value ?? ''
   }
 
+  // A `day` cell (e.g. a DateField) carries a Day value plus a format; render the
+  // formatted day — mirroring the read-only STableCellDay — so an inline-editable
+  // date column shows e.g. `YYYY-MM-DD` rather than the raw ISO/timestamp string
+  // the generic fallback below would otherwise surface.
+  if (resolved && resolved.type === 'day') {
+    return resolved.value ? day(resolved.value).format(resolved.format ?? 'YYYY-MM-DD HH:mm:ss') : ''
+  }
+
   const v = props.value
   if (v == null) {
     return ''
@@ -123,6 +149,10 @@ const editorStyle = computed(() => ({
 }))
 
 function start() {
+  if (!canEdit.value) {
+    return
+  }
+
   inputComponent.value = props.field.formInputComponent()
   model.value = props.field.payloadToInput(props.value ?? props.field.inputEmptyValue())
   reset()
@@ -161,6 +191,19 @@ async function apply() {
     return
   }
 
+  // A per-record `editable` predicate can flip to reject this row while the editor
+  // is open (e.g. a refresh marks it locked) — `start()` only gates opening, so
+  // re-check before persisting. Without this an already-open editor could save a
+  // row the policy now rejects. Close only if this cell is still the active one
+  // (mirrors the post-save close below) so bailing can't wipe an editor the user
+  // opened on another cell during the `await validate()`.
+  if (!canEdit.value) {
+    if (inline?.activeKey.value === myKey.value) {
+      inline.stop()
+    }
+    return
+  }
+
   // Optimistic: patch + persist in the background, then close immediately.
   edit!.save(props.record, {
     [props.fieldKey]: props.field.inputToPayload(model.value)
@@ -217,8 +260,18 @@ function isTextLikeInput(target: EventTarget | null): boolean {
       :mode="displayState.mode"
       :label="displayState.label"
     />
+    <SLink
+      v-else-if="displayLink"
+      class="value link"
+      :href="displayLink.link"
+      :role="displayLink.onClick ? 'button' : null"
+      @click="() => displayLink?.onClick?.(value, record)"
+    >
+      {{ displayValue }}
+    </SLink>
     <span v-else class="value">{{ displayValue }}</span>
     <button
+      v-if="canEdit"
       class="edit"
       type="button"
       :aria-label="`${t.edit} ${field.label()}`"
@@ -266,6 +319,15 @@ function isTextLikeInput(target: EventTarget | null): boolean {
   text-overflow: ellipsis;
 }
 
+.value.link {
+  color: var(--c-text-info-1);
+  transition: color 0.1s;
+}
+
+.value.link:hover {
+  color: var(--c-text-info-2);
+}
+
 .pills {
   display: flex;
   flex-wrap: nowrap;

package/lib/blocks/lens/composables/FileDownloader.ts

@@ -1,10 +1,37 @@
 import { useGet } from '../../../composables/Api'
+import { useTrans } from '../../../composables/Lang'
+import { useSnackbars } from '../../../stores/Snackbars'
 import { type FileDownloader } from '../FileDownloader'
+import { isAuthError } from '../validation/ServerErrors'
 
 export function useFileDownloader(): FileDownloader {
+  const snackbars = useSnackbars()
+
+  const { t } = useTrans({
+    en: { download_error: 'We couldn’t download this file. Please try again.' },
+    ja: { download_error: 'ファイルをダウンロードできませんでした。もう一度お試しください。' }
+  })
+
   const { execute: fileDownloader } = useGet<any, [url: string]>(async (http, url) => {
     return http.download(url)
   })
 
-  return fileDownloader
+  // The click binding (e.g. SDescFile's `@click`) doesn't await the returned
+  // promise, so a failed download would otherwise be an unhandled rejection with
+  // no feedback — the click just appears to do nothing. Catch and surface a
+  // snackbar. The response is a blob, so the server's message isn't readily
+  // decodable here; generic copy is the right level.
+  return async (url) => {
+    try {
+      return await fileDownloader(url)
+    } catch (e) {
+      // Let auth / session-expiry failures (401 / 419) propagate to the app's
+      // error flow so it can prompt re-authentication — the click path doesn't
+      // await this, so the rejection reaches the global handler as it did before.
+      if (isAuthError(e)) {
+        throw e
+      }
+      snackbars.push({ mode: 'danger', text: t.download_error })
+    }
+  }
 }

package/lib/blocks/lens/composables/LensEdit.ts

@@ -13,6 +13,12 @@ export interface LensEditContext {
   /** Whether new records may be created. */
   creatable: boolean
 
+  /** Whether the given record may be edited, inline or in the sheet. */
+  canEdit: (record: Record<string, any>) => boolean
+
+  /** Whether the given record may be deleted from the sheet. */
+  canDelete: (record: Record<string, any>) => boolean
+
   /** The entity key being edited (e.g. `topic`, `user`). */
   entity: string
 

package/lib/blocks/lens/composables/ResourceFetcher.ts

@@ -33,6 +33,12 @@ export function useResourceFetcher(): ResourceFetcher {
         data.value[key] = response
         delete pendingList[key]
         return response
+      },
+      (error) => {
+        // Clear the pending entry on failure too — otherwise the rejected promise
+        // stays cached under `key` and every retry returns the same rejection.
+        delete pendingList[key]
+        throw error
       }
     )
 

package/lib/blocks/lens/filter-inputs/SelectFilterInput.ts

@@ -2,6 +2,7 @@ import { type ValidationArgs } from '@vuelidate/core'
 import { defineAsyncComponent } from 'vue'
 import SInputDropdown, { type Option } from '../../../components/SInputDropdown.vue'
 import { required } from '../../../validation/rules'
+import { isAuthError } from '../validation/ServerErrors'
 import { FilterInput } from './FilterInput'
 
 export class SelectFilterInput extends FilterInput {
@@ -53,10 +54,25 @@ export class SelectFilterInput extends FilterInput {
   }
 
   async valueToText(value: any): Promise<string> {
-    const options = await this.resolveOptions()
+    // Degrade gracefully: if the options can't be fetched, or the applied filter
+    // value isn't among them (the option set changed, or the referenced record was
+    // deleted), fall back to the raw value instead of asserting — a throw here
+    // leaves the filter chip stuck on its loading placeholder forever.
+    let options: Option[] = []
+    try {
+      options = await this.resolveOptions()
+    } catch (e) {
+      // Let auth / session-expiry failures reach the app's error / re-auth flow
+      // instead of silently degrading to raw values. Other failures — an option
+      // miss or a non-auth fetch error — fall back so the chip stays readable.
+      if (isAuthError(e)) {
+        throw e
+      }
+      options = []
+    }
 
     return this.valueAsArray(value)
-      .map((v) => options.find((o) => o.value === v)!.label)
+      .map((v) => options.find((o) => o.value === v)?.label ?? String(v))
       .join(', ')
   }
 

package/lib/blocks/lens/validation/ServerErrors.ts

@@ -23,3 +23,41 @@ export function extractServerErrors(error: unknown): Record<string, string[]> |
 
   return errors
 }
+
+/**
+ * Auth / session-expiry statuses (Laravel: 401 unauthenticated, 419 session /
+ * CSRF token expired). These need the app-level error flow — e.g. to prompt
+ * re-authentication — so Lens never surfaces them inline or swallows them into a
+ * snackbar; callers let them propagate to the global handler instead.
+ */
+const AUTH_STATUSES = new Set([401, 419])
+
+export function isAuthError(error: unknown): boolean {
+  return isFetchError(error) && error.status != null && AUTH_STATUSES.has(error.status)
+}
+
+/**
+ * Extract a human-readable top-level message from a failed request, when the
+ * server provides one worth showing the user. Laravel includes a `message` on
+ * most error responses — policy denials (`Response::deny('…')`), business-rule
+ * rejections, and 422 summaries. Limited to 4xx so internal 5xx detail never
+ * leaks to the UI, and excludes auth / session statuses (see `isAuthError`) so
+ * those reach the app's re-auth flow rather than being shown inline. 5xx /
+ * network / opaque / auth failures return `null` so the caller can fall back to
+ * its own generic copy or rethrow.
+ */
+export function extractServerMessage(error: unknown): string | null {
+  if (
+    !isFetchError(error)
+    || error.status == null
+    || error.status < 400
+    || error.status >= 500
+    || AUTH_STATUSES.has(error.status)
+  ) {
+    return null
+  }
+
+  const message = (error.data as any)?.message
+
+  return typeof message === 'string' && message.trim() !== '' ? message : null
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@globalbrain/sefirot",
-  "version": "4.50.0",
+  "version": "4.52.0",
   "description": "Vue Components for Global Brain Design System.",
   "keywords": [
     "components",