@workbench-kit/shell-react 0.0.2-prototype.0.2.13 → 0.0.2-prototype.0.2.15

package/README.md

@@ -92,6 +92,21 @@ const flowActionsRef = useRef<FieldRemapFlowActions | null>(null);
 />;
 ```
 
+## Shell chrome labels / `t()`
+
+`WorkbenchShell` accepts optional `labels` and `t(key, fallback)` for high-visibility chrome
+(ActivityBar / StatusBar aria names, Profile/Settings secondary items, command palette).
+English defaults apply when neither is set. See
+`resolveWorkbenchShellChromeLabels` / `workbenchShellChromeLabelKeys` and
+[Consumer Capabilities — Shell chrome label injection](../../docs/workbench/consumer-capabilities.md#shell-chrome-label--t-injection-126).
+
+```tsx
+<WorkbenchShell
+  t={(key, fallback) => hostTranslate(key, fallback)}
+  labels={{ settingsLabel: 'Settings' }}
+/>
+```
+
 ## Related docs
 
 - [Component Map](../../docs/guides/component-map.md)

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@workbench-kit/shell-react",
-  "version": "0.0.2-prototype.0.2.13",
+  "version": "0.0.2-prototype.0.2.15",
   "private": false,
+  "sideEffects": [
+    "**/*.css"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -21,13 +24,13 @@
     "@xyflow/react": "^12.11.2",
     "jsonata": "^2.2.0",
     "react-table-mapping": "^1.0.3",
-    "@workbench-kit/field-remap": "0.0.2-prototype.0.2.13",
-    "@workbench-kit/react": "0.0.2-prototype.0.2.13",
-    "@workbench-kit/platform": "0.0.2-prototype.0.2.13",
-    "@workbench-kit/tokens": "0.0.2-prototype.0.2.13",
-    "@workbench-kit/workbench-core": "0.0.2-prototype.0.2.13",
-    "@workbench-kit/workbench-config": "0.0.2-prototype.0.2.13",
-    "@workbench-kit/workspace": "0.0.2-prototype.0.2.13"
+    "@workbench-kit/platform": "0.0.2-prototype.0.2.15",
+    "@workbench-kit/field-remap": "0.0.2-prototype.0.2.15",
+    "@workbench-kit/tokens": "0.0.2-prototype.0.2.15",
+    "@workbench-kit/react": "0.0.2-prototype.0.2.15",
+    "@workbench-kit/workbench-config": "0.0.2-prototype.0.2.15",
+    "@workbench-kit/workbench-core": "0.0.2-prototype.0.2.15",
+    "@workbench-kit/workspace": "0.0.2-prototype.0.2.15"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/chat/command-error-message.ts

@@ -0,0 +1,7 @@
+export function getCommandErrorMessage(error: unknown) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}

package/src/chat/command-surface.tsx

@@ -6,6 +6,7 @@ import {
   type WorkbenchCommandDescriptor,
 } from '@workbench-kit/react/workbench';
 
+import { getCommandErrorMessage } from './command-error-message.js';
 import { parseWorkbenchChatCommandInput } from './command-input.js';
 import { useWorkbench } from '../shell/provider.js';
 import { useWorkbenchCommandDescriptors } from '../commands/use-command-descriptors.js';
@@ -145,11 +146,3 @@ export function useWorkbenchChatCommandSurface({
     runInputAsCommand,
   };
 }
-
-function getCommandErrorMessage(error: unknown) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-
-  return String(error);
-}

package/src/chat/use-chat-command-proposals.ts

@@ -7,6 +7,7 @@ import {
 } from '@workbench-kit/react/workbench';
 import type { ChatCommandProposal, ChatMessage } from '@workbench-kit/react/workbench/chat';
 
+import { getCommandErrorMessage } from './command-error-message.js';
 import { type WorkbenchChatCommandRunResult } from './command-surface.js';
 import { useWorkbench } from '../shell/provider.js';
 
@@ -24,14 +25,6 @@ export interface UseWorkbenchChatCommandProposalsOptions {
   policyInput?: ResolveWorkbenchCommandExecutionPolicyInput | undefined;
 }
 
-function getCommandErrorMessage(error: unknown) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-
-  return String(error);
-}
-
 function createProposalId(commandId: string) {
   return `proposal-${commandId}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 }

