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

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@workbench-kit/shell-react",
-  "version": "0.0.2-prototype.0.2.14",
+  "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.14",
-    "@workbench-kit/tokens": "0.0.2-prototype.0.2.14",
-    "@workbench-kit/workbench-config": "0.0.2-prototype.0.2.14",
-    "@workbench-kit/workbench-core": "0.0.2-prototype.0.2.14",
-    "@workbench-kit/workspace": "0.0.2-prototype.0.2.14",
-    "@workbench-kit/react": "0.0.2-prototype.0.2.14",
-    "@workbench-kit/platform": "0.0.2-prototype.0.2.14"
+    "@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/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/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' });
 }

package/src/storage/local-json-storage.ts

@@ -0,0 +1,66 @@
+import {
+  createBrowserWorkbenchStorage,
+  type WorkbenchStorageAdapter,
+  type WorkbenchStorageReader,
+  type WorkbenchStorageWriter,
+} from '@workbench-kit/workbench-core';
+
+export function resolveLocalWorkbenchStorage<
+  TStorage extends WorkbenchStorageReader | WorkbenchStorageWriter = WorkbenchStorageAdapter,
+>(storage?: TStorage): TStorage | WorkbenchStorageAdapter | undefined {
+  return storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
+}
+
+export function readLocalJsonStorage<T>(
+  storageKey: string,
+  parse: (value: unknown) => T,
+  fallback: () => T,
+  storage?: WorkbenchStorageReader,
+): T {
+  const resolvedStorage = resolveLocalWorkbenchStorage(storage);
+  if (!resolvedStorage) {
+    return fallback();
+  }
+
+  try {
+    const raw = resolvedStorage.getItem(storageKey);
+    if (!raw) {
+      return fallback();
+    }
+
+    return parse(JSON.parse(raw) as unknown);
+  } catch {
+    return fallback();
+  }
+}
+
+export function writeLocalJsonStorage<T>(
+  storageKey: string,
+  value: T,
+  storage?: WorkbenchStorageWriter,
+  options: {
+    readonly errorMode?: 'ignore' | 'throw';
+    readonly toStorageValue?: (value: T) => unknown;
+  } = {},
+): void {
+  const resolvedStorage = resolveLocalWorkbenchStorage(storage);
+  if (!resolvedStorage) {
+    return;
+  }
+
+  try {
+    resolvedStorage.setItem(
+      storageKey,
+      JSON.stringify((options.toStorageValue ?? identity)(value), null, 2),
+    );
+  } catch (error) {
+    if (options.errorMode === 'throw') {
+      throw error;
+    }
+    // Local storage is best-effort; quota, security, and serialization errors stay non-fatal.
+  }
+}
+
+function identity<T>(value: T): T {
+  return value;
+}

package/src/workbench/appearance-storage.ts

@@ -7,11 +7,16 @@ import {
   type WorkbenchColorSchemePreference,
 } from '@workbench-kit/react/workbench';
 import {
-  createBrowserWorkbenchStorage,
   type WorkbenchStorageReader,
   type WorkbenchStorageWriter,
 } from '@workbench-kit/workbench-core';
 
+import {
+  readLocalJsonStorage,
+  resolveLocalWorkbenchStorage,
+  writeLocalJsonStorage,
+} from '../storage/local-json-storage.js';
+
 export type { WorkbenchAppearanceSettings } from '@workbench-kit/react/workbench/themePresets';
 
 export const DEFAULT_WORKBENCH_APPEARANCE_STORAGE_KEY = 'workbench-kit/.workbench/appearance';
