@startsimpli/ui 0.4.112 → 0.4.114

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.112",
+  "version": "0.4.114",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -47,9 +47,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
+    "@startsimpli/api": "^0.5.58",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/api": "^0.5.58"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/collection/ReviewDrawer.tsx

@@ -79,7 +79,15 @@ export interface ReviewDrawerProps {
     /** Refetch the parent + return to review mode. */
     saved: () => void;
   }) => ReactNode;
-  /** App-specific extra content under the record (e.g. a topic's drafts). Optional. */
+  /**
+   * App-specific extra content under the record (e.g. a topic's drafts).
+   * Optional.
+   *
+   * Handed the record AS DECIDED — the drawer's optimistic `data`, not the
+   * `record` prop (bd startsim-t1t1k). An extra slot is where a consumer puts
+   * the action a decision UNLOCKS, so it is the one place that most needs to
+   * see the decision that was just made.
+   */
   renderExtra?: (record: EntityRecord, type: EntityTypeDef) => ReactNode;
 }
 
@@ -119,6 +127,18 @@ function ReviewDrawerInner({
   const title = fieldStr(data, cfg.titleAttr) || record.name || `#${record.id}`;
   const summary = fieldStr(data, cfg.summaryAttr);
   const rank = fieldStr(data, cfg.rankAttr);
+  /**
+   * The record AS DECIDED — the `record` prop carrying this drawer's own
+   * optimistic `data` (bd startsim-t1t1k).
+   *
+   * Everything else here already renders from `data`; `renderExtra` was the one
+   * slot still reading the untouched prop, so a consumer affordance gated on
+   * status (OGMC's "Generate drafts", legal only once the topic is approved)
+   * kept reading the PRE-decision status and kept refusing. The parent's
+   * refetch cannot fix that on its own — it invalidates a list, while the
+   * drawer holds a record object the parent chose before the decision existed.
+   */
+  const decided = useMemo(() => ({ ...record, data }), [record, data]);
 
   /** Merge changes into the (camelCased) blob and PATCH; the backend REPLACES data. */
   async function patch(changes: Record<string, unknown>, key: string, advance = false) {
@@ -304,7 +324,9 @@ function ReviewDrawerInner({
 
               <ReviewSources data={data} sourceAttrs={cfg.sourceAttrs} tierByHost={sourceTierByHost} />
 
-              {renderExtra ? <div className="mt-6 border-t border-border pt-4">{renderExtra(record, type)}</div> : null}
+              {renderExtra ? (
+                <div className="mt-6 border-t border-border pt-4">{renderExtra(decided, type)}</div>
+              ) : null}
             </div>
 
             <footer className="space-y-3 border-t border-border px-4 py-3">

package/src/components/collection/__tests__/approve-unlocks.test.tsx

@@ -0,0 +1,169 @@
+/**
+ * Approving a record must leave the reviewer standing on the record they
+ * approved, holding whatever the approval unlocked (bd startsim-t1t1k).
+ *
+ * The report, verbatim: "To create a draft, you first have to approve the
+ * Topic, then click out of the window, refresh the page, filter the 'Ready'
+ * topics, find the same topic, click approve again and then it generates
+ * drafts." Six steps to reach a button that should have been one — and the
+ * second approve writes nothing new, so what the reload actually bought was a
+ * FRESH RECORD.
+ *
+ * Two independent mechanisms in this component produced that, and both are
+ * pinned below:
+ *
+ *   1. THE EXTRA SLOT SAW A STALE RECORD. Every other thing the drawer renders
+ *      — heading, meta chips, the status Select, which decision reads as active
+ *      — is derived from the optimistic `data` a decision writes. `renderExtra`
+ *      alone was handed the untouched `record` prop, so the consumer's
+ *      follow-on affordance (OGMC's "Generate drafts", gated on
+ *      status === the approve status) kept reading the PRE-approval status and
+ *      kept refusing. Exactly the state a page reload cures.
+ *   2. THE DRAWER MOVED ON. Approve auto-advances, so even once the gate opened
+ *      it opened on a record that was no longer on screen.
+ *
+ * Neither test asserts a colour or a class: they assert that the thing the
+ * approval unlocked is reachable, for the record that was approved.
+ */
+import * as React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { ReviewDrawer } from '../ReviewDrawer';
+import { readData } from '../data';
+import type { CollectionClient, EntityRecord, EntityTypeDef, Paginated } from '../types';
+
+const TOPIC_TYPE: EntityTypeDef = {
+  id: 1,
+  key: 'topic',
+  label: 'Topic',
+  attributes: [
+    {
+      id: 'status',
+      name: 'status',
+      dataType: 'enum',
+      required: false,
+      config: { choices: ['suggested', 'ready', 'written', 'rejected'] },
+    },
+    { id: 'title', name: 'title', dataType: 'text', required: false, config: {} },
+  ],
+};
+
+function topic(id: number, title: string): EntityRecord {
+  return {
+    id,
+    entityType: 'topic',
+    externalId: null,
+    name: title,
+    data: { title, status: 'suggested' },
+    createdAt: '2026-09-01T00:00:00Z',
+  };
+}
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results };
+}
+
+function stubClient(): CollectionClient & { updateEntity: jest.Mock } {
+  const updateEntity = jest.fn(async (id: number | string, input: { data?: Record<string, unknown> }) => ({
+    ...topic(Number(id), 'x'),
+    data: input.data ?? {},
+  }));
+  return {
+    listTypes: jest.fn(async () => page([TOPIC_TYPE])),
+    listAllEntities: jest.fn(async () => []),
+    updateEntity,
+  } as CollectionClient & { updateEntity: jest.Mock };
+}
+
+/**
+ * The consumer's follow-on affordance, standing in for OGMC's "Generate
+ * drafts": legal only once the record has reached the approve status, and it
+ * says WHY when it is not — a disabled control the reader cannot explain is the
+ * same defect in another shape.
+ */
+function GenerateStub(record: EntityRecord) {
+  const approved = String(readData(record.data, 'status') ?? '') === 'ready';
+  return approved ? (
+    <button type="button">Generate drafts</button>
+  ) : (
+    <span>Approve this topic to generate drafts.</span>
+  );
+}
+
+function renderDrawer(overrides: Partial<React.ComponentProps<typeof ReviewDrawer>> = {}) {
+  const client = stubClient();
+  const onNavigate = jest.fn();
+  const onSaved = jest.fn();
+  const first = topic(1, 'Desalination in Riyadh');
+  const utils = render(
+    <ReviewDrawer
+      client={client}
+      type={TOPIC_TYPE}
+      records={[first, topic(2, 'A different topic entirely')]}
+      record={first}
+      onClose={jest.fn()}
+      onNavigate={onNavigate}
+      onSaved={onSaved}
+      renderExtra={GenerateStub}
+      {...overrides}
+    />,
+  );
+  return { ...utils, client, onNavigate, onSaved, first };
+}
+
+describe('approving a topic unlocks its follow-on action in place', () => {
+  it('hands renderExtra the record AS DECIDED, not the stale prop', async () => {
+    const user = userEvent.setup();
+    const { client } = renderDrawer({ config: { holdAfter: ['approve'] } });
+
+    // Before: the follow-on is refused, in words.
+    expect(screen.getByText('Approve this topic to generate drafts.')).toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', { name: /Approve/ }));
+
+    // The write itself carries the coherent pair the pipeline reads.
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalled());
+    expect(client.updateEntity.mock.calls[0][1].data).toMatchObject({
+      status: 'ready',
+      teamVerdict: 'good',
+    });
+
+    // And the drawer's extra slot reflects it WITHOUT a refetch, a reopen, or a
+    // second approve — the parent has not sent a new `record` prop at all.
+    expect(await screen.findByRole('button', { name: 'Generate drafts' })).toBeInTheDocument();
+    expect(screen.queryByText('Approve this topic to generate drafts.')).not.toBeInTheDocument();
+  });
+
+  it('stays on the approved record when the consumer holds that decision', async () => {
+    const user = userEvent.setup();
+    const { onNavigate, onSaved } = renderDrawer({ config: { holdAfter: ['approve'] } });
+
+    await user.click(screen.getByRole('button', { name: /Approve/ }));
+
+    await waitFor(() => expect(onSaved).toHaveBeenCalled());
+    expect(onNavigate).not.toHaveBeenCalled();
+    // The heading is still the topic that was decided, not the next one.
+    expect(screen.getByRole('heading', { name: 'Desalination in Riyadh' })).toBeInTheDocument();
+  });
+
+  it('still advances after a decision the consumer did NOT hold', async () => {
+    const user = userEvent.setup();
+    const { onNavigate } = renderDrawer({ config: { holdAfter: ['approve'] } });
+
+    await user.click(screen.getByRole('button', { name: /Reject/ }));
+
+    await waitFor(() => expect(onNavigate).toHaveBeenCalled());
+    expect(onNavigate.mock.calls[0][0].id).toBe(2);
+  });
+
+  it('advances after Approve for a consumer that holds nothing (unchanged default)', async () => {
+    const user = userEvent.setup();
+    const { onNavigate } = renderDrawer();
+
+    await user.click(screen.getByRole('button', { name: /Approve/ }));
+
+    await waitFor(() => expect(onNavigate).toHaveBeenCalled());
+    expect(onNavigate.mock.calls[0][0].id).toBe(2);
+  });
+});

package/src/components/collection/__tests__/review.test.ts

@@ -284,3 +284,62 @@ describe('decision labels are the consumer’s to name', () => {
     );
   });
 });
