@workbench-kit/shell-react 0.0.2-prototype.0.2.32 → 0.0.2-prototype.0.2.34

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

@@ -1,10 +1,20 @@
 import {
   createBrowserWorkbenchStorage,
+  readWorkbenchStorageJsonResult,
+  writeWorkbenchStorageJsonResult,
+  type WorkbenchPersistenceDiagnosticOptions,
+  type WorkbenchPersistenceReadResult,
+  type WorkbenchPersistenceWriteResult,
   type WorkbenchStorageAdapter,
   type WorkbenchStorageReader,
   type WorkbenchStorageWriter,
 } from '@workbench-kit/workbench-core';
 
+export interface WriteLocalJsonStorageOptions<T> extends WorkbenchPersistenceDiagnosticOptions {
+  readonly errorMode?: 'ignore' | 'throw';
+  readonly toStorageValue?: (value: T) => unknown;
+}
+
 export function resolveLocalWorkbenchStorage<
   TStorage extends WorkbenchStorageReader | WorkbenchStorageWriter = WorkbenchStorageAdapter,
 >(storage?: TStorage): TStorage | WorkbenchStorageAdapter | undefined {
@@ -16,49 +26,53 @@ export function readLocalJsonStorage<T>(
   parse: (value: unknown) => T,
   fallback: () => T,
   storage?: WorkbenchStorageReader,
+  options: WorkbenchPersistenceDiagnosticOptions = {},
 ): T {
-  const resolvedStorage = resolveLocalWorkbenchStorage(storage);
-  if (!resolvedStorage) {
-    return fallback();
-  }
-
-  try {
-    const raw = resolvedStorage.getItem(storageKey);
-    if (!raw) {
-      return fallback();
-    }
+  return readLocalJsonStorageResult(storageKey, parse, fallback, storage, options).value;
+}
 
-    return parse(JSON.parse(raw) as unknown);
-  } catch {
-    return fallback();
-  }
+export function readLocalJsonStorageResult<T>(
+  storageKey: string,
+  parse: (value: unknown) => T,
+  fallback: () => T,
+  storage?: WorkbenchStorageReader,
+  options: WorkbenchPersistenceDiagnosticOptions = {},
+): WorkbenchPersistenceReadResult<T> {
+  return readWorkbenchStorageJsonResult(storageKey, parse, fallback, storage, options);
 }
 
 export function writeLocalJsonStorage<T>(
   storageKey: string,
   value: T,
   storage?: WorkbenchStorageWriter,
-  options: {
-    readonly errorMode?: 'ignore' | 'throw';
-    readonly toStorageValue?: (value: T) => unknown;
-  } = {},
+  options: WriteLocalJsonStorageOptions<T> = {},
 ): void {
+  if (options.errorMode !== 'throw') {
+    writeLocalJsonStorageResult(storageKey, value, storage, options);
+    return;
+  }
+
   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.
-  }
+  resolvedStorage.setItem(
+    storageKey,
+    JSON.stringify((options.toStorageValue ?? identity)(value), null, 2),
+  );
+}
+
+export function writeLocalJsonStorageResult<T>(
+  storageKey: string,
+  value: T,
+  storage?: WorkbenchStorageWriter,
+  options: WriteLocalJsonStorageOptions<T> = {},
+): WorkbenchPersistenceWriteResult {
+  return writeWorkbenchStorageJsonResult(storageKey, value, storage, {
+    onDiagnostic: options.onDiagnostic,
+    toStorageValue: options.toStorageValue,
+  });
 }
 
 function identity<T>(value: T): T {

package/src/storage/persistence-diagnostics.ts

@@ -0,0 +1,72 @@
+import { useEffect, useRef, type MutableRefObject } from 'react';
+import type {
+  WorkbenchPersistenceDiagnostic,
+  WorkbenchPersistenceDiagnosticHandler,
+  WorkbenchPersistenceWriteResult,
+} from '@workbench-kit/workbench-core';
+
+export type WorkbenchPersistenceDiagnosticHandlerRef = MutableRefObject<
+  WorkbenchPersistenceDiagnosticHandler | undefined
+>;
+
+export function usePersistenceDiagnosticHandlerRef(
+  onDiagnostic: WorkbenchPersistenceDiagnosticHandler | undefined,
+): WorkbenchPersistenceDiagnosticHandlerRef {
+  const handlerRef = useRef(onDiagnostic);
+
+  useEffect(() => {
+    handlerRef.current = onDiagnostic;
+  }, [onDiagnostic]);
+
+  return handlerRef;
+}
+
+export function useReportPersistenceReadDiagnostic(
+  diagnostic: WorkbenchPersistenceDiagnostic | undefined,
+  generation: readonly unknown[],
+  handlerRef: WorkbenchPersistenceDiagnosticHandlerRef,
+): void {
+  const lastGenerationRef = useRef<readonly unknown[] | undefined>(undefined);
+
+  useEffect(() => {
+    if (isSameGeneration(lastGenerationRef.current, generation)) {
+      return;
+    }
+
+    lastGenerationRef.current = [...generation];
+    if (diagnostic) {
+      reportPersistenceDiagnostic(diagnostic, handlerRef);
+    }
+  }, [diagnostic, generation, handlerRef]);
+}
+
+export function reportPersistenceWriteResult(
+  result: WorkbenchPersistenceWriteResult,
+  handlerRef: WorkbenchPersistenceDiagnosticHandlerRef,
+): void {
+  if (!result.committed) {
+    reportPersistenceDiagnostic(result.diagnostic, handlerRef);
+  }
+}
+
+export function reportPersistenceDiagnostic(
+  diagnostic: WorkbenchPersistenceDiagnostic,
+  handlerRef: WorkbenchPersistenceDiagnosticHandlerRef,
+): void {
+  try {
+    handlerRef.current?.(diagnostic);
+  } catch {
+    // Diagnostics are observational and must not change runtime state.
+  }
+}
+
+function isSameGeneration(
+  left: readonly unknown[] | undefined,
+  right: readonly unknown[],
+): boolean {
+  return (
+    left !== undefined &&
+    left.length === right.length &&
+    left.every((value, index) => Object.is(value, right[index]))
+  );
+}

package/src/workbench/appearance-storage.ts

@@ -7,14 +7,19 @@ import {
   type WorkbenchColorSchemePreference,
 } from '@workbench-kit/react/workbench';
 import {
+  type WorkbenchPersistenceDiagnosticOptions,
+  type WorkbenchPersistenceReadResult,
+  type WorkbenchPersistenceWriteResult,
   type WorkbenchStorageReader,
   type WorkbenchStorageWriter,
 } from '@workbench-kit/workbench-core';
 
 import {
   readLocalJsonStorage,
+  readLocalJsonStorageResult,
   resolveLocalWorkbenchStorage,
   writeLocalJsonStorage,
+  writeLocalJsonStorageResult,
 } from '../storage/local-json-storage.js';
 
 export type { WorkbenchAppearanceSettings } from '@workbench-kit/react/workbench/themePresets';
@@ -44,6 +49,20 @@ export function readPersistedWorkbenchAppearance(
   );
 }
 