@@ -24,28 +29,19 @@ export const DEFAULT_WORKBENCH_APPEARANCE: WorkbenchAppearanceSettings = {
 };
 
 export function isWorkbenchAppearancePersistenceAvailable(): boolean {
-  return createBrowserWorkbenchStorage({ kind: 'local' }) !== undefined;
+  return resolveLocalWorkbenchStorage() !== undefined;
 }
 
 export function readPersistedWorkbenchAppearance(
   storageKey = DEFAULT_WORKBENCH_APPEARANCE_STORAGE_KEY,
   storage?: WorkbenchStorageReader,
 ): WorkbenchAppearanceSettings {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) {
-    return DEFAULT_WORKBENCH_APPEARANCE;
-  }
-
-  try {
-    const raw = resolvedStorage.getItem(storageKey);
-    if (!raw) {
-      return DEFAULT_WORKBENCH_APPEARANCE;
-    }
-
-    return normalizeWorkbenchAppearance(JSON.parse(raw) as unknown);
-  } catch {
-    return DEFAULT_WORKBENCH_APPEARANCE;
-  }
+  return readLocalJsonStorage(
+    storageKey,
+    normalizeWorkbenchAppearance,
+    () => DEFAULT_WORKBENCH_APPEARANCE,
+    storage,
+  );
 }
 
 export function writePersistedWorkbenchAppearance(
@@ -53,16 +49,7 @@ export function writePersistedWorkbenchAppearance(
   storageKey = DEFAULT_WORKBENCH_APPEARANCE_STORAGE_KEY,
   storage?: WorkbenchStorageWriter,
 ): void {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) {
-    return;
-  }
-
-  try {
-    resolvedStorage.setItem(storageKey, JSON.stringify(settings, null, 2));
-  } catch {
-    // Ignore quota and security errors so the shell keeps working offline.
-  }
+  writeLocalJsonStorage(storageKey, settings, storage);
 }
 
 function normalizeWorkbenchAppearance(value: unknown): WorkbenchAppearanceSettings {

package/src/workbench/layout-storage.ts

@@ -3,7 +3,6 @@ import {
   type WorkbenchLayoutConfig,
 } from '@workbench-kit/workbench-config';
 import {
-  createBrowserWorkbenchStorage,
   createWorkbenchLayoutState,
   type WorkbenchStorageReader,
   type WorkbenchStorageWriter,
@@ -11,10 +10,16 @@ import {
   type WorkbenchLayoutStateInput,
 } from '@workbench-kit/workbench-core';
 
+import {
+  readLocalJsonStorage,
+  resolveLocalWorkbenchStorage,
+  writeLocalJsonStorage,
+} from '../storage/local-json-storage.js';
+
 export const DEFAULT_WORKBENCH_LAYOUT_STORAGE_KEY = 'workbench-kit/.workbench/layout';
 
 export function isWorkbenchLayoutPersistenceAvailable(): boolean {
-  return createBrowserWorkbenchStorage({ kind: 'local' }) !== undefined;
+  return resolveLocalWorkbenchStorage() !== undefined;
 }
 
 export function workbenchLayoutConfigToInput(
@@ -81,17 +86,12 @@ export function readPersistedWorkbenchLayout(
   storageKey = DEFAULT_WORKBENCH_LAYOUT_STORAGE_KEY,
   storage?: WorkbenchStorageReader,
 ): WorkbenchLayoutStateInput | undefined {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) return undefined;
-
-  try {
-    const raw = resolvedStorage.getItem(storageKey);
-    if (!raw) return undefined;
-
-    return workbenchLayoutConfigToInput(parseWorkbenchLayoutConfig(JSON.parse(raw) as unknown));
-  } catch {
-    return undefined;
-  }
+  return readLocalJsonStorage(
+    storageKey,
+    (value) => workbenchLayoutConfigToInput(parseWorkbenchLayoutConfig(value)),
+    () => undefined,
+    storage,
+  );
 }
 
 export function writePersistedWorkbenchLayout(
@@ -99,17 +99,9 @@ export function writePersistedWorkbenchLayout(
   storageKey = DEFAULT_WORKBENCH_LAYOUT_STORAGE_KEY,
   storage?: WorkbenchStorageWriter,
 ): void {
-  const resolvedStorage = storage ?? createBrowserWorkbenchStorage({ kind: 'local' });
-  if (!resolvedStorage) return;
-
-  try {
-    resolvedStorage.setItem(
-      storageKey,
-      JSON.stringify(workbenchLayoutStateToStorageValue(state), null, 2),
-    );
-  } catch {
-    // Ignore quota and security errors so the shell keeps working offline.
-  }
+  writeLocalJsonStorage(storageKey, state, storage, {
+    toStorageValue: workbenchLayoutStateToStorageValue,
+  });
 }
 
 export function resolvePersistedWorkbenchLayout(