+
+/**
+ * A decision that UNLOCKS a next action on the same record must not scroll that
+ * record off the screen (bd startsim-t1t1k).
+ *
+ * On OGMC, approving a topic is what makes "Generate drafts" legal for it. The
+ * drawer then auto-advanced to the next topic, so the control the approval had
+ * just unlocked appeared for a record nobody was looking at — and the reviewer's
+ * six-step workaround (close, reload, filter to Ready, find it again, approve a
+ * second time) is what she reported. Rejecting has no such follow-on, so it
+ * still advances: this is opt-in, per decision key, and every type that does not
+ * ask for it is byte-identical.
+ */
+describe('holdAfter — decisions that stay on the record', () => {
+  const type = {
+    id: 't',
+    key: 'topic',
+    label: 'Topic',
+    attributes: [
+      {
+        id: 'a',
+        name: 'status',
+        dataType: 'enum' as const,
+        required: false,
+        config: { choices: ['suggested', 'ready', 'written', 'rejected'] },
+      },
+    ],
+  };
+
+  it('advances after every decision when nothing is held (today’s behaviour)', () => {
+    const byKey = Object.fromEntries(
+      reviewDecisions(resolveReviewConfig(type)).map((d) => [d.key, d.advance]),
+    );
+    expect(byKey.approve).toBe(true);
+    expect(byKey.reject).toBe(true);
+    // "Needs work" already holds — it is meant to be revisited.
+    expect(byKey.needs_work).toBe(false);
+  });
+
+  it('holds the named decision and leaves the others advancing', () => {
+    const cfg = resolveReviewConfig(type, { holdAfter: ['approve'] });
+    const byKey = Object.fromEntries(reviewDecisions(cfg).map((d) => [d.key, d.advance]));
+    expect(byKey.approve).toBe(false);
+    expect(byKey.reject).toBe(true);
+  });
+
+  it('changes ONLY whether the queue moves on — never what gets written', () => {
+    const plain = reviewDecisions(resolveReviewConfig(type));
+    const held = reviewDecisions(resolveReviewConfig(type, { holdAfter: ['approve', 'reject'] }));
+    expect(held.map((d) => [d.key, d.label, d.status, d.verdict, d.tone, d.shortcut])).toEqual(
+      plain.map((d) => [d.key, d.label, d.status, d.verdict, d.tone, d.shortcut]),
+    );
+  });
+
+  it('resolves to an empty hold list when the consumer supplies none', () => {
+    expect(resolveReviewConfig(type).holdAfter).toEqual([]);
+    expect(resolveReviewConfig(type, { holdAfter: ['approve'] }).holdAfter).toEqual(['approve']);
+  });
+});

