basalt-ui 1.23.1 → 1.25.0

package/src/guard/check-source.test.ts

@@ -66,6 +66,58 @@ describe('raw-hex', () => {
     const f = find(`// use #ff0000 from the palette`)
     expect(kinds(f)).not.toContain('raw-hex')
   })
+
+  /**
+   * Round 9, rollhook: `{` / `}` — the escaped braces an Astro template writes to show a
+   * literal `${…}` in prose — were read as the hex colors `#123` / `#125`, and 4 findings blocked a
+   * release on a page with no color in it at all. The hole was in the KIND, not in the extension:
+   * the same string produced the same two findings in `.html`, `.tsx`, `.css` and `.vue`.
+   */
+  describe('HTML numeric character references', () => {
+    const ENTITIES = `<p>image: $&#123;IMAGE_TAG&#125;</p>`
+
+    for (const rel of [
+      'index.html',
+      'src/App.tsx',
+      'src/a.css',
+      'src/Hero.vue',
+      'src/pages/index.astro',
+    ]) {
+      it(`does NOT read &#123;/&#125; as a hex color in ${rel}`, () => {
+        expect(kinds(find(ENTITIES, rel))).not.toContain('raw-hex')
+      })
+    }
+
+    // The exemption is the ENTITY, never the file type — a template that hardcodes a color is
+    // exactly what making `.astro`/`.vue` scannable was for.
+    it('still flags a real hex in an .astro file', () => {
+      const f = find(`<div style="color: #ff0000">x</div>`, 'src/pages/index.astro')
+      expect(kinds(f)).toContain('raw-hex')
+      expect(f.find((x) => x.kind === 'raw-hex')?.token).toBe('#ff0000')
+    })
+
+    it('still flags a real hex in a .vue file', () => {
+      const f = find(`<style>\n  .hero { color: #ff0000; }\n</style>`, 'src/Hero.vue')
+      expect(kinds(f)).toContain('raw-hex')
+      expect(f.find((x) => x.kind === 'raw-hex')?.token).toBe('#ff0000')
+    })
+
+    it('flags a hex after a bare & — an entity needs its terminating semicolon', () => {
+      expect(kinds(find(`<p>a&#fff b</p>`, 'index.html'))).toContain('raw-hex')
+    })
+
+    it('flags a plain #123 with no entity around it', () => {
+      expect(kinds(find(`const c = '#123'`))).toContain('raw-hex')
+    })
+
+    // The neighbouring raw-text kinds were checked for the same blind spot and do NOT share it: a
+    // character reference contains no `(`, so `raw-color-fn`'s `rgba?|hsla?\(` anchor cannot occur
+    // inside one, and every other raw-text kind anchors on a property name, `var(`, or a JSX `=`.
+    it('leaves the sibling color kinds unchanged — nothing else fires inside an entity', () => {
+      const src = `<p>&amp; &mdash; &nbsp; &#8212; &hellip; &#x1F600; &copy;</p>`
+      expect(find(src, 'index.html')).toHaveLength(0)
+    })
+  })
 })
 
 // ── 2. raw-color-fn ──────────────────────────────────────────────────────────
@@ -2580,6 +2632,95 @@ describe('markup files (index.html / *.webmanifest)', () => {
   })
 })
 