package/src/editor/state-storage.ts

@@ -1,5 +1,4 @@
 import {
-  createBrowserWorkbenchStorage,
   type EditorGroupState,
   type EditorLayoutDirection,
   type EditorLayoutNode,
@@ -10,11 +9,16 @@ import {
 } from '@workbench-kit/workbench-core';
 
 import { isRecord } from '../is-record.js';
+import {
+  readLocalJsonStorage,
+  resolveLocalWorkbenchStorage,
+  writeLocalJsonStorage,
+} from '../storage/local-json-storage.js';
 
 export const DEFAULT_WORKBENCH_EDITOR_STATE_STORAGE_KEY = 'workbench-kit/.workbench/editors';
 
 export function isWorkbenchEditorStatePersistenceAvailable(): boolean {
-  return createBrowserWorkbenchStorage({ kind: 'local' }) !== undefined;
+  return resolveLocalWorkbenchStorage() !== undefined;
 }
 
 export function editorStateToStorageValue(state: EditorState): EditorState {
@@ -42,17 +46,7 @@ export function readPersistedEditorState(
   storageKey = DEFAULT_WORKBENCH_EDITOR_STATE_STORAGE_KEY,
   storage?: WorkbenchStorageReader,
 ): EditorState | undefined {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) return undefined;
-
-  try {
-    const raw = resolvedStorage.getItem(storageKey);
-    if (!raw) return undefined;
-
-    return parseEditorStateStorageValue(JSON.parse(raw) as unknown);
-  } catch {
-    return undefined;
-  }
+  return readLocalJsonStorage(storageKey, parseEditorStateStorageValue, () => undefined, storage);
 }
 
 export function writePersistedEditorState(
@@ -60,14 +54,9 @@ export function writePersistedEditorState(
   storageKey = DEFAULT_WORKBENCH_EDITOR_STATE_STORAGE_KEY,
   storage?: WorkbenchStorageWriter,
 ): void {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) return;
-
-  try {
-    resolvedStorage.setItem(storageKey, JSON.stringify(editorStateToStorageValue(state), null, 2));
-  } catch {
-    // Ignore quota and security errors so the shell keeps working offline.
-  }
+  writeLocalJsonStorage(storageKey, state, storage, {
+    toStorageValue: editorStateToStorageValue,
+  });
 }
 
 function parseEditorStateStorageValue(value: unknown): EditorState | undefined {

package/src/field-remap/convert-note-editor.tsx

@@ -49,10 +49,9 @@ export function ConvertNoteEditor({
 
   const portTypes = useMemo(() => edgePortTypes(edge, sources, targets), [edge, sources, targets]);
 
-  const optionFields = useMemo(
-    () => optionFieldsForStep(transforms, transformId),
-    [transforms, transformId],
-  );
+  // ValueTransformRegistry is intentionally mutable (`register`). Resolve its
+  // display contract on render so a host rerender sees replacement definitions.
+  const optionFields = optionFieldsForStep(transforms, transformId);
 
   const optionValue = useMemo(() => {
     if (!transformId) {
@@ -63,18 +62,14 @@ export function ConvertNoteEditor({
     );
   }, [chain, edge.transformOptionSteps, edge.transformOptions, stepIndex, transformId]);
 
-  const replaceCatalog = useMemo(
-    () =>
-      listCompatibleTransforms({
-        registry: transforms,
-        edge,
-        stepIndex,
-        sourceType: portTypes.sourceType,
-        targetType: portTypes.targetType,
-        mode: 'replace',
-      }),
-    [edge, portTypes.sourceType, portTypes.targetType, stepIndex, transforms],
-  );
+  const replaceCatalog = listCompatibleTransforms({
+    registry: transforms,
+    edge,
+    stepIndex,
+    sourceType: portTypes.sourceType,
+    targetType: portTypes.targetType,
+    mode: 'replace',
+  });
 
   if (!transformId) {
     return null;

package/src/field-remap/convert-palette.tsx

@@ -1,4 +1,4 @@
-import { useMemo, type JSX } from 'react';
+import type { JSX } from 'react';
 import { Button } from '@workbench-kit/react/primitives';
 import type { ValueTransformRegistry } from '@workbench-kit/field-remap';
 
@@ -28,10 +28,9 @@ export function FieldRemapConvertPalette({
   onAddSplit,
   chromeLabels = defaultFieldRemapChromeLabels,
 }: FieldRemapConvertPaletteProps): JSX.Element {
-  const catalog = useMemo(
-    () => transforms.list().filter((definition) => definition.id !== 'identity'),
-    [transforms],
-  );
+  // The registry supports replacing definitions through `register`; resolve
+  // display metadata on each host render even when the registry object is stable.
+  const catalog = transforms.list().filter((definition) => definition.id !== 'identity');
 
   return (
     <aside

package/src/field-remap/flow-sync-key.ts

@@ -0,0 +1,149 @@
+import type { Edge, Node } from '@xyflow/react';
+import type { ValueTransformRegistry } from '@workbench-kit/field-remap';
+
+import type { FieldRemapFlowEdgeData, FieldRemapFlowNodeData } from './flow-adapter.js';
+import type { FieldRemapSelection } from './flow-ops.js';
+
+type GraphSyncToken = string | number | boolean | null | undefined;
+
+function appendToken(parts: string[], value: GraphSyncToken): void {
+  const encoded =
+    value === undefined
+      ? 'undefined'
+      : value === null
+        ? 'null'
+        : `${typeof value}:${String(value)}`;
+  parts.push(`${encoded.length}:${encoded}`);
+}
+
+function appendTransformRegistrySignature(
+  parts: string[],
+  transforms: ValueTransformRegistry,
+): void {
+  const definitions = transforms
+    .list()
+    .slice()
+    .sort((left, right) => left.id.localeCompare(right.id));
+  appendToken(parts, definitions.length);
+  for (const definition of definitions) {
+    appendToken(parts, definition.id);
+    appendToken(parts, definition.label);
+    appendToken(parts, definition.description);
+    appendToken(parts, definition.category);
+    appendToken(parts, definition.outputType);
+    appendToken(parts, definition.inputTypes?.length ?? 0);
+    for (const inputType of definition.inputTypes ?? []) {
+      appendToken(parts, inputType);
+    }
+    appendToken(parts, definition.optionFields?.length ?? 0);
+    for (const option of definition.optionFields ?? []) {
+      appendToken(parts, option.key);
+      appendToken(parts, option.label);
+      appendToken(parts, option.kind);
+    }
+  }
+}
+
+export function createTransformRegistrySignature(transforms: ValueTransformRegistry): string {
+  const parts: string[] = [];
+  appendTransformRegistrySignature(parts, transforms);
+  return parts.join('');
+}
+
+function appendSelection(parts: string[], selection: FieldRemapSelection): void {
+  appendToken(parts, selection?.kind);
+  if (!selection) {
+    return;
+  }
+  if (selection.kind === 'edge' || selection.kind === 'transformStep') {
+    appendToken(parts, selection.edgeId);
+    appendToken(parts, selection.kind === 'transformStep' ? selection.stepIndex : undefined);
+    return;
+  }
+  appendToken(parts, selection.kind === 'draft' ? selection.localId : selection.operatorId);
+}
+
+/**
+ * Stable signature for the controlled values copied into XYFlow's internal node store.
+ * This intentionally lists display fields instead of serializing arbitrary props.
+ */
+export function createFieldRemapGraphSyncKey(input: {
+  readonly nodes: readonly Node<FieldRemapFlowNodeData>[];
+  readonly edges: readonly Edge<FieldRemapFlowEdgeData>[];
+  readonly selection: FieldRemapSelection;
+  readonly transformRegistrySignature: string;
+}): string {
+  const parts: string[] = [];
+  appendToken(parts, input.nodes.length);
+  for (const node of input.nodes) {
+    appendToken(parts, node.id);
+    appendToken(parts, node.type);
+    appendToken(parts, node.position.x);
+    appendToken(parts, node.position.y);
+    appendToken(parts, node.selected);
+
+    const data = node.data;
+    appendToken(parts, data.kind);
+    if (data.kind === 'source-object' || data.kind === 'target-object') {
+      appendToken(parts, data.title);
+      appendToken(parts, data.schemaRole);
+      appendToken(parts, data.ports.length);
+      for (const port of data.ports) {
+        appendToken(parts, port.fieldId);
+        appendToken(parts, port.label);
+        appendToken(parts, port.dataType);
+      }
+      continue;
+    }
+    if (data.kind === 'transform') {
+      appendToken(parts, data.mappingEdgeId);
+      appendToken(parts, data.stepIndex);
+      appendToken(parts, data.transformId);
+      appendToken(parts, data.label);
+      appendToken(parts, data.selected);
+      continue;
+    }
+    if (data.kind === 'draft-transform') {
+      appendToken(parts, data.localId);
+      appendToken(parts, data.transformId);
+      appendToken(parts, data.label);
+      appendToken(parts, data.sourceFieldId);
+      appendToken(parts, data.targetSlotId);
+      continue;
+    }
+    appendToken(parts, data.operatorId);
+    appendToken(parts, data.label);
+    if (data.kind === 'combine-operator') {
+      appendToken(parts, data.inputFieldIds.length);
+      for (const fieldId of data.inputFieldIds) {
+        appendToken(parts, fieldId);
+      }
+      appendToken(parts, data.outputSlotId);
+      continue;
+    }
+    appendToken(parts, data.inputFieldId);
+    appendToken(parts, data.outputSlotIds.length);
+    for (const slotId of data.outputSlotIds) {
+      appendToken(parts, slotId);
+    }
+  }
+
+  appendToken(parts, input.edges.length);
+  for (const edge of input.edges) {
+    appendToken(parts, edge.id);
+    appendToken(parts, edge.type);
+    appendToken(parts, edge.source);
+    appendToken(parts, edge.sourceHandle);
+    appendToken(parts, edge.target);
+    appendToken(parts, edge.targetHandle);
+    appendToken(parts, edge.selected);
+    appendToken(parts, edge.data?.mappingEdgeId);
+    appendToken(parts, edge.data?.draftLocalId);
+    appendToken(parts, edge.data?.operatorId);
+    appendToken(parts, edge.data?.segment);
+  }
+
+  appendSelection(parts, input.selection);
+  appendToken(parts, input.transformRegistrySignature);
+  return parts.join('');
+}

package/src/field-remap/flow.tsx

@@ -60,6 +60,7 @@ import {
   type FieldRemapTargetObjectNodeData,
   type FieldRemapTransformNodeData,
 } from './flow-adapter.js';
+import { createFieldRemapGraphSyncKey, createTransformRegistrySignature } from './flow-sync-key.js';
 import {
   addTransformStepToEdge,
   bindDraftSource,
@@ -414,6 +415,7 @@ function FieldRemapFlowCanvas({
     const first = transforms.list().find((definition) => definition.id !== 'identity');
     return first?.id ?? '';
   });
+  const transformRegistrySignature = createTransformRegistrySignature(transforms);
 
   const graph = useMemo(
     () =>
@@ -427,7 +429,17 @@ function FieldRemapFlowCanvas({
         targetTitle,
         drafts,
       }),
-    [sources, targets, edges, transforms, operators, sourceTitle, targetTitle, drafts],
+    [
+      sources,
+      targets,
+      edges,
+      transforms,
+      operators,
+      sourceTitle,
+      targetTitle,
+      drafts,
+      transformRegistrySignature,
+    ],
   );
 
   const nodesWithSelection = useMemo(
@@ -461,22 +473,15 @@ function FieldRemapFlowCanvas({
   const [nodes, setNodes, onNodesChange] = useNodesState(nodesWithSelection);
   const [flowEdges, setFlowEdges, onFlowEdgesChange] = useEdgesState(graph.edges);
 
-  // Sync controlled graph by topology/selection signature only. Depending on
-  // `nodesWithSelection` (new array each paint) re-enters xyflow StoreUpdater and
-  // can hit "Maximum update depth exceeded" in embed hosts with tight flex layouts.
-  const graphSyncKey = useMemo(
-    () =>
-      [
-        ...graph.nodes.map((node) => node.id),
-        ...graph.edges.map(
-          (edge) =>
-            `${edge.id}:${edge.source}:${edge.target}:${edge.sourceHandle ?? ''}:${edge.targetHandle ?? ''}`,
-        ),
-        selection ? JSON.stringify(selection) : '',
-        ...drafts.map((draft) => draft.localId),
-      ].join('|'),
-    [drafts, graph.edges, graph.nodes, selection],
-  );
+  // Depending directly on `nodesWithSelection` (a new array after each graph
+  // calculation) re-enters XYFlow's StoreUpdater. The explicit signature keeps
+  // that loop guard while still tracking every value copied into rendered nodes.
+  const graphSyncKey = createFieldRemapGraphSyncKey({
+    nodes: nodesWithSelection,
+    edges: graph.edges,
+    selection,
+    transformRegistrySignature,
+  });
   const nodesWithSelectionRef = useRef(nodesWithSelection);
   const graphEdgesRef = useRef(graph.edges);
   nodesWithSelectionRef.current = nodesWithSelection;
@@ -611,7 +616,18 @@ function FieldRemapFlowCanvas({
       onEdgesChange([...withoutTarget, result.edge]);
       setSelection({ kind: 'edge', edgeId: result.edge.id });
     },
-    [connectionContext, drafts, edges, onEdgesChange, setSelection, sources, targets, transforms],
+    [
+      connectionContext,
+      drafts,
+      edges,
+      onEdgesChange,
+      onOperatorsChange,
+      operators,
+      setSelection,
+      sources,
+      targets,
+      transforms,
+    ],
   );
 
   const onEdgesDelete = useCallback(
@@ -694,7 +710,7 @@ function FieldRemapFlowCanvas({
         stepIndex: data.stepIndex,
       });
     },
-    [edges, onEdgesChange, setSelection],
+    [edges, onEdgesChange, onOperatorsChange, operators, selection, setSelection],
   );
 
   const onKeyDown = useCallback(

package/src/field-remap/samples.ts

@@ -31,12 +31,6 @@ export interface FieldRemapSampleDefinition {
   readonly operators?: readonly MappingOperator[];
 }
 
-/** Alias kept so older URIs still open a known sample. */
-export const FIELD_REMAP_LEGACY_SAMPLE_ALIASES: Readonly<Record<string, FieldRemapSampleId>> = {
-  'interactive-bindings': 'nested-ab',
-  't-order-invoice': 't-event-time',
-};
-
 export const FIELD_REMAP_SAMPLES: readonly FieldRemapSampleDefinition[] = [
   {
     id: 'nested-ab',
@@ -386,14 +380,7 @@ export function isFieldRemapSampleId(value: string): value is FieldRemapSampleId
 }
 
 export function resolveFieldRemapSampleId(value: string | undefined): FieldRemapSampleId {
-  if (!value) {
-    return 'nested-ab';
-  }
-  const aliased = FIELD_REMAP_LEGACY_SAMPLE_ALIASES[value];
-  if (aliased) {
-    return aliased;
-  }
-  if (isFieldRemapSampleId(value)) {
+  if (value && isFieldRemapSampleId(value)) {
     return value;
   }
   return 'nested-ab';

package/src/field-remap/view.css

@@ -331,7 +331,11 @@
   display: flex;
   flex-direction: column;
   gap: 0.65rem;
+  box-sizing: border-box;
   min-width: 0;
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
   padding: 0.75rem;
   border: 1px solid var(--vscode-panel-border, var(--color-border));
   border-radius: 0.375rem;
@@ -354,14 +358,21 @@
   color: var(--vscode-descriptionForeground, var(--color-text-muted));
 }
 
+.workbench-field-remap-convert-palette__header,
+.workbench-field-remap-convert-palette__place,
+.workbench-field-remap-convert-palette__operators {
+  flex: 0 0 auto;
+}
+
 .workbench-field-remap-convert-palette__list {
   list-style: none;
   margin: 0;
   padding: 0;
   display: flex;
+  flex: 1 1 auto;
   flex-direction: column;
   gap: 0.35rem;
-  max-height: min(22rem, 45vh);
+  min-height: 0;
   overflow: auto;
 }
 

package/src/index.ts

@@ -286,6 +286,14 @@ export {
   type WorkbenchSecondaryActivityItemsInput,
   type WorkbenchSecondaryActivityRoute,
 } from './shell/secondary-actions.js';
+export {
+  defaultWorkbenchShellChromeLabels,
+  resolveWorkbenchShellChromeLabels,
+  workbenchShellChromeLabelKeys,
+  type WorkbenchI18n,
+  type WorkbenchShellChromeLabels,
+  type WorkbenchTranslate,
+} from './shell/chrome-labels.js';
 export {
   WorkbenchProfileModal,
   type WorkbenchProfileDetail,

package/src/management/keybinding-overrides-storage.ts

@@ -3,36 +3,27 @@ import {
   type WorkbenchKeybindingDefinition,
 } from '@workbench-kit/workbench-config';
 import {
-  createBrowserWorkbenchStorage,
   type WorkbenchStorageReader,
   type WorkbenchStorageWriter,
 } from '@workbench-kit/workbench-core';
 
+import {
+  readLocalJsonStorage,
+  resolveLocalWorkbenchStorage,
+  writeLocalJsonStorage,
+} from '../storage/local-json-storage.js';
+
 export const DEFAULT_WORKBENCH_KEYBINDING_STORAGE_KEY = 'workbench-kit/.workbench/keybindings';
 
 export function isWorkbenchKeybindingPersistenceAvailable(): boolean {
-  return createBrowserWorkbenchStorage({ kind: 'local' }) !== undefined;
+  return resolveLocalWorkbenchStorage() !== undefined;
 }
 
 export function readPersistedKeybindingOverrides(
   storageKey = DEFAULT_WORKBENCH_KEYBINDING_STORAGE_KEY,
   storage?: WorkbenchStorageReader,
 ): readonly WorkbenchKeybindingDefinition[] {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) {
-    return [];
-  }
-
-  try {
-    const raw = resolvedStorage.getItem(storageKey);
-    if (!raw) {
-      return [];
-    }
-
-    return parseWorkbenchKeybindingsConfig(JSON.parse(raw) as unknown);
-  } catch {
-    return [];
-  }
+  return readLocalJsonStorage(storageKey, parseWorkbenchKeybindingsConfig, () => [], storage);
 }
 
 export function writePersistedKeybindingOverrides(
@@ -40,10 +31,5 @@ export function writePersistedKeybindingOverrides(
   storageKey = DEFAULT_WORKBENCH_KEYBINDING_STORAGE_KEY,
   storage?: WorkbenchStorageWriter,
 ): void {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) {
-    return;
-  }
-
-  resolvedStorage.setItem(storageKey, JSON.stringify(overrides, null, 2));
+  writeLocalJsonStorage(storageKey, overrides, storage, { errorMode: 'throw' });
 }

package/src/management/preference-settings-storage.ts

@@ -3,37 +3,28 @@ import {
   type WorkbenchSettingsConfig,
 } from '@workbench-kit/workbench-config';
 import {
-  createBrowserWorkbenchStorage,
   type WorkbenchStorageReader,
   type WorkbenchStorageWriter,
 } from '@workbench-kit/workbench-core';
 
+import {
+  readLocalJsonStorage,
+  resolveLocalWorkbenchStorage,
+  writeLocalJsonStorage,
+} from '../storage/local-json-storage.js';
+
 export const DEFAULT_WORKBENCH_LOCAL_PREFERENCE_STORAGE_KEY =
   'workbench-kit/.workbench/settings.local';
 
 export function isWorkbenchLocalPreferencePersistenceAvailable(): boolean {
-  return createBrowserWorkbenchStorage({ kind: 'local' }) !== undefined;
+  return resolveLocalWorkbenchStorage() !== undefined;
 }
 
 export function readPersistedLocalPreferences(
   storageKey = DEFAULT_WORKBENCH_LOCAL_PREFERENCE_STORAGE_KEY,
   storage?: WorkbenchStorageReader,
 ): WorkbenchSettingsConfig {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) {
-    return {};
-  }
-
-  try {
-    const raw = resolvedStorage.getItem(storageKey);
-    if (!raw) {
-      return {};
-    }
-
-    return parseWorkbenchSettingsConfig(JSON.parse(raw) as unknown);
-  } catch {
-    return {};
-  }
+  return readLocalJsonStorage(storageKey, parseWorkbenchSettingsConfig, () => ({}), storage);
 }
 
 export function writePersistedLocalPreferences(
@@ -41,10 +32,5 @@ export function writePersistedLocalPreferences(
   storageKey = DEFAULT_WORKBENCH_LOCAL_PREFERENCE_STORAGE_KEY,
   storage?: WorkbenchStorageWriter,
 ): void {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) {
-    return;
-  }
-
-  resolvedStorage.setItem(storageKey, JSON.stringify(values, null, 2));
+  writeLocalJsonStorage(storageKey, values, storage, { errorMode: 'throw' });
 }