package/src/components/collection/review.ts

@@ -186,6 +186,24 @@ export interface ReviewConfig {
    * unchanged, so nothing that does not pass this renders differently.
    */
   decisionLabels?: Record<string, string>;
+  /**
+   * Decision keys after which the drawer STAYS on the record instead of
+   * auto-advancing to the next one. Default: none (every decision behaves
+   * exactly as it does today).
+   *
+   * WHY THIS EXISTS (bd startsim-t1t1k). Auto-advance is right for pure triage
+   * — decide, move on — but wrong for a decision that UNLOCKS a next action on
+   * the same record. On OGMC, approving a topic is precisely what makes
+   * "Generate drafts" legal for it; advancing scrolled the newly-legal control
+   * off the screen, and the reviewer's workaround was to close the drawer,
+   * reload, filter to Ready, find the topic again and approve it a second time.
+   * Six steps, and the second approve wrote nothing — what the reload bought
+   * was a fresh record.
+   *
+   * Only the consumer knows whether one of its decisions has a follow-on, so
+   * this is theirs to declare. Rejecting has none, so it keeps advancing.
+   */
+  holdAfter?: string[];
 }
 
 export interface ResolvedReview {
@@ -203,6 +221,7 @@ export interface ResolvedReview {
   sourceAttrs: string[];
   omitNeedsWork: boolean;
   decisionLabels: Record<string, string>;
+  holdAfter: string[];
 }
 
 const DEFAULT_SOURCE_ATTRS = ['source_1', 'source_2', 'source_3', 'sources'];
@@ -235,6 +254,7 @@ export function resolveReviewConfig(
     sourceAttrs: (config.sourceAttrs ?? DEFAULT_SOURCE_ATTRS).filter((a) => declared.has(a)),
     omitNeedsWork: config.omitNeedsWork ?? false,
     decisionLabels: config.decisionLabels ?? {},
+    holdAfter: config.holdAfter ?? [],
   };
 }
 
