@ultimat3/ui 23.0.0 → 25.0.0

package/src/components/DataTable.tsx

@@ -5,6 +5,9 @@
 // The four-way decision itself is NOT here — it is `asyncBranch`, shared with `AsyncRegion`, so a
 // table and a card list cannot disagree about what "loading with stale rows" looks like. Only the
 // PLACEHOLDER is local, because a table's is table-shaped: rows of cells, not lines of text.
+//
+// A narrow table is the SAME table restyled as labelled cards (`DataTable.module.scss`), never a
+// second copy: a duplicate is read twice or, hidden, is links the reader is told are not there.
 
 import { type AsyncState, finiteCount } from '@ultimat3/core';
 import type { JSX } from 'solid-js';
@@ -14,6 +17,14 @@ import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
 import { type AsyncBranch, asyncBranch, isBusyBranch } from './async-branch';
 import styles from './DataTable.module.scss';
+import {
+  type ColumnPriority,
+  columnPriority,
+  type MoreColumn,
+  moreColumn,
+  priorityAttr,
+  TABLE_ROLES,
+} from './data-table-view';
 import { EmptyState } from './EmptyState';
 import { ErrorState } from './ErrorState';
 import { Pagination } from './Pagination';
@@ -31,8 +42,18 @@ export interface Column<Row> {
   /** Right-aligns in LTR and left-aligns in RTL via `text-align: end`. */
   numeric?: boolean | undefined;
   width?: string | undefined;
+  /**
+   * 1 (default) is a cell at every width; 2 hides the cell while the TABLE is narrower than `md`,
+   * 3 while it is narrower than `lg`. A hidden value moves into the row's "more" disclosure, so it
+   * is never lost — which renders `cell` a second time: give a priority to columns that SHOW a
+   * value, never to one holding a form control or a fixed `id`.
+   */
+  priority?: ColumnPriority | undefined;
 }
 