+export function readPersistedWorkbenchAppearanceResult(
+  storageKey = DEFAULT_WORKBENCH_APPEARANCE_STORAGE_KEY,
+  storage?: WorkbenchStorageReader,
+  options: WorkbenchPersistenceDiagnosticOptions = {},
+): WorkbenchPersistenceReadResult<WorkbenchAppearanceSettings> {
+  return readLocalJsonStorageResult(
+    storageKey,
+    normalizeWorkbenchAppearance,
+    () => DEFAULT_WORKBENCH_APPEARANCE,
+    storage,
+    options,
+  );
+}
+
 export function writePersistedWorkbenchAppearance(
   settings: WorkbenchAppearanceSettings,
   storageKey = DEFAULT_WORKBENCH_APPEARANCE_STORAGE_KEY,
@@ -52,6 +71,15 @@ export function writePersistedWorkbenchAppearance(
   writeLocalJsonStorage(storageKey, settings, storage);
 }
 
+export function writePersistedWorkbenchAppearanceResult(
+  settings: WorkbenchAppearanceSettings,
+  storageKey = DEFAULT_WORKBENCH_APPEARANCE_STORAGE_KEY,
+  storage?: WorkbenchStorageWriter,
+  options: WorkbenchPersistenceDiagnosticOptions = {},
+): WorkbenchPersistenceWriteResult {
+  return writeLocalJsonStorageResult(storageKey, settings, storage, options);
+}
+
 function normalizeWorkbenchAppearance(value: unknown): WorkbenchAppearanceSettings {
   if (typeof value !== 'object' || value === null) {
     return DEFAULT_WORKBENCH_APPEARANCE;

package/src/workbench/command-host.tsx

@@ -101,11 +101,15 @@ export function WorkbenchCommandHost({
   quickOpenTitle = 'Quick Open',
 }: WorkbenchCommandHostProps) {
   const {
+    activities,
+    commands,
     contextKeyService,
     executeCommand,
-    extensionRegistry,
+    extensionCatalog,
+    keybindings,
     keybindingOverrides,
     layoutService,
+    views,
     workspaceHostPort,
   } = useWorkbench();
   const [paletteOpen, setPaletteOpen] = useState(false);
@@ -136,12 +140,12 @@ export function WorkbenchCommandHost({
   }, [layoutService]);
 
   const managedShellActivities = useMemo(
-    () => resolveShellCommandActivities(extensionRegistry),
-    [extensionRegistry],
+    () => resolveShellCommandActivities({ activities, views }),
+    [activities, views],
   );
   const visibleShellActivities = useMemo(
-    () => resolveShellCommandActivities(extensionRegistry, contextKeySnapshot),
-    [contextKeySnapshot, extensionRegistry],
+    () => resolveShellCommandActivities({ activities, views }, contextKeySnapshot),
+    [activities, contextKeySnapshot, views],
   );
   const visibleShellActivityIdSet = new Set(visibleShellActivities.map((activity) => activity.id));
   const visibleShellActivitySignature = managedShellActivities
@@ -203,7 +207,7 @@ export function WorkbenchCommandHost({
 
   useEffect(() => {
     const registration = registerWorkbenchShellCommandHandlers(
-      extensionRegistry.commands,
+      commands,
       shellCommandDefinitions,
       () => {
         const context = shellContextRef.current;
@@ -218,14 +222,16 @@ export function WorkbenchCommandHost({
     return () => {
       registration.dispose();
     };
-  }, [extensionRegistry.commands, shellCommandDefinitions]);
+  }, [commands, shellCommandDefinitions]);
 
   const paletteCommands = useMemo(
     () =>
       buildWorkbenchPaletteCommands({
         additionalCommands,
-        extensionCommandFeaturesById: collectExtensionCommandFeaturesById(extensionRegistry),
-        extensionCommands: extensionRegistry.commands
+        extensionCommandFeaturesById: collectExtensionCommandFeaturesById(
+          extensionCatalog.getFeatureSpecs(),
+        ),
+        extensionCommands: commands
           .getCommands()
           .filter((command) => !managedShellCommandIds.has(command.id)),
         shellCommands: shellCommandDefinitions,
@@ -233,7 +239,8 @@ export function WorkbenchCommandHost({
       }),
     [
       additionalCommands,
-      extensionRegistry,
+      commands,
+      extensionCatalog,
       managedShellCommandIds,
       shellContext,
       shellCommandDefinitions,
@@ -356,12 +363,7 @@ export function WorkbenchCommandHost({
         return;
       }
 
-      const match = resolveExtensionKeybindingCommand(
-        extensionRegistry.keybindings,
-        event,
-        {},
-        keybindingOverrides,
-      );
+      const match = resolveExtensionKeybindingCommand(keybindings, event, {}, keybindingOverrides);
       if (!match) {
         return;
       }
@@ -374,12 +376,7 @@ export function WorkbenchCommandHost({
     return () => {
       window.removeEventListener('keydown', onKeyDown);
     };
-  }, [
-    enableExtensionKeybindings,
-    executeCommand,
-    extensionRegistry.keybindings,
-    keybindingOverrides,
-  ]);
+  }, [enableExtensionKeybindings, executeCommand, keybindings, keybindingOverrides]);
 
   return (
     <>

package/src/workbench/command-palette.ts

@@ -7,10 +7,13 @@ import type {
 import {
   filterActivitiesByWhenClause,
   type ExtensionCommandFeatureSpec,
-  type ExtensionRegistry,
+  type ActivityRegistry,
+  type ExtensionFeatureSpec,
+  type ViewRegistry,
 } from '@workbench-kit/workbench-core';
+import type { CommandRegistry } from '@workbench-kit/platform';
 
-type ExtensionCommand = ReturnType<ExtensionRegistry['commands']['getCommands']>[number];
+type ExtensionCommand = ReturnType<CommandRegistry['getCommands']>[number];
 
 function resolveCommandValue<TContext, TValue>(
   value: CommandDefinition<TContext>[keyof CommandDefinition<TContext>],
@@ -44,10 +47,10 @@ export function resolveExtensionCommandIcon(icon: ExtensionCommand['icon']): str
 }
 
 export function resolveShellCommandActivities(
-  extensionRegistry: ExtensionRegistry,
+  registries: { readonly activities: ActivityRegistry; readonly views: ViewRegistry },
   contextKeys?: object | undefined,
 ): WorkbenchShellCommandActivity[] {
-  const activities = extensionRegistry.activities.getActivities();
+  const activities = registries.activities.getActivities();
   if (activities.length > 0) {
     const visibleActivities =
       contextKeys === undefined
@@ -63,13 +66,11 @@ export function resolveShellCommandActivities(
       .sort((left, right) => left.label.localeCompare(right.label));
   }
 
-  const viewContainerIds = new Set(
-    extensionRegistry.views.getViews().map((view) => view.containerId),
-  );
+  const viewContainerIds = new Set(registries.views.getViews().map((view) => view.containerId));
 
   return [...viewContainerIds].map((containerId) => {
-    const container = extensionRegistry.views.getViewContainer(containerId);
-    const firstView = extensionRegistry.views.getViews(containerId)[0];
+    const container = registries.views.getViewContainer(containerId);
+    const firstView = registries.views.getViews(containerId)[0];
 
     return {
       icon: formatWorkbenchCommandIcon(container?.icon ?? 'files'),
@@ -125,12 +126,12 @@ export function extensionCommandToDescriptor(
 }
 
 export function collectExtensionCommandFeaturesById(
-  extensionRegistry: ExtensionRegistry,
+  featureSpecs: readonly ExtensionFeatureSpec[],
 ): ReadonlyMap<string, ExtensionCommandFeatureSpec> {
   return new Map(
-    extensionRegistry
-      .getFeatureSpecs()
-      .flatMap((feature) => feature.commands.map((command) => [command.id, command] as const)),
+    featureSpecs.flatMap((feature) =>
+      feature.commands.map((command) => [command.id, command] as const),
+    ),
   );
 }
 

package/src/workbench/layout-storage.ts

@@ -7,6 +7,11 @@ import {
   type WorkbenchLayoutState,
   type WorkbenchLayoutStateInput,
 } from '@workbench-kit/workbench-core/layout';
+import type {
+  WorkbenchPersistenceDiagnosticOptions,
+  WorkbenchPersistenceReadResult,
+  WorkbenchPersistenceWriteResult,
+} from '@workbench-kit/workbench-core';
 import type {
   WorkbenchStorageReader,
   WorkbenchStorageWriter,
@@ -14,8 +19,10 @@ import type {
 
 import {
   readLocalJsonStorage,
+  readLocalJsonStorageResult,
   resolveLocalWorkbenchStorage,
   writeLocalJsonStorage,
+  writeLocalJsonStorageResult,
 } from '../storage/local-json-storage.js';
 
 export const DEFAULT_WORKBENCH_LAYOUT_STORAGE_KEY = 'workbench-kit/.workbench/layout';
@@ -96,6 +103,20 @@ export function readPersistedWorkbenchLayout(
   );
 }
 
+export function readPersistedWorkbenchLayoutResult(
+  storageKey = DEFAULT_WORKBENCH_LAYOUT_STORAGE_KEY,
+  storage?: WorkbenchStorageReader,
+  options: WorkbenchPersistenceDiagnosticOptions = {},
+): WorkbenchPersistenceReadResult<WorkbenchLayoutStateInput | undefined> {
+  return readLocalJsonStorageResult(
+    storageKey,
+    (value) => workbenchLayoutConfigToInput(parseWorkbenchLayoutConfig(value)),
+    () => undefined,
+    storage,
+    options,
+  );
+}
+
 export function writePersistedWorkbenchLayout(
   state: WorkbenchLayoutState,
   storageKey = DEFAULT_WORKBENCH_LAYOUT_STORAGE_KEY,
@@ -106,6 +127,18 @@ export function writePersistedWorkbenchLayout(
   });
 }
 
+export function writePersistedWorkbenchLayoutResult(
+  state: WorkbenchLayoutState,
+  storageKey = DEFAULT_WORKBENCH_LAYOUT_STORAGE_KEY,
+  storage?: WorkbenchStorageWriter,
+  options: WorkbenchPersistenceDiagnosticOptions = {},
+): WorkbenchPersistenceWriteResult {
+  return writeLocalJsonStorageResult(storageKey, state, storage, {
+    ...options,
+    toStorageValue: workbenchLayoutStateToStorageValue,
+  });
+}
+
 export function resolvePersistedWorkbenchLayout(
   initialLayout: WorkbenchLayoutStateInput | undefined,
   options: {
@@ -114,6 +147,17 @@ export function resolvePersistedWorkbenchLayout(
     storageKey?: string | undefined;
   } = {},
 ): WorkbenchLayoutStateInput | undefined {
+  return resolvePersistedWorkbenchLayoutResult(initialLayout, options).value;
+}
+
+export function resolvePersistedWorkbenchLayoutResult(
+  initialLayout: WorkbenchLayoutStateInput | undefined,
+  options: {
+    persistLayout?: boolean | undefined;
+    storage?: WorkbenchStorageReader | undefined;
+    storageKey?: string | undefined;
+  } = {},
+): WorkbenchPersistenceReadResult<WorkbenchLayoutStateInput | undefined> {
   const {
     initialLayout: baseLayout,
     persistLayout = options.storage !== undefined || isWorkbenchLayoutPersistenceAvailable(),
@@ -122,13 +166,16 @@ export function resolvePersistedWorkbenchLayout(
   } = { initialLayout, ...options };
 
   if (!persistLayout) {
-    return baseLayout;
+    return { value: baseLayout };
   }
 
-  const persisted = readPersistedWorkbenchLayout(storageKey, storage);
-  if (!persisted) {
-    return baseLayout;
+  const result = readPersistedWorkbenchLayoutResult(storageKey, storage);
+  if (!result.value) {
+    return { ...result, value: baseLayout };
   }
 
-  return createWorkbenchLayoutState(persisted, createWorkbenchLayoutState(baseLayout ?? {}));
+  return {
+    ...result,
+    value: createWorkbenchLayoutState(result.value, createWorkbenchLayoutState(baseLayout ?? {})),
+  };
 }

package/src/workbench/use-persisted-appearance.ts

@@ -1,33 +1,59 @@
-import { useEffect, useState } from 'react';
-import type { WorkbenchStorageAdapter } from '@workbench-kit/workbench-core';
+import { useCallback, useEffect, useState } from 'react';
+import type {
+  WorkbenchPersistenceDiagnosticHandler,
+  WorkbenchStorageAdapter,
+} from '@workbench-kit/workbench-core';
 
 import {
-  readPersistedWorkbenchAppearance,
-  writePersistedWorkbenchAppearance,
+  readPersistedWorkbenchAppearanceResult,
+  writePersistedWorkbenchAppearanceResult,
   type WorkbenchAppearanceSettings,
 } from './appearance-storage.js';
+import {
+  reportPersistenceWriteResult,
+  usePersistenceDiagnosticHandlerRef,
+  useReportPersistenceReadDiagnostic,
+} from '../storage/persistence-diagnostics.js';
 
 export interface UsePersistedWorkbenchAppearanceOptions {
+  onPersistenceDiagnostic?: WorkbenchPersistenceDiagnosticHandler | undefined;
   persist?: boolean | undefined;
   storage?: WorkbenchStorageAdapter | undefined;
   storageKey?: string | undefined;
 }
 
+interface PersistedWorkbenchAppearanceState {
+  readonly appearance: WorkbenchAppearanceSettings;
+  readonly writeEligible: boolean;
+}
+
 export function usePersistedWorkbenchAppearance(
   options: UsePersistedWorkbenchAppearanceOptions = {},
 ): [WorkbenchAppearanceSettings, (settings: WorkbenchAppearanceSettings) => void] {
-  const { persist = true, storage, storageKey } = options;
-  const [appearance, setAppearance] = useState(() =>
-    readPersistedWorkbenchAppearance(storageKey, storage),
-  );
+  const { onPersistenceDiagnostic, persist = true, storage, storageKey } = options;
+  const [initialRead] = useState(() => readPersistedWorkbenchAppearanceResult(storageKey, storage));
+  const [state, setState] = useState<PersistedWorkbenchAppearanceState>(() => ({
+    appearance: initialRead.value,
+    writeEligible: initialRead.diagnostic === undefined,
+  }));
+  const diagnosticHandlerRef = usePersistenceDiagnosticHandlerRef(onPersistenceDiagnostic);
+
+  useReportPersistenceReadDiagnostic(initialRead.diagnostic, [], diagnosticHandlerRef);
 
   useEffect(() => {
-    if (!persist) {
+    if (!persist || !state.writeEligible) {
       return;
     }
 
-    writePersistedWorkbenchAppearance(appearance, storageKey, storage);
-  }, [appearance, persist, storage, storageKey]);
+    reportPersistenceWriteResult(
+      writePersistedWorkbenchAppearanceResult(state.appearance, storageKey, storage),
+      diagnosticHandlerRef,
+    );
+  }, [diagnosticHandlerRef, persist, state, storage, storageKey]);
+
+  const setAppearance = useCallback((appearance: WorkbenchAppearanceSettings) => {
+    setState({ appearance, writeEligible: true });
+  }, []);
 
-  return [appearance, setAppearance];
+  return [state.appearance, setAppearance];
 }