@@ -284,10 +304,15 @@ export interface ReviewDecision {
  * A decision only appears when its status target resolves (or, for Needs work,
  * when there's an entry stage or an edit verdict) — so a two-state or non-workflow
  * enum simply shows fewer buttons instead of guessing.
+ *
+ * `holdAfter` overrides the advance flag per decision key (bd startsim-t1t1k) —
+ * it changes only whether the queue moves on, never what a decision writes.
  */
 export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   const verdictOf = (tone: VerdictTone): string | null =>
     r.verdicts.find((v) => v.tone === tone)?.value ?? null;
+  const held = new Set(r.holdAfter ?? []);
+  const advances = (key: string) => !held.has(key);
   const entry = r.statusChoices[0] ?? null;
   const out: ReviewDecision[] = [];
 
@@ -298,7 +323,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
       status: r.transitions.approve,
       verdict: verdictOf('good'),
       tone: 'good',
-      advance: true,
+      advance: advances('approve'),
       shortcut: 'a',
       promptNote: false,
     });
@@ -325,7 +350,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
       status: r.transitions.reject,
       verdict: verdictOf('bad'),
       tone: 'bad',
-      advance: true,
+      advance: advances('reject'),
       shortcut: 'x',
       promptNote: false,
     });

package/src/components/unified-table/UnifiedTable.tsx

@@ -11,6 +11,7 @@ import { TablePagination } from './components/TablePagination'
 import { StandardTableToolbar } from './components/Toolbar'
 import { Loader2 } from 'lucide-react'
 import { cn } from '../../utils'