+// ── 29b. single-file components (.astro / .vue) ───────────────────────────────
+
+/**
+ * Round 9: `.astro` and `.vue` became scannable and fell through to the `ts` dialect, so `<!-- … -->`
+ * was never stripped — a `theme-allow` written in an HTML comment waived nothing there, and a color
+ * inside a commented-out block still reported. They resolve as `sfc` now: BOTH comment dialects,
+ * and the full 25-kind set (not `MARKUP_KINDS` — an `.astro` template is JSX-shaped and a `.vue`
+ * `<script setup>` is real TS).
+ */
+describe('single-file components (.astro / .vue)', () => {
+  const ASTRO = 'src/pages/index.astro'
+  const VUE = 'src/Hero.vue'
+
+  for (const rel of [ASTRO, VUE]) {
+    it(`strips an HTML comment in ${rel}`, () => {
+      expect(kinds(find(`<!-- <div style="color: #ff0000" /> -->`, rel))).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow inside an HTML comment in ${rel}`, () => {
+      const f = find(
+        `<!-- theme-allow raw-hex — brand asset -->\n<div style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow-file inside an HTML comment in ${rel}`, () => {
+      const f = find(
+        `<!-- theme-allow-file raw-hex — brand asset -->\n<b style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`honours a multi-line HTML comment annotation in ${rel}`, () => {
+      const f = find(
+        `<!--\n  theme-allow raw-hex — brand asset\n-->\n<b style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`still strips the JS dialect in ${rel} — an SFC carries both`, () => {
+      expect(kinds(find(`// const c = '#ff0000'`, rel))).not.toContain('raw-hex')
+      expect(kinds(find(`/* const c = '#ff0000' */`, rel))).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow in the script fence of ${rel}`, () => {
+      const f = find(`// theme-allow raw-hex — brand asset\nconst c = '#ff0000'`, rel)
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`keeps the non-markup kinds — an SFC is not MARKUP_KINDS-restricted in ${rel}`, () => {
+      expect(kinds(find(`const s = { border: '1px solid #ccc' }`, rel))).toContain('raw-surface')
+      expect(kinds(find(`<div style={{ padding: 18 }} />`, rel))).toContain('inline-spacing')
+    })
+  }
+
+  it('does not let an HTML comment open a runaway JS block comment', () => {
+    const f = find(`<!-- a /* unclosed -->\n<div style="color: #ff0000" />`, ASTRO)
+    expect(kinds(f)).toContain('raw-hex')
+  })
+
+  /**
+   * Asserted LIMITS, so "unsupported" and "silently broken" don't read the same. Both are
+   * false-negative-only — the direction a release-blocking false positive says to take.
+   */
+  describe('known limits', () => {
+    it('does not fire the kebab-CSS surface kinds inside a <style> fence', () => {
+      const src = `<style>\n  .card { border-radius: 8px; }\n</style>`
+      expect(kinds(find(src, ASTRO))).not.toContain('css-raw-surface')
+      // The same text in a real .css file still reports — the limit is the SFC dialect, not the rule.
+      expect(kinds(find(src.replace(/<\/?style>/g, ''), 'src/a.css'))).toContain('css-raw-surface')
+    })
+
+    it('over-strips a `<!--` that lives inside a script string', () => {
+      expect(
+        kinds(find(`const s = '<!--'\nconst c = '#ff0000'\nconst e = '-->'`, ASTRO)),
+      ).not.toContain('raw-hex')
+    })
+
+    it('over-strips after an unquoted `https://` in template prose', () => {
+      expect(
+        kinds(find(`<p>see https://x.test <b style="color: #ff0000" /></p>`, ASTRO)),
+      ).not.toContain('raw-hex')
+    })
+  })
+})
+
 // ── 30. tokens-only profile ──────────────────────────────────────────────────
 
 describe("profile: 'tokens-only'", () => {

package/src/guard/index.ts

@@ -10,7 +10,32 @@ export type { Finding, GuardConfig, GuardKind, GuardSeverity }
 
 // ── Static regex consts ──────────────────────────────────────────────────────────────────────────
 
-const HEX = /#[0-9a-fA-F]{3,8}\b/g
+/**
+ * A raw hex color literal.
+ *
+ * The `(?!(?<=&#)\d+;)` guard drops an HTML NUMERIC CHARACTER REFERENCE. `&#123;` is the escaped
+ * `{` and `&#125;` the escaped `}` — the two an Astro/JSX template writes to show a literal brace
+ * in prose — and their `#123` / `#125` read as three-digit hex. It is not markup-specific: the same
+ * string produced the same two findings in `.html`, `.tsx`, `.css` and `.vue`, so this was a hole
+ * in the kind itself that `.astro` merely walked into first (rollhook, round 9).
+ *
+ * The lookahead is deliberately the FULL reference — `&#`, digits, `;` — not a bare `(?<!&)`. Only
+ * the decimal form can collide at all (`&#x1F600;` never matches: `x` is not a hex digit), and a
+ * `#` that follows an `&` without terminating in `;` is not an entity, so `color: red&#fff` still
+ * flags. Nothing is exempted by file type; a real `#ff0000` in an `.astro` file fires exactly as it
+ * does in a `.tsx` one.
+ *
+ * The sibling raw-text kinds do NOT share this blind spot, and the reason is structural rather than
+ * lucky: a character reference contains no `(`, so `raw-color-fn`'s `rgba?|hsla?\(` anchor cannot
+ * occur inside one, and every other raw-text kind is anchored on a property name, `var(`, or a JSX
+ * `=`. Probed across `.html`/`.astro`/`.tsx` over 20 entity shapes — `raw-hex` was the only kind
+ * that fired.
+ *
+ * Known and NOT covered, because the fix would cost real findings: an all-hex URL fragment or SVG
+ * reference (`href="#cafe"`, `fill="url(#abcdef)"`) is indistinguishable from a color by text
+ * alone, and both still report. `theme-allow` is the escape there.
+ */
+const HEX = /#(?!(?<=&#)\d+;)[0-9a-fA-F]{3,8}\b/g
 
 /**
  * A raw `rgb()`/`rgba()`/`hsl()`/`hsla()` color function.
@@ -531,6 +556,21 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * into an unplanned refactor, which is exactly what the grace minor exists to prevent. The five
  * entries below all landed together in the round-4 guard minor and all promote one minor later.
  *
+ * **A `SCANNABLE_EXT` widening cannot be expressed here, and 1.23.2's was deliberately not.**
+ * Adding `.astro`/`.jsx`/`.vue` widens the FILE SET for all 25 kinds at once — there is no kind to
+ * key an entry on, and the nearest one (`raw-hex`, which is what actually fired) is keyed per KIND,
+ * not per extension: an entry for it would demote basalt's most load-bearing kind to `warn` in
+ * every `.tsx` and `.css` in every consumer for a minor, to buy runway on a file type only one
+ * consumer has. `css-raw-surface` is the shape that DOES fit — the new dialect got its own kind
+ * because kebab CSS is a distinct pattern set; more files running the same patterns is not.
+ *
+ * The measurement agreed with the structure. Once the two defects the widening exposed were fixed
+ * (`&#123;` read as a hex; `<!-- … -->` never stripped in an SFC), rollhook's marketing site scans
+ * 6 files with 0 findings, and no other consumer has a single `.astro`, `.vue` or `.jsx` file — so
+ * grace would have covered zero incumbent violations. The doctrine protects code that "passed every
+ * previous release"; a violation in a newly-scanned file type is code the consumer is writing now,
+ * with `theme-allow`, `basalt.severity` and `exemptRules` all still available.
+ *
  * @example
  * const GRACE: Partial<Record<GuardKind, string>> = {
  *   'raw-font-family': 'introduced 1.4.0 — promote to error in 1.5.0',
@@ -846,10 +886,13 @@ function commentBlockEnd(
   syntax: GuardSyntax,
 ): number {
   const line = lines[index] ?? ''
+  // An SFC carries both dialects, so the closer is resolved from the opener the token actually sits
+  // behind rather than from the extension: whichever of `<!--` / `/*` is NEAREST on its left wins.
+  const markup = syntax === 'markup' || (syntax === 'sfc' && opensMarkupComment(line, tokenAt))
   // A line comment closes at its own end of line. CSS has no `//`, so the test is TS-only: there,
   // a `//`-looking sequence is text and the conservative same-line answer is the right one anyway.
-  if (syntax === 'ts' && /\/\/\s*$/.test(line.slice(0, tokenAt))) return index
-  const closer = syntax === 'markup' ? '-->' : '*/'
+  if (!markup && syntax !== 'css' && /\/\/\s*$/.test(line.slice(0, tokenAt))) return index
+  const closer = markup ? '-->' : '*/'
   if (line.slice(tokenAt).includes(closer)) return index
   for (let ahead = index + 1; ahead < lines.length; ahead++) {
     if ((lines[ahead] ?? '').includes(closer)) return ahead
@@ -857,6 +900,18 @@ function commentBlockEnd(
   return index
 }
 
+/**
+ * In an `sfc` file, is the comment the token sits in an HTML one?
+ *
+ * Both dialects are legal in the same file, so the extension cannot answer it — the nearest opener
+ * on the token's left does. A tie (neither present) reads as the JS dialect, which is what an
+ * annotation on a bare frontmatter line is.
+ */
+function opensMarkupComment(line: string, tokenAt: number): boolean {
+  const before = line.slice(0, tokenAt)
+  return before.lastIndexOf('<!--') > before.lastIndexOf('/*')
+}
+
 /**
  * A comment opener sitting immediately before the annotation token.
  *
@@ -1132,8 +1187,8 @@ function annotationsCover(annotations: AllowAnnotation[] | undefined, kind: Guar
   return (annotations ?? []).some((a) => annotationCovers(a, kind))
 }
 
-/** The 3 comment dialects the stripper understands, resolved from the file's own extension. */
-type GuardSyntax = 'ts' | 'css' | 'markup'
+/** The 4 comment dialects the stripper understands, resolved from the file's own extension. */
+type GuardSyntax = 'ts' | 'css' | 'markup' | 'sfc'
 
 /**
  * CSS (including `.module.css`) has no `//` line-comment syntax at all — an unquoted `//`, e.g.
@@ -1143,13 +1198,50 @@ type GuardSyntax = 'ts' | 'css' | 'markup'
  * `markup` covers the two files whose colors nothing re-derives on a theme change and which the
  * scan never reached — `index.html` and `*.webmanifest` (plus plain `.json`, which a webmanifest
  * often is). Only the color/typography kinds apply there; see `MARKUP_KINDS`.
+ *
+ * `sfc` is the single-file-component dialect — `.astro` and `.vue`, which carry BOTH regions:
+ * `<!-- … -->` in the template and `//` / `/* … *\/` in the frontmatter/`<script>` fence. They used
+ * to fall through to `ts`, so an HTML comment was never stripped: a `theme-allow` written in one
+ * waived nothing, and a color inside a commented-out block still reported (rollhook, round 9 —
+ * `.astro` became scannable in the same minor that exposed it). They are NOT `markup`: an `.astro`
+ * template is JSX-shaped and a `.vue` `<script setup>` is real TS, so restricting them to
+ * {@link MARKUP_KINDS} would drop 22 of the 25 kinds on a file type that can violate all of them.
+ *
+ * `.jsx` needs no entry — it is TS syntax with no HTML-comment region.
+ *
+ * **Two asserted limits, both false-NEGATIVE-only** (pinned in `check-source.test.ts`):
+ *
+ * 1. The kebab-CSS kinds (`css-raw-surface`) do not fire inside a `<style>` fence — that branch
+ *    keys on `syntax === 'css'`, and an SFC is one file with three dialects, not three files. The
+ *    color kinds, which are what an unguarded template layer actually leaks, do fire there.
+ * 2. Stripping is region-BLIND: `<!-- … -->` is blanked anywhere in the file, and `//` anywhere
+ *    outside a string. A `<!--` inside a script string, or an unquoted `https://` in template
+ *    prose, over-strips the rest of that construct. Both directions lose findings rather than
+ *    inventing them, which is the side of the trade a release-blocking false positive says to take.
  */
 function guardSyntaxFor(relPath: string): GuardSyntax {
   if (relPath.endsWith('.css')) return 'css'
   if (/\.(?:html?|webmanifest|json)$/.test(relPath)) return 'markup'
+  if (/\.(?:astro|vue)$/.test(relPath)) return 'sfc'
   return 'ts'
 }
 
+/**
+ * The comment-stripped twin of `text`, same length and same newline positions, for any dialect.
+ *
+ * One place rather than the two call sites (`checkSource` and `findAllowAnnotations`) that used to
+ * spell the `markup ? … : …` ternary out independently — adding `sfc` to one and not the other is
+ * exactly how the scan and `--audit-allows` drift apart on what counts as a comment.
+ *
+ * The SFC order is markup-first: an HTML comment may legally contain `//` or an unterminated `/*`,
+ * and blanking it before the TS pass keeps that text from opening a comment that runs to EOF.
+ */
+function stripGuardComments(text: string, syntax: GuardSyntax): string {
+  if (syntax === 'markup') return stripMarkupComments(text)
+  if (syntax === 'sfc') return stripComments(stripMarkupComments(text), 'ts')
+  return stripComments(text, syntax)
+}
+
 /** The only kinds meaningful in an HTML document or a JSON manifest — no JSX, no CSS-in-JS. */
 const MARKUP_KINDS: ReadonlySet<GuardKind> = new Set(['raw-hex', 'raw-color-fn', 'raw-font-family'])
 
@@ -1840,7 +1932,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   // stripped text has already blanked out. Same length / same newline positions as `text`, so line
   // numbers computed off either one agree.
   const syntax = guardSyntaxFor(relPath)
-  const codeText = syntax === 'markup' ? stripMarkupComments(text) : stripComments(text, syntax)
+  const codeText = stripGuardComments(text, syntax)
   const codeLines = codeText.split('\n')
   const { waivers, fileScoped, declared } = collectAllowAnnotations(
     lines,
@@ -2020,7 +2112,9 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
         if (syntax === 'css' && isSubScaleCssSpacing(line, m.index)) continue
         const hasUnit = /^[a-z%]/.test(line.slice(m.index + m[0].length))
         if (
-          syntax === 'ts' &&
+          // An SFC's script fence IS TS, so it takes the same gate — without it a unitless
+          // `padding: 8` in `.astro`/`.vue` frontmatter reports with no style-object behind it.
+          (syntax === 'ts' || syntax === 'sfc') &&
           !hasUnit &&
           !isStyleObjectContext(codeText, lineStarts[i]! + m.index, styleIdentifiers)
         )
@@ -2256,7 +2350,7 @@ export function findAllowAnnotations(
 ): AllowAnnotationSite[] {
   const lines = text.split('\n')
   const syntax = guardSyntaxFor(relPath)
-  const codeText = syntax === 'markup' ? stripMarkupComments(text) : stripComments(text, syntax)
+  const codeText = stripGuardComments(text, syntax)
   const { declared } = collectAllowAnnotations(
     lines,
     codeText.split('\n'),

package/src/index.ts

@@ -95,6 +95,15 @@ export {
   type SettingsRowProps,
   DangerZone,
   type DangerZoneProps,
+  QueryState,
+  type QueryStateProps,
+  type QueryStateLike,
+  type QueryStateVariant,
+  type QueryEmptyCopy,
+  LoadingState,
+  type LoadingStateProps,
+  ErrorState,
+  type ErrorStateProps,
 } from './dashboard'
 
 // ── Connectivity (auto-mounted by BasaltProvider) ────────────────────────────────────────────────

package/src/query/error-message.test.ts

@@ -0,0 +1,67 @@
+/**
+ * `toErrorMessage`'s job is to never hand a human a string that says nothing. The decode ladder
+ * was already right; what was missing is the floor under it — an opaque envelope decoded to the
+ * literal `"{}"`, and `toErrorMessage(undefined)` returned `JSON.stringify(undefined)`, which is
+ * not a string at all despite the `string` return type. Both are the shape a page renders straight
+ * into an Alert, so both are asserted here.
+ */
+import { describe, expect, test } from 'bun:test'
+import { errorStatus, toErrorMessage } from './error-message'
+
+describe('toErrorMessage — decode ladder', () => {
+  test('Error instance → message', () => {
+    expect(toErrorMessage(new Error('slug already in use'))).toBe('slug already in use')
+  })
+
+  test('{ message } → message', () => {
+    expect(toErrorMessage({ message: 'recursive is rejected' })).toBe('recursive is rejected')
+  })
+
+  test('Eden { status, value } envelope → one level down', () => {
+    expect(toErrorMessage({ status: 409, value: { message: 'slug taken' } })).toBe('slug taken')
+  })
+
+  test('plain string → itself', () => {
+    expect(toErrorMessage('boom')).toBe('boom')
+  })
+})
+
+describe('toErrorMessage — the unusable floor', () => {
+  test('an opaque object falls back instead of rendering "{}"', () => {
+    expect(toErrorMessage({}, 'Could not create share')).toBe('Could not create share')
+  })
+
+  test('undefined returns a real string, not the undefined value', () => {
+    const message = toErrorMessage(undefined)
+    expect(typeof message).toBe('string')
+    expect(message).toBe('The request failed.')
+  })
+
+  test('an opaque envelope WITH a status folds the status into the fallback', () => {
+    expect(toErrorMessage({ status: 502, value: {} }, 'Could not load images')).toBe(
+      'Could not load images (HTTP 502)',
+    )
+  })
+
+  test('a readable body wins over the status — the server message is never replaced', () => {
+    expect(toErrorMessage({ status: 403, value: { message: 'forbidden' } }, 'Nope')).toBe(
+      'forbidden',
+    )
+  })
+
+  test('whitespace-only decodes as unusable', () => {
+    expect(toErrorMessage({ message: '   ' }, 'Fallback')).toBe('Fallback')
+  })
+})
+
+describe('errorStatus', () => {
+  test('reads a numeric status off an envelope', () => {
+    expect(errorStatus({ status: 404, value: null })).toBe(404)
+  })
+
+  test('is undefined for anything else', () => {
+    expect(errorStatus(new Error('x'))).toBeUndefined()
+    expect(errorStatus(null)).toBeUndefined()
+    expect(errorStatus({ status: '404' })).toBeUndefined()
+  })
+})

package/src/query/error-message.ts

@@ -0,0 +1,70 @@
+/**
+ * Transport-agnostic error decoding. Deliberately a standalone module with NO
+ * `@tanstack/react-query` import — `dashboard/query-state.tsx` renders server messages and must
+ * not drag the query peer into the root barrel's graph to do it.
+ */
+
+/**
+ * The HTTP status behind a thrown envelope (Eden Treaty's `{ status, value }`, a `Response`-shaped
+ * throw), when there is one. Use it to BRANCH — 404 → "not found" copy — rather than to build a
+ * message; `toErrorMessage` already folds the status into its text when the body says nothing.
+ *
+ * @example
+ * if (errorStatus(err) === 404) return <EmptyState title="Gone" />
+ */
+export function errorStatus(err: unknown): number | undefined {
+  if (err === null || typeof err !== 'object') return undefined
+  const status = (err as { status?: unknown }).status
+  return typeof status === 'number' ? status : undefined
+}
+
+/** Strings that technically decoded but tell a reader nothing. `JSON.stringify` produces most. */
+const UNUSABLE = new Set(['', '{}', '[]', 'null', 'undefined', '[object Object]'])
+
+function decode(err: unknown): string {
+  if (err instanceof Error) return err.message
+  if (typeof err === 'string') return err
+  if (typeof err === 'object' && err !== null) {
+    const obj = err as Record<string, unknown>
+    if (typeof obj['message'] === 'string') return obj['message']
+    // Eden-style { value: ... } or { status, value } envelopes — unwrap one level.
+    if ('value' in obj) return decode(obj['value'])
+  }
+  try {
+    return JSON.stringify(err) ?? ''
+  } catch {
+    return String(err)
+  }
+}
+
+/**
+ * Extract a human-readable message from an unknown thrown value (e.g. the raw Eden envelope
+ * thrown by `unwrap`). Removes the 8-line three-branch boilerplate consumers duplicate.
+ *
+ * Resolution order:
+ *   1. `Error` instance       → err.message
+ *   2. `{ message: string }`  → message (Eden / Elysia error shape)
+ *   3. `{ value: ... }`       → recursively (Eden nested value envelope)
+ *   4. plain string           → itself
+ *   5. anything else          → `JSON.stringify`
+ *
+ * **If that yields nothing a human can read** (`''`, `'{}'`, `'[]'`, `'null'`, `'undefined'`,
+ * `'[object Object]'` — the shapes `JSON.stringify` produces for an opaque envelope) the `fallback`
+ * is returned instead, with `(HTTP <status>)` appended when the envelope carries one. Without that
+ * guard the caller renders a literal `{}` at the user, or — for `toErrorMessage(undefined)` —
+ * the actual value `undefined`, since `JSON.stringify(undefined)` is not a string at all.
+ *
+ * @example
+ * try {
+ *   await unwrap(api.resource.post({ body }))
+ * } catch (e) {
+ *   toast(toErrorMessage(e, 'Could not create share'))   // → "slug already in use"
+ *                                                        // → "Could not create share (HTTP 502)"
+ * }
+ */
+export function toErrorMessage(err: unknown, fallback = 'The request failed.'): string {
+  const message = decode(err).trim()
+  if (!UNUSABLE.has(message)) return message
+  const status = errorStatus(err)
+  return status === undefined ? fallback : `${fallback} (HTTP ${status})`
+}

package/src/query/index.ts

@@ -69,41 +69,9 @@ export async function unwrap<TData>(
   return data as TData
 }
 
-// ── toErrorMessage ────────────────────────────────────────────────────────────────────────────────
+// ── Error decoding ────────────────────────────────────────────────────────────────────────────────
 
-/**
- * Extract a human-readable message from an unknown thrown value (e.g. the raw Eden envelope
- * thrown by `unwrap`). Removes the 8-line three-branch boilerplate consumers duplicate.
- *
- * Resolution order:
- *   1. `Error` instance       → err.message
- *   2. `{ message: string }`  → message (Eden / Elysia error shape)
- *   3. `{ value: ... }`       → toErrorMessage(value) recursively (Eden nested value envelope)
- *   4. plain string            → itself
- *   5. anything else           → JSON.stringify with safe fallback to String()
- *
- * @example
- * try {
- *   await unwrap(api.resource.post({ body }))
- * } catch (e) {
- *   toast(toErrorMessage(e))
- * }
- */
-export function toErrorMessage(err: unknown): string {
-  if (err instanceof Error) return err.message
-  if (typeof err === 'string') return err
-  if (typeof err === 'object' && err !== null) {
-    const obj = err as Record<string, unknown>
-    if (typeof obj['message'] === 'string') return obj['message']
-    // Eden-style { value: ... } or { status, value } envelopes — unwrap one level.
-    if ('value' in obj) return toErrorMessage(obj['value'])
-  }
-  try {
-    return JSON.stringify(err)
-  } catch {
-    return String(err)
-  }
-}
+export { toErrorMessage, errorStatus } from './error-message'
 
 // ── Re-exports from @tanstack/react-query ────────────────────────────────────────────────────────
 

package/src/surfaces.ts

@@ -194,7 +194,7 @@ export const SURFACES = {
       'mantine-shade-index',
     ],
     description:
-      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)',
+      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)',
     optionalPeers: [
       'react-markdown',
       'remark-gfm',