+/** Below `sm`, `cards` restacks each row as a labelled card; `scroll` keeps the scrolling table. */
+export type DataTableNarrow = 'cards' | 'scroll';
+
 interface DataTableBaseProps<Row> {
   caption: string;
   columns: readonly Column<Row>[];
@@ -49,6 +70,10 @@ interface DataTableBaseProps<Row> {
   nextCursor?: string | undefined;
   prevCursor?: string | undefined;
   stickyHeader?: boolean | undefined;
+  /** Pins the first column while the table scrolls sideways. */
+  stickyFirstColumn?: boolean | undefined;
+  /** What a table narrower than `sm` becomes. Default `cards`. */
+  narrow?: DataTableNarrow | undefined;
   density?: 'comfortable' | 'compact' | undefined;
   /** Placeholder row count while loading. Match the usual page size. */
   skeletonRows?: number | undefined;
@@ -108,6 +133,43 @@ export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
 
   const branch = (): AsyncBranch<readonly Row[]> => asyncBranch(state());
 
+  const cards = (): boolean => (props.narrow ?? 'cards') === 'cards';
+  /** Read through the validator on every render, so a bad priority is refused, never shown. */
+  const priorityOf = (column: Column<Row>): string | undefined =>
+    priorityAttr(columnPriority(column.priority));
+
+  /** The card label rides inside the cell and is `aria-hidden`: the header already names it. */
+  const cellContent = (column: Column<Row>, row: Row): JSX.Element =>
+    cards()
+      ? [
+          // No class: the attribute is the stylesheet's hook, and this span is on every cell.
+          <span data-label="" aria-hidden="true">
+            {column.header}
+          </span>,
+          column.cell(row),
+        ]
+      : column.cell(row);
+
+  /**
+   * The hidden columns' values, each entry shown only over the widths its own cell is hidden —
+   * a `<details>`, so it opens with scripting off.
+   */
+  const disclosure = (more: MoreColumn<Column<Row>>, row: Row): JSX.Element => (
+    <td role={TABLE_ROLES.cell} class={styles['more']} data-more={more.until}>
+      <details class={styles['disclosure']}>
+        <summary class={styles['summary']}>{ui.t(UI_KEYS.more)}</summary>
+        <dl class={styles['entries']}>
+          {more.columns.map((column) => (
+            <div class={styles['entry']} data-priority={priorityOf(column)}>
+              <dt>{column.header}</dt>
+              <dd>{column.cell(row)}</dd>
+            </div>
+          ))}
+        </dl>
+      </details>
+    </td>
+  );
+
   const body = (): JSX.Element => {
     if (branch().kind === 'pending') {
       // `Array.from({ length: NaN })` is `[]`, so a busy tbody with no placeholders in it is the
@@ -116,44 +178,37 @@ export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
       // neither, because `NaN` is not nullish. 0 stays legal: a loading table with no placeholders
       // is a choice, and it is a visible one.
       const placeholders = finiteCount('DataTable', 'skeletonRows', props.skeletonRows ?? 5, 0);
+      const more = moreColumn(props.columns);
       return Array.from({ length: placeholders }, () => (
-        <tr>
-          {props.columns.map(() => (
-            <td>
+        <tr role={TABLE_ROLES.row} class={styles['row']}>
+          {props.columns.map((column) => (
+            <td role={TABLE_ROLES.cell} class={styles['cell']} data-priority={priorityOf(column)}>
               <Skeleton height="1.1em" />
             </td>
           ))}
+          {more === undefined ? null : (
+            <td role={TABLE_ROLES.cell} class={styles['more']} data-more={more.until} />
+          )}
         </tr>
       ));
     }
+    const more = moreColumn(props.columns);
     return props.rows.map((row) => (
-      <tr data-row={props.rowKey(row)}>
+      <tr role={TABLE_ROLES.row} class={styles['row']} data-row={props.rowKey(row)}>
         {props.columns.map((column) => (
-          <td class={column.numeric === true ? styles['numeric'] : undefined}>
-            {column.cell(row)}
+          <td
+            role={TABLE_ROLES.cell}
+            class={cx(styles['cell'], column.numeric === true && styles['numeric'])}
+            data-priority={priorityOf(column)}
+          >
+            {cellContent(column, row)}
           </td>
         ))}
+        {more === undefined ? null : disclosure(more, row)}
       </tr>
     ));
   };
 
-  const decided = branch();
-  if (decided.kind === 'failed') {
-    return <ErrorState error={decided.error} onRetry={props.onRetry} class={props.class} />;
-  }
-
-  // Unreachable while pending, by the shape of `AsyncBranch` rather than by the order of two ifs:
-  // "No results" under a first page in flight is the bug that ordering used to be all that stopped.
-  if (decided.kind === 'empty') {
-    return (
-      <EmptyState
-        title={props.emptyTitle}
-        description={props.emptyDescription}
-        class={props.class}
-      />
-    );
-  }
-
   /** One mode per use, exactly as `Pagination` declares it — the table only hands it through. */
   const pager = (): JSX.Element =>
     props.hrefFor === undefined ? (
@@ -185,6 +240,10 @@ export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
    * linked, a button that calls back when it is not. A linked table with no `sortHrefFor` gets the
    * header text alone — a `<button>` on a page that never hydrates is a control that does nothing.
    */
+  /** Whether a header renders a control at all — the card view shows only those headers. */
+  const hasSortControl = (column: Column<Row>): boolean =>
+    column.sortable === true && (props.hrefFor === undefined || props.sortHrefFor !== undefined);
+
   const sortControl = (column: Column<Row>): JSX.Element => {
     if (column.sortable !== true) return column.header;
     const label = `${column.header}: ${sortLabel(column.key)}`;
@@ -216,35 +275,86 @@ export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
     );
   };
 
-  return (
-    <div class={cx(styles['wrap'], props.class)}>
-      <Table
-        caption={props.caption}
-        stickyHeader={props.stickyHeader !== false}
-        density={props.density ?? 'comfortable'}
+  // An array, not a fragment: this package's `.tsx` compiles to two factories (Solid's and render's
+  // `h`), and only an array means the same sibling list to both.
+  const header = (): JSX.Element => {
+    const more = moreColumn(props.columns);
+    return (
+      <thead
+        role={TABLE_ROLES.rowgroup}
+        class={styles['head']}
+        data-sortable={props.columns.some(hasSortControl) ? '' : undefined}
       >
-        <thead>
-          <tr>
-            {props.columns.map((column) => (
-              <th
-                scope="col"
-                style={column.width === undefined ? undefined : { 'inline-size': column.width }}
-                aria-sort={ariaSortFor(props.sort, column.key)}
-                class={column.numeric === true ? styles['numeric'] : undefined}
-              >
-                {sortControl(column)}
-              </th>
-            ))}
-          </tr>
-        </thead>
-        <tbody
-          class={decided.kind === 'ready' && decided.busy ? styles['stale'] : undefined}
-          aria-busy={ariaBool(isBusyBranch(decided))}
-        >
-          {body()}
-        </tbody>
-      </Table>
-      {props.nextCursor === undefined && props.prevCursor === undefined ? null : pager()}
+        <tr role={TABLE_ROLES.row}>
+          {props.columns.map((column) => (
+            <th
+              scope="col"
+              role={TABLE_ROLES.columnheader}
+              style={column.width === undefined ? undefined : { 'inline-size': column.width }}
+              aria-sort={ariaSortFor(props.sort, column.key)}
+              class={cx(styles['heading'], column.numeric === true && styles['numeric'])}
+              data-priority={priorityOf(column)}
+              data-sort-control={hasSortControl(column) ? '' : undefined}
+            >
+              {sortControl(column)}
+            </th>
+          ))}
+          {more === undefined ? null : (
+            <th
+              scope="col"
+              role={TABLE_ROLES.columnheader}
+              class={styles['more']}
+              data-more={more.until}
+            >
+              {ui.t(UI_KEYS.more)}
+            </th>
+          )}
+        </tr>
+      </thead>
+    );
+  };
+
+  const table = (decided: AsyncBranch<readonly Row[]>): JSX.Element => [
+    <Table
+      caption={props.caption}
+      stickyHeader={props.stickyHeader !== false}
+      stickyFirstColumn={props.stickyFirstColumn === true}
+      explicitRoles
+      density={props.density ?? 'comfortable'}
+    >
+      {header()}
+      <tbody
+        role={TABLE_ROLES.rowgroup}
+        class={cx(styles['body'], decided.kind === 'ready' && decided.busy && styles['stale'])}
+        aria-busy={ariaBool(isBusyBranch(decided))}
+      >
+        {body()}
+      </tbody>
+    </Table>,
+    props.nextCursor === undefined && props.prevCursor === undefined ? null : pager(),
+  ];
+
+  /**
+   * The branch is decided INSIDE the returned JSX, as `AsyncRegion` does: a component body runs
+   * once, so a decision taken there is the decision for the island's whole life — a table that
+   * first rendered its error state kept it after the query recovered.
+   */
+  const content = (): JSX.Element => {
+    const decided = branch();
+    if (decided.kind === 'failed') {
+      return <ErrorState error={decided.error} onRetry={props.onRetry} />;
+    }
+    // Unreachable while pending, by the shape of `AsyncBranch` rather than by the order of two
+    // ifs: "No results" under a first page in flight is the bug that ordering used to stop.
+    if (decided.kind === 'empty') {
+      return <EmptyState title={props.emptyTitle} description={props.emptyDescription} />;
+    }
+    return table(decided);
+  };
+
+  return (
+    <div class={cx(styles['wrap'], props.class)} data-narrow={props.narrow ?? 'cards'}>
+      {content()}
     </div>
   );
 }

package/src/components/Divider.tsx

@@ -25,9 +25,7 @@ export function Divider(props: DividerProps): JSX.Element {
     // ARIA does not give a value and does not put in the tab order. `<hr>` is void, so the
     // caption has to live in a container that carries the role itself.
     // biome-ignore lint/a11y/useSemanticElements: <hr> cannot hold the caption
-    // biome-ignore lint/a11y/useFocusableInteractive: a captioned rule is not a splitter
     <div
-      // biome-ignore lint/a11y/useAriaPropsForRole: aria-valuenow is the splitter flavour's
       role="separator"
       aria-orientation={orientation()}
       class={cx(styles['labelled'], props.class)}

package/src/components/DonutChart.module.scss

@@ -0,0 +1,73 @@
+@use '../tokens' as t;
+
+// A square box, centred, never wider than a phone column needs: the centre label is HTML laid
+// over the ring, so it keeps its type step at every size (issue 494's rule).
+.donut {
+  position: relative;
+  display: grid;
+  place-items: center;
+  inline-size: 100%;
+  max-inline-size: t.rem(224px);
+  margin-inline: auto;
+  aspect-ratio: 1;
+  // The ring is drawn clockwise from twelve in either direction; its overlay must agree.
+  direction: ltr;
+}
+
+.ring {
+  grid-area: 1 / 1;
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+}
+
+.track {
+  fill: t.role('line', 0.35);
+}
+
+.segment {
+  fill: var(--series);
+}
+
+// The marker is cut out of the segment in the surface colour, so its SHAPE names the series.
+.marker {
+  fill: t.role('surface');
+}
+
+.centre {
+  grid-area: 1 / 1;
+  display: grid;
+  justify-items: center;
+  gap: t.space(1);
+  max-inline-size: 55%;
+  margin: 0;
+  text-align: center;
+  pointer-events: none;
+}
+
+.total {
+  @include t.data-text;
+  font-size: t.text(xl);
+  font-weight: t.weight(semibold);
+  line-height: t.leading(tight);
+  color: t.role('fg-strong');
+}
+
+.caption {
+  @include t.label-caps;
+  color: t.role('fg-muted');
+}
+
+.key {
+  display: block;
+  inline-size: t.space(3);
+  block-size: t.space(3);
+}
+
+.keyBlock {
+  fill: var(--series);
+}
+
+.keyMarker {
+  fill: t.role('surface');
+}

package/src/components/DonutChart.tsx

@@ -0,0 +1,154 @@
+// Parts of one whole — traffic by device, runs by outcome — as a ring of segments with the total
+// (or the caller's figure) in its centre, a legend giving each part's value and share, and a hidden
+// data table. Each segment carries its series' marker shape and a gap from its neighbours, so
+// the ring reads in greyscale. SVG geometry from `donut-chart-view.ts`; text is HTML.
+
+import type { JSX } from 'solid-js';
+import { useUi } from '../theme/context';
+import type { ChartHit } from './ChartFrame';
+import { ChartFrame, chartHits } from './ChartFrame';
+import type { MarkerShape } from './chart-frame-view';
+import {
+  chartNumberFormat,
+  chartPercentFormat,
+  chartTable,
+  cssPercent,
+  hitEdge,
+  markerPath,
+  pointLabel,
+  seriesStyle,
+} from './chart-frame-view';
+import styles from './DonutChart.module.scss';
+import type { DonutArc } from './donut-chart-view';
+import { annularSector, DONUT, donutArcs } from './donut-chart-view';
+
+export interface DonutSegment {
+  /** The part's name, already translated. */
+  readonly label: string;
+  /** Its size; zero, negative and non-finite values are listed but not drawn. */
+  readonly value: number;
+}
+
+export interface DonutChartProps {
+  /** The chart's name, already translated: the figure's caption and the svg's accessible name. */
+  label: string;
+  /** Clockwise from twelve o'clock, in the order the legend lists them. */
+  segments: readonly DonutSegment[];
+  /** The figure in the ring's centre, already formatted. Default: the formatted total. */
+  centreValue?: string | undefined;
+  /** A short line under the centre figure, already translated — "Total", "Sessions". */
+  centreLabel?: string | undefined;
+  /** The segment column's head in the data table, already translated — "Device". */
+  keyLabel?: string | undefined;
+  /** The value column's head in the data table, already translated. Default: `label`. */
+  valueLabel?: string | undefined;
+  /** Formats every value. Default: `Intl.NumberFormat` in the page's locale. */
+  format?: ((value: number) => string) | undefined;
+  /** Give every drawn segment a tab stop and a hover/focus readout. Default off. */
+  focusable?: boolean | undefined;
+  /** Show the caption above the chart. Default off — it names the figure either way. */
+  showCaption?: boolean | undefined;
+  /** Lands on the root `<figure>`. */
+  class?: string | undefined;
+}
+
+const finitePositive = (value: number): number => (Number.isFinite(value) && value > 0 ? value : 0);
+
+export function DonutChart(props: DonutChartProps): JSX.Element {
+  const ui = useUi();
+  const format = (value: number): string => (props.format ?? chartNumberFormat(ui.locale))(value);
+  const percent = (share: number): string => chartPercentFormat(ui.locale)(share);
+  const arcs = (): readonly DonutArc[] => donutArcs(props.segments.map((s) => s.value));
+  const total = (): number => props.segments.reduce((sum, s) => sum + finitePositive(s.value), 0);
+  const { size, centre, outer, inner, marker } = DONUT;
+
+  const hits = (): readonly ChartHit[] =>
+    props.segments.flatMap((segment, i) => {
+      const anchor = arcs()[i]?.anchor;
+      if (anchor === null || anchor === undefined) return [];
+      const share = arcs()[i]?.share ?? 0;
+      return [
+        {
+          x: cssPercent(anchor.x, size),
+          y: cssPercent(anchor.y, size),
+          label: pointLabel(
+            segment.label,
+            undefined,
+            `${format(segment.value)} (${percent(share)})`,
+          ),
+          edge: hitEdge(anchor.x, size),
+        },
+      ];
+    });
+
+  return (
+    <ChartFrame
+      label={props.label}
+      showCaption={props.showCaption}
+      class={props.class}
+      legend={props.segments.map((segment, i) => ({
+        label: segment.label,
+        value: format(segment.value),
+        detail: percent(arcs()[i]?.share ?? 0),
+        swatch: segmentSwatch(seriesStyle(i).slot, seriesStyle(i).marker),
+      }))}
+      table={chartTable({
+        caption: props.label,
+        keyLabel: props.keyLabel,
+        keys: props.segments.map((segment) => segment.label),
+        series: [
+          { label: props.valueLabel ?? props.label, values: props.segments.map((s) => s.value) },
+        ],
+        format,
+      })}
+    >
+      <div class={styles['donut']}>
+        <svg
+          role="img"
+          aria-label={props.label}
+          viewBox={`0 0 ${size} ${size}`}
+          class={styles['ring']}
+        >
+          {/* The track: the empty ring a chart with nothing to total still draws. */}
+          <path
+            class={styles['track']}
+            d={annularSector(centre, centre, outer, inner, 0, Math.PI * 2)}
+          />
+          {arcs().map((arc, i) => {
+            if (arc.path === '') return null;
+            const style = seriesStyle(i);
+            return (
+              <g data-series={style.slot} data-segment={String(i)}>
+                <path class={styles['segment']} d={arc.path} />
+                {arc.marker === null ? null : (
+                  <path
+                    class={styles['marker']}
+                    d={markerPath(style.marker, arc.marker.x, arc.marker.y, marker)}
+                    data-marker={style.marker}
+                  />
+                )}
+              </g>
+            );
+          })}
+        </svg>
+        <p class={styles['centre']}>
+          <span class={styles['total']}>{props.centreValue ?? format(total())}</span>
+          {props.centreLabel === undefined ? null : (
+            <span class={styles['caption']}>{props.centreLabel}</span>
+          )}
+        </p>
+        {props.focusable === true ? chartHits(hits()) : null}
+      </div>
+    </ChartFrame>
+  );
+}
+
+/** A legend key for a segment: its colour slot with its marker shape cut out of it. */
+function segmentSwatch(slot: number, shape: MarkerShape): JSX.Element {
+  return (
+    <svg class={styles['key']} viewBox="0 0 12 12" data-series={slot} aria-hidden="true">
+      <rect class={styles['keyBlock']} width={12} height={12} rx={2} />
+      <path class={styles['keyMarker']} d={markerPath(shape, 6, 6, 3.5)} />
+    </svg>
+  );
+}

package/src/components/Dropzone.module.scss

@@ -25,8 +25,10 @@
     background: t.role('bg-soft');
   }
 
+  // Dimmed directly: `@include t.disabled` appends `:disabled`, which a `<label>` carrying a data
+  // flag can never be, so the rule it compiled to matched nothing (`disabled-dim.test.ts`).
   &[data-disabled='true'] {
-    @include t.disabled;
+    opacity: 0.55;
     background: t.role('bg-soft');
     cursor: not-allowed;
   }

package/src/components/Dropzone.tsx

@@ -12,7 +12,7 @@ import { useUi } from '../theme/context';
 import { solid } from '../theme/solid-adapter';
 import styles from './Dropzone.module.scss';
 import type { FileSelection } from './file-input-view';
-import { adoptDroppedFiles, progressPercent, selectFiles } from './file-input-view';
+import { adoptAcceptedFiles, progressPercent, selectFiles } from './file-input-view';
 
 export interface DropzoneProps {
   /** Already-translated instruction. Required — it is the control's accessible name. */
@@ -23,11 +23,13 @@ export interface DropzoneProps {
   name?: string | undefined;
   /** The `accept` attribute, and the same list a dropped file is partitioned against. */
   accept?: string | undefined;
+  /** Without it the zone takes ONE file, dropped or picked — the rest are refused by `count`. */
   multiple?: boolean | undefined;
   required?: boolean | undefined;
   disabled?: boolean | undefined;
   /** Client-side ceiling. The server enforces its own; this only spares a doomed transfer. */
   maxBytes?: number | undefined;
+  /** Read only with `multiple`: a single-file zone's ceiling is one. */
   maxFiles?: number | undefined;
   /** 0..1 while an upload runs. Absent renders no bar at all — never one stuck at zero. */
   progress?: number | undefined;
@@ -49,8 +51,18 @@ export function Dropzone(props: DropzoneProps): JSX.Element {
   const inputId = (): string => props.id ?? fallbackId;
   const percent = (): number => progressPercent(props.progress ?? 0);
 
-  const offer = (files: FileList | null | undefined): void => {
-    props.onSelect(selectFiles([...(files ?? [])], props));
+  // The input first, then the callback: a drop that only reaches `onSelect` leaves the real
+  // control empty, and a refused file left in it is posted by the form anyway.
+  const offer = (files: FileList | null | undefined, origin: 'drop' | 'pick'): void => {
+    // `multiple` limits a drop too: the picker enforces the attribute itself, but a drop never
+    // goes through the picker, so a single-file zone would otherwise take every file dropped on it.
+    const selection = selectFiles([...(files ?? [])], {
+      accept: props.accept,
+      maxBytes: props.maxBytes,
+      maxFiles: props.multiple === true ? props.maxFiles : 1,
+    });
+    adoptAcceptedFiles(input, files, selection, origin);
+    props.onSelect(selection);
   };
 
   // `dragover` must be cancelled on every tick or the browser refuses the drop and navigates to
@@ -74,10 +86,7 @@ export function Dropzone(props: DropzoneProps): JSX.Element {
         event.preventDefault();
         setOver(false);
         if (props.disabled === true) return;
-        // The input first, then the callback: a drop that only reaches `onSelect` leaves the real
-        // control empty, and the form the label sits in submits nothing.
-        adoptDroppedFiles(input, event.dataTransfer?.files);
-        offer(event.dataTransfer?.files);
+        offer(event.dataTransfer?.files, 'drop');
       }}
     >
       <span class={styles['label']}>{props.label}</span>
@@ -96,7 +105,7 @@ export function Dropzone(props: DropzoneProps): JSX.Element {
         disabled={props.disabled === true}
         aria-describedby={props['aria-describedby']}
         aria-invalid={ariaBool(props['aria-invalid'])}
-        onChange={(event) => offer(event.currentTarget.files)}
+        onChange={(event) => offer(event.currentTarget.files, 'pick')}
       />
       {props.progress === undefined ? null : (
         <span

package/src/components/ErrorState.tsx

@@ -2,7 +2,13 @@
 // code, cause, fix. Identical text in the CLI, the overlay, and `--json` is the
 // whole point of the error contract — this component must not paraphrase.
 
-import { describeErrorCode, isUltimateError, renderCauseValue } from '@ultimat3/core';
+import {
+  describeErrorCode,
+  isUltimateError,
+  renderCauseValue,
+  renderFixShellArg,
+  stringField,
+} from '@ultimat3/core';
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
@@ -30,20 +36,31 @@ interface ErrorParts {
 }
 
 export function errorParts(error: unknown): ErrorParts {
-  if (isUltimateError(error)) {
+  // Every field through `stringField`, never `error.code`: a getter or a `Proxy` trap on the value
+  // throws during the READ, and this is the component that renders an error — its throw replaced
+  // the screen reporting one with a blank tree. A field that will not read falls back to the
+  // registry's answer for the code, so the code itself survives whatever else is unreadable.
+  const code = isUltimateError(error) ? stringField(error, 'code') : undefined;
+  if (code !== undefined) {
+    const known = describeErrorCode(code);
     return {
-      code: error.code,
-      title: error.title,
-      cause: error.cause,
-      fix: error.fix,
-      docs: error.docs,
+      code,
+      // The error's own `title` first: a remote code this realm never registered carries the
+      // server's title there (`remoteTitle`), and the registry would only humanise the code.
+      title: stringField(error, 'title') ?? known.title,
+      cause: stringField(error, 'cause') ?? renderCauseValue(error),
+      // Screened: the code came off a value the app (or a wire) built, and a fix is pasted into a
+      // shell. The placeholder is single-quoted so it is inert there, never a `<` redirection.
+      fix:
+        stringField(error, 'fix') ??
+        `x errors explain ${renderFixShellArg(code, "'<the code above>'")}`,
+      docs: stringField(error, 'docs') ?? known.docs,
     };
   }
-  // `props.error` is any thrown value, so `String()` ran the app's own `toString` — and this is the
-  // component that RENDERS an error, so its throw replaced the screen that was reporting one with a
-  // blank tree. Laundering it through a local `message` is exactly what `scripts/error-render.ts`
-  // says it cannot see, which is why this one shipped.
-  const message = error instanceof Error ? error.message : renderCauseValue(error);
+  // `props.error` is any thrown value, so `String()` ran the app's own `toString`. Laundering it
+  // through a local `message` is exactly what `scripts/error-render.ts` says it cannot see, which
+  // is why this one shipped.
+  const message = thrownMessage(error) ?? renderCauseValue(error);
   // Title and docs come from core's registry, never a hand-copy: this screen must read exactly
   // as `x errors explain X_INTERNAL` does, and there is one docs URL for every code.
   const described = describeErrorCode('X_INTERNAL');
@@ -59,6 +76,16 @@ export function errorParts(error: unknown): ErrorParts {
   };
 }
 
+/** An `Error`'s own message, or `undefined` when it is not one or will not be read. */
+function thrownMessage(error: unknown): string | undefined {
+  try {
+    // `instanceof` runs a `Proxy`'s `getPrototypeOf` trap, so the test is inside the guard too.
+    return error instanceof Error ? stringField(error, 'message') : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function ErrorState(props: ErrorStateProps): JSX.Element {
   const ui = useUi();
   const parts = (): ErrorParts => errorParts(props.error);