+import { reconcileColumnVisibility, readStoredColumnVisibility, isForcedVisible } from './utils/columnVisibility'
 
 export function UnifiedTable<TData>({
   data,
@@ -56,31 +57,38 @@ export function UnifiedTable<TData>({
     return urlState.getURLState()
   }, []) // Only run once on mount
 
-  // Column visibility state
-  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>(() => {
-    // Try to load from localStorage if persistKey is set
-    if (columnVisibilityConfig?.persistKey && typeof window !== 'undefined') {
-      try {
-        const stored = localStorage.getItem(`table-columns-${columnVisibilityConfig.persistKey}`)
-        if (stored) {
-          return JSON.parse(stored)
-        }
-      } catch {
-        // Ignore localStorage errors
-      }
-    }
+  // Column visibility state.
+  //
+  // A stored map is never trusted verbatim: it is reconciled against the
+  // columns actually on screen, so an attribute declared AFTER the user last
+  // saved a choice takes `defaultVisible` instead of being pinned visible for
+  // that one browser (bd startsim-7r2ta). See utils/columnVisibility.ts for the
+  // three rules — absent takes the default, a stored `false` survives,
+  // `alwaysVisible` outranks both.
+  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>(() =>
+    reconcileColumnVisibility(
+      columns,
+      readStoredColumnVisibility(columnVisibilityConfig?.persistKey),
+      columnVisibilityConfig
+    )
+  )
 
-    // Initialize default visibility
-    const initial: ColumnVisibilityState = {}
-    columns.forEach(col => {
-      if (columnVisibilityConfig?.defaultVisible) {
-        initial[col.id] = columnVisibilityConfig.defaultVisible.includes(col.id)
-      } else {
-        initial[col.id] = true // Default all visible
-      }
-    })
-    return initial
-  })
+  // Callers that render before their schema lands (a runtime-declared entity
+  // type, a lazily loaded column set) hand us a short `columns` array for a
+  // render or two, so the reconciliation has to hold for the columns that
+  // arrive later as well. Reading through this memo rather than off state means
+  // a late column is never visible for a frame before being corrected.
+  const resolvedColumnVisibility = useMemo(
+    () => reconcileColumnVisibility(columns, columnVisibility, columnVisibilityConfig),
+    [columns, columnVisibility, columnVisibilityConfig]
+  )
+
+  useEffect(() => {
+    // Identity-stable when nothing changed, so this settles in one pass.
+    if (resolvedColumnVisibility !== columnVisibility) {
+      setColumnVisibility(resolvedColumnVisibility)
+    }
+  }, [resolvedColumnVisibility, columnVisibility])
 
   // Client-side sorting state (used when no external sorting config is provided)
   const [localSort, setLocalSort] = useState<SortState>(() => {
@@ -100,13 +108,13 @@ export function UnifiedTable<TData>({
       try {
         localStorage.setItem(
           `table-columns-${columnVisibilityConfig.persistKey}`,
-          JSON.stringify(columnVisibility)
+          JSON.stringify(resolvedColumnVisibility)
         )
       } catch {
         // Ignore localStorage errors
       }
     }
-  }, [columnVisibility, columnVisibilityConfig?.persistKey])
+  }, [resolvedColumnVisibility, columnVisibilityConfig?.persistKey])
 
   // Toggle column visibility
   const toggleColumnVisibility = useCallback((columnId: string) => {
@@ -114,9 +122,12 @@ export function UnifiedTable<TData>({
     if (columnVisibilityConfig?.alwaysVisible?.includes(columnId)) {
       return
     }
+    // Anything but an explicit `false` is on screen, so that's what a toggle
+    // has to turn off — `!prev[id]` would SHOW a column whose id the map has
+    // yet to learn, which is the very state this component used to render.
     setColumnVisibility(prev => ({
       ...prev,
-      [columnId]: !prev[columnId]
+      [columnId]: prev[columnId] === false
     }))
   }, [columnVisibilityConfig?.alwaysVisible])
 
@@ -125,8 +136,14 @@ export function UnifiedTable<TData>({
     if (!columnVisibilityConfig?.enabled) {
       return columns
     }
-    return columns.filter(col => columnVisibility[col.id] !== false)
-  }, [columns, columnVisibility, columnVisibilityConfig?.enabled])
+    return columns.filter(col =>
+      // "Cannot be hidden" is a promise to the caller, not a default: a stored
+      // map written before the column joined that list must not be able to
+      // drop it, and the picker won't offer it back.
+      isForcedVisible(col, columnVisibilityConfig.alwaysVisible) ||
+      resolvedColumnVisibility[col.id] !== false
+    )
+  }, [columns, resolvedColumnVisibility, columnVisibilityConfig?.enabled, columnVisibilityConfig?.alwaysVisible])
 
   // Get hideable columns for the dropdown
   const hideableColumns = useMemo(() => {
@@ -263,7 +280,7 @@ export function UnifiedTable<TData>({
   // Get current view state for saving
   const getCurrentViewState = useCallback((): Omit<SavedView, 'id' | 'name' | 'createdAt'> => {
     return {
-      columnVisibility: columnVisibilityConfig?.enabled ? columnVisibility : undefined,
+      columnVisibility: columnVisibilityConfig?.enabled ? resolvedColumnVisibility : undefined,
       columnOrder: columnReorderConfig?.enabled ? columnReorder.columnOrder : undefined,
       sortBy: currentSortBy,
       sortDirection: currentSortDirection,
@@ -271,7 +288,7 @@ export function UnifiedTable<TData>({
       pageSize: paginationConfig?.pageSize,
     }
   }, [
-    columnVisibility,
+    resolvedColumnVisibility,
     columnVisibilityConfig?.enabled,
     columnReorder.columnOrder,
     columnReorderConfig?.enabled,
@@ -450,7 +467,7 @@ export function UnifiedTable<TData>({
         searchDebounceMs={searchConfig?.debounceMs}
         columnVisibilityEnabled={columnVisibilityConfig?.enabled}
         hideableColumns={hideableColumns}
-        columnVisibility={columnVisibility}
+        columnVisibility={resolvedColumnVisibility}
         onToggleColumnVisibility={toggleColumnVisibility}
         exportEnabled={exportConfig?.enabled}
         exportData={sortedData}

package/src/components/unified-table/__tests__/integration/column-visibility-persistence.test.tsx

@@ -0,0 +1,234 @@
+/**
+ * A saved column map must not force-show columns declared after it (bd startsim-7r2ta).
+ *
+ * UnifiedTable seeds `columnVisibility` from localStorage and then keeps a
+ * column whose id is missing from that map, because the filter asks
+ * `map[id] !== false` and `undefined !== false`. On a runtime-declared schema —
+ * every foundry tenant — that means every attribute added AFTER a reviewer last
+ * touched the column picker is pinned visible for that reviewer alone, and
+ * invisible to anyone checking in a clean browser.
+ *
+ * The reconciliation has to thread three needles at once:
+ *   1. an id ABSENT from the stored map falls back to `defaultVisible`,
+ *   2. a stored `false` is a deliberate hide and survives,
+ *   3. `alwaysVisible` outranks both.
+ */
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { useState } from 'react'
+import { UnifiedTable } from '../../index'
+import { ColumnConfig } from '../../types'
+
+interface Row {
+  id: string
+  name: string
+}
+
+const rows: Row[] = [{ id: '1', name: 'Alpha' }]
+
+const NAME: ColumnConfig<Row> = { id: 'name', header: 'Name', accessorKey: 'name' }
+const STATUS: ColumnConfig<Row> = { id: 'status', header: 'Status', accessorKey: 'status' }
+const SCOPE: ColumnConfig<Row> = { id: 'scope_path', header: 'Scope path', accessorKey: 'scope_path' }
+const ACTIONS: ColumnConfig<Row> = { id: '__actions', header: 'Actions' }
+
+const PERSIST_KEY = 'records-topic'
+const STORAGE_KEY = `table-columns-${PERSIST_KEY}`
+
+function seedStoredMap(map: Record<string, boolean>) {
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(map))
+}
+
+function readStoredMap(): Record<string, boolean> {
+  return JSON.parse(window.localStorage.getItem(STORAGE_KEY) ?? '{}')
+}
+
+/** Only the headers of the rendered grid — the column picker lists them too. */
+function headers(): string[] {
+  return within(screen.getByRole('table'))
+    .getAllByRole('columnheader')
+    .map((th) => th.textContent?.trim() ?? '')
+}
+
+beforeEach(() => {
+  window.localStorage.clear()
+})
+
+describe('a stored column map is reconciled against the current columns', () => {
+  it('hides a column the stored map never heard of when defaults exclude it', () => {
+    // The reviewer saved a choice back when the type had name + status. Since
+    // then the schema grew a scope_path attribute, which the app does NOT
+    // default on.
+    seedStoredMap({ name: true, status: true })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status'])
+  })
+
+  it('still shows an unheard-of column when the caller defaults everything on', () => {
+    // No defaultVisible => "all visible" is the documented default, so an
+    // absent id must stay visible. The fix must not turn absence into a hide.
+    seedStoredMap({ name: true })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{ enabled: true, persistKey: PERSIST_KEY }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Scope path'])
+  })
+
+  it('keeps a deliberate hide the user saved', () => {
+    // status is in defaultVisible, but the stored map says false. Persistence
+    // exists precisely so that choice outlives the default.
+    seedStoredMap({ name: true, status: false })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name'])
+  })
+
+  it('overrides a stored hide of an always-visible column', () => {
+    // The caller added __actions to alwaysVisible after this user had hidden
+    // it (or the column was renamed into the always-visible set). An
+    // always-visible column that the table drops takes the row actions with it.
+    seedStoredMap({ name: false, status: true, __actions: false })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, ACTIONS]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name', '__actions'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Actions'])
+  })
+
+  it('shows an always-visible column that defaultVisible forgot', () => {
+    // Nothing stored at all: the seed path must not let a defaultVisible list
+    // that omits an always-visible id hide it.
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, ACTIONS]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name', '__actions'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Actions'])
+  })
+
+  it('keeps a hideable:false column that the defaults leave out', () => {
+    // `hideable: false` is already excluded from the column picker, so a
+    // reconciliation that hid one would strand it: off the table and off the
+    // menu that puts it back.
+    const pinned: ColumnConfig<Row> = { ...SCOPE, hideable: false }
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, pinned]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Scope path'])
+  })
+})
+
+describe('columns that arrive after mount', () => {
+  function LateSchema() {
+    const [cols, setCols] = useState<ColumnConfig<Row>[]>([NAME])
+    return (
+      <>
+        <button onClick={() => setCols([NAME, STATUS, SCOPE])}>load schema</button>
+        <UnifiedTable<Row>
+          data={rows}
+          columns={cols}
+          tableId="records"
+          getRowId={(r) => r.id}
+          columnVisibility={{
+            enabled: true,
+            alwaysVisible: ['name'],
+            defaultVisible: ['name', 'status'],
+            persistKey: PERSIST_KEY,
+          }}
+        />
+      </>
+    )
+  }
+
+  it('reconciles a column the table had not been handed at mount', () => {
+    seedStoredMap({ name: true, status: true })
+    render(<LateSchema />)
+
+    fireEvent.click(screen.getByText('load schema'))
+
+    expect(headers()).toEqual(['Name', 'Status'])
+  })
+
+  it('does not wipe a saved hide for a column that has not arrived yet', () => {
+    // Reconciling by rebuilding the map from `columns` alone would drop
+    // status:false while the schema is still in flight, and the persist effect
+    // would write that loss straight back to localStorage.
+    seedStoredMap({ name: true, status: false })
+    render(<LateSchema />)
+
+    expect(readStoredMap().status).toBe(false)
+
+    fireEvent.click(screen.getByText('load schema'))
+
+    expect(readStoredMap().status).toBe(false)
+    expect(headers()).toEqual(['Name'])
+  })
+})

package/src/components/unified-table/__tests__/utils/column-visibility.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Unit cover for the reconciliation UnifiedTable applies to a stored column
+ * map (bd startsim-7r2ta). The integration test pins the rendered result; this
+ * pins the rules themselves, including the cases a rendered table can't easily
+ * show — an id the current schema no longer declares, a corrupt stored value.
+ */
+import { reconcileColumnVisibility } from '../../utils/columnVisibility'
+
+const cols = [{ id: 'name' }, { id: 'status' }, { id: 'scope_path' }]
+
+describe('reconcileColumnVisibility', () => {
+  it('falls an unknown id back to defaultVisible, not to visible', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: true, status: true }, {
+        enabled: true,
+        defaultVisible: ['name', 'status'],
+      })
+    ).toEqual({ name: true, status: true, scope_path: false })
+  })
+
+  it('treats "no defaultVisible" as all-visible for unknown ids', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: true }, { enabled: true })
+    ).toEqual({ name: true, status: true, scope_path: true })
+  })
+
+  it('preserves a stored false even when the defaults say otherwise', () => {
+    expect(
+      reconcileColumnVisibility(cols, { status: false }, {
+        enabled: true,
+        defaultVisible: ['name', 'status', 'scope_path'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: true })
+  })
+
+  it('forces an always-visible column on over a stored hide', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: false, status: false }, {
+        enabled: true,
+        alwaysVisible: ['name'],
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false })
+  })
+
+  it('forces an always-visible column on when defaultVisible omits it', () => {
+    expect(
+      reconcileColumnVisibility([...cols, { id: '__actions' }], null, {
+        enabled: true,
+        alwaysVisible: ['__actions'],
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false, __actions: true })
+  })
+
+  it('keeps a stored choice for a column the current schema has not declared', () => {
+    // Mid-flight schemas hand the table a short `columns` array. Rebuilding the
+    // map from `columns` alone would drop the hide, and the persist effect
+    // would write that loss back to localStorage.
+    expect(
+      reconcileColumnVisibility([{ id: 'name' }], { name: true, status: false }, {
+        enabled: true,
+        defaultVisible: ['name', 'status'],
+      })
+    ).toEqual({ name: true, status: false })
+  })
+
+  it('ignores non-boolean values in a corrupt stored map', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: 'yes', status: null } as never, {
+        enabled: true,
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false })
+  })
+
+  it('returns the same object when nothing needs reconciling', () => {
+    // The mount-time seed feeds this straight into setState on every columns
+    // change; a fresh object every time would loop.
+    const stored = { name: true, status: false, scope_path: false }
+    expect(
+      reconcileColumnVisibility(cols, stored, { enabled: true, defaultVisible: ['name'] })
+    ).toBe(stored)
+  })
+
+  it('forces a hideable:false column on, since the picker will not offer it back', () => {
+    // Same promise as alwaysVisible, and the one the caller is likelier to get
+    // wrong: hiding such a column leaves the user no way to restore it.
+    expect(
+      reconcileColumnVisibility(
+        [{ id: 'name' }, { id: 'status' }, { id: 'scope_path', hideable: false }],
+        { name: true, scope_path: false },
+        { enabled: true, defaultVisible: ['name'] }
+      )
+    ).toEqual({ name: true, status: false, scope_path: true })
+  })
+})

package/src/components/unified-table/utils/columnVisibility.ts

@@ -0,0 +1,105 @@
+import { ColumnVisibilityConfig, ColumnVisibilityState } from '../types'
+
+/** The two fields of a column this reconciliation reads. */
+export interface ReconcilableColumn {
+  id: string
+  /** `false` is the same promise as listing the id in `alwaysVisible`. */
+  hideable?: boolean
+}
+
+/**
+ * Column visibility persists as a map of column id -> boolean, and the table
+ * treats a MISSING id as visible (`map[id] !== false`). That is the right
+ * reading for a fresh browser, and the wrong one for a stored map: a schema
+ * declared at runtime — every foundry tenant — grows attributes after a
+ * reviewer last saved a column choice, and each new one lands outside the
+ * stored map and is therefore pinned on for that reviewer alone, invisible to
+ * anyone checking in a clean session. Bumping the persist key clears it once
+ * and the next attribute brings it back (bd startsim-7r2ta).
+ *
+ * So a stored map is reconciled against the columns actually on screen:
+ *
+ *   - an id the stored map has never heard of takes `defaultVisible`
+ *     (or stays visible when the caller declared no defaults at all),
+ *   - a stored `false` is a deliberate hide and is left alone — that is the
+ *     entire point of persisting,
+ *   - `alwaysVisible` outranks both, so neither a stale stored `false` nor a
+ *     `defaultVisible` list that forgot the id can drop the name column or the
+ *     row-actions column. `hideable: false` carries the same promise and is
+ *     forced the same way: the column picker already refuses to list such a
+ *     column, so hiding one would leave the user no way to bring it back.
+ *
+ * Ids the current `columns` no longer declare are carried through untouched.
+ * A caller that renders before its schema arrives hands us a short column list
+ * for a render or two, and rebuilding the map from `columns` alone would erase
+ * the user's saved hides in that window — and the persist effect would then
+ * write the loss back to localStorage.
+ *
+ * Returns the `stored` object itself when nothing needed changing, so callers
+ * can feed the result straight back into `setState` without looping.
+ */
+export function reconcileColumnVisibility(
+  columns: ReconcilableColumn[],
+  stored: ColumnVisibilityState | null | undefined,
+  config?: ColumnVisibilityConfig
+): ColumnVisibilityState {
+  const { defaultVisible, alwaysVisible } = config ?? {}
+
+  const next: ColumnVisibilityState = {}
+  let changed = false
+
+  // Carry the stored choices forward. A non-boolean is a corrupt entry (hand-
+  // edited storage, an older shape) and is treated as absent.
+  for (const [id, value] of Object.entries(stored ?? {})) {
+    if (typeof value === 'boolean') next[id] = value
+    else changed = true
+  }
+
+  for (const col of columns) {
+    const id = col.id
+    const desired = isForcedVisible(col, alwaysVisible)
+      ? true
+      : id in next
+        ? next[id]
+        : defaultVisible
+          ? defaultVisible.includes(id)
+          : true
+    if (next[id] !== desired) {
+      next[id] = desired
+      changed = true
+    }
+  }
+
+  return stored && !changed ? stored : next
+}
+
+/**
+ * A column the user is not allowed to hide — which therefore must not end up
+ * hidden by a stale stored map or by a `defaultVisible` list that omits it.
+ */
+export function isForcedVisible(
+  column: ReconcilableColumn,
+  alwaysVisible: string[] | undefined
+): boolean {
+  return column.hideable === false || !!alwaysVisible?.includes(column.id)
+}
+
+/**
+ * The persisted half of the above: read the map UnifiedTable wrote for
+ * `persistKey`, tolerating a browser that has no localStorage (SSR, privacy
+ * mode) and a value that no longer parses.
+ */
+export function readStoredColumnVisibility(
+  persistKey: string | undefined
+): ColumnVisibilityState | null {
+  if (!persistKey || typeof window === 'undefined') return null
+  try {
+    const stored = window.localStorage.getItem(`table-columns-${persistKey}`)
+    if (!stored) return null
+    const parsed = JSON.parse(stored)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return parsed as ColumnVisibilityState
+  } catch {
+    return null
+  }
+}

package/src/components/unified-table/utils/index.ts

@@ -2,3 +2,4 @@ export * from './renderers'
 export * from './themes'
 export * from './validation'
 export * from './export'
+export * from './columnVisibility'