@rozenite/storage-plugin 1.13.0 → 2.1.0

package/src/ui/__tests__/binary.test.ts

@@ -5,7 +5,9 @@ import {
   bytesToBase64,
   bytesToGroupedHex,
   bytesToHexdump,
+  compactAsciiPreview,
   compactBufferPreview,
+  formatHexdumpRow,
   hexInputToBytes,
 } from '../binary';
 
@@ -24,8 +26,8 @@ describe('bytesToGroupedHex', () => {
   it('inserts a double-space gap between bytes 8 and 9', () => {
     expect(
       bytesToGroupedHex([
-        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d,
-        0x49, 0x48, 0x44, 0x52,
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
+        0x52,
       ]),
     ).toBe('89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52');
   });
@@ -42,17 +44,7 @@ describe('bytesToGroupedHex', () => {
 
 describe('bytesToHexdump', () => {
   it('renders offset, grouped hex, and ASCII column', () => {
-    const bytes = [
-      ...PNG_SIGNATURE,
-      0x00,
-      0x00,
-      0x00,
-      0x0d,
-      0x49,
-      0x48,
-      0x44,
-      0x52,
-    ];
+    const bytes = [...PNG_SIGNATURE, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52];
     expect(bytesToHexdump(bytes)).toBe(
       '00000000  89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52  |.PNG........IHDR|',
     );
@@ -69,9 +61,7 @@ describe('bytesToHexdump', () => {
     const bytes = [0x41, 0x42, 0x43];
     const line = bytesToHexdump(bytes);
     // Hex section width must be exactly 48 chars before the "  |..." block.
-    expect(line).toBe(
-      '00000000  41 42 43                                          |ABC|',
-    );
+    expect(line).toBe('00000000  41 42 43                                          |ABC|');
   });
 
   it('renders non-printable bytes as dots in the ASCII column', () => {
@@ -80,6 +70,16 @@ describe('bytesToHexdump', () => {
   });
 });
 
+describe('formatHexdumpRow', () => {
+  it('formats one requested row without requiring a complete hexdump', () => {
+    expect(formatHexdumpRow(new Array(32).fill(0x41), 16)).toEqual({
+      offset: '00000010',
+      hex: '41 41 41 41 41 41 41 41  41 41 41 41 41 41 41 41',
+      ascii: 'AAAAAAAAAAAAAAAA',
+    });
+  });
+});
+
 describe('bytesToAsciiPreview', () => {
   it('maps printable bytes to characters', () => {
     expect(bytesToAsciiPreview([0x48, 0x69])).toBe('Hi');
@@ -94,6 +94,12 @@ describe('bytesToAsciiPreview', () => {
   });
 });
 
+describe('compactAsciiPreview', () => {
+  it('only converts the visible prefix of a large buffer', () => {
+    expect(compactAsciiPreview(new Array(128).fill(0x41), 4)).toBe('AAAA…');
+  });
+});
+
 describe('bytesToBase64 / base64ToBytes round-trip', () => {
   it('encodes simple ASCII to base64 and back', () => {
     const bytes = [0x48, 0x65, 0x6c, 0x6c, 0x6f]; // "Hello"
@@ -141,21 +147,15 @@ describe('compactBufferPreview', () => {
   });
 
   it('omits the ellipsis when the buffer fits within maxBytes', () => {
-    expect(compactBufferPreview([0x89, 0x50, 0x4e, 0x47])).toBe(
-      '89 50 4E 47 4 B',
-    );
+    expect(compactBufferPreview([0x89, 0x50, 0x4e, 0x47])).toBe('89 50 4E 47 4 B');
   });
 
   it('includes an ellipsis when truncated', () => {
-    expect(compactBufferPreview(new Array(128).fill(0xab))).toBe(
-      'AB AB AB AB AB AB AB AB … 128 B',
-    );
+    expect(compactBufferPreview(new Array(128).fill(0xab))).toBe('AB AB AB AB AB AB AB AB … 128 B');
   });
 
   it('respects a custom maxBytes', () => {
-    expect(compactBufferPreview([0x01, 0x02, 0x03], { maxBytes: 2 })).toBe(
-      '01 02 … 3 B',
-    );
+    expect(compactBufferPreview([0x01, 0x02, 0x03], { maxBytes: 2 })).toBe('01 02 … 3 B');
   });
 });
 
@@ -176,14 +176,12 @@ describe('hexInputToBytes', () => {
 
   it('parses multiline grouped hex', () => {
     expect(
-      hexInputToBytes(
-        '89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52\n00 00 00 20 00 00 00 20',
-      ),
+      hexInputToBytes('89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52\n00 00 00 20 00 00 00 20'),
     ).toEqual({
       ok: true,
       value: [
-        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d,
-        0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, 0x20,
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
+        0x52, 0x00, 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, 0x20,
       ],
     });
   });
@@ -196,9 +194,9 @@ describe('hexInputToBytes', () => {
     expect(hexInputToBytes(pasted)).toEqual({
       ok: true,
       value: [
-        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d,
-        0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, 0x20,
-        0x08, 0x06, 0x00, 0x00, 0x00, 0x73, 0x7a, 0x7a,
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
+        0x52, 0x00, 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, 0x20, 0x08, 0x06, 0x00, 0x00, 0x00, 0x73,
+        0x7a, 0x7a,
       ],
     });
   });

package/src/ui/__tests__/large-value-viewer-state.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { TEXT_CHUNK_SIZE, textRowRanges } from '../large-value-viewer-state';
+
+describe('textRowRanges', () => {
+  it('indexes chunks without splitting a pathological single line', () => {
+    const value = 'x'.repeat(TEXT_CHUNK_SIZE * 2 + 7);
+
+    expect(textRowRanges(value)).toEqual([
+      [0, TEXT_CHUNK_SIZE],
+      [TEXT_CHUNK_SIZE, TEXT_CHUNK_SIZE * 2],
+      [TEXT_CHUNK_SIZE * 2, value.length],
+    ]);
+  });
+
+  it('keeps newline boundaries in their displayed row', () => {
+    expect(textRowRanges('first\nsecond')).toEqual([
+      [0, 6],
+      [6, 12],
+    ]);
+  });
+});

package/src/ui/__tests__/large-value-viewer.test.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { TEXT_CHUNK_SIZE, VIRTUALIZED_TEXT_THRESHOLD } from '../large-value-viewer-state';
+
+vi.mock('react-virtuoso', async () => {
+  const React = await import('react');
+  return {
+    Virtuoso: ({ totalCount, itemContent, ...props }: any) =>
+      React.createElement(
+        'div',
+        { ...props, 'data-testid': 'virtuoso' },
+        Array.from({ length: Math.min(totalCount, 4) }, (_, index) =>
+          React.createElement('div', { key: index }, itemContent(index)),
+        ),
+      ),
+  };
+});
+
+import { HexdumpValueViewer, TextValueViewer } from '../large-value-viewer';
+
+describe('large value viewers', () => {
+  afterEach(cleanup);
+
+  it('renders only virtualized chunks for a large single-line string', () => {
+    const value = 'x'.repeat(VIRTUALIZED_TEXT_THRESHOLD + TEXT_CHUNK_SIZE);
+    const { container } = render(<TextValueViewer value={value} />);
+
+    expect(screen.getByTestId('virtuoso')).toBeInTheDocument();
+    expect(container.querySelectorAll('[data-testid="virtuoso"] > div')).toHaveLength(4);
+    expect(container.textContent).toHaveLength(TEXT_CHUNK_SIZE * 4 + 1);
+    expect(container.textContent).not.toBe(value);
+  });
+
+  it('formats only visible hexdump rows for a large buffer', () => {
+    const bytes = new Array(16 * 1_000).fill(0x41);
+    const { container } = render(<HexdumpValueViewer bytes={bytes} />);
+
+    expect(screen.getByTestId('virtuoso')).toBeInTheDocument();
+    expect(container.querySelectorAll('[data-testid="virtuoso"] > div')).toHaveLength(4);
+    expect(container.textContent).toContain('00000000');
+    expect(container.textContent).not.toContain('00003e70');
+  });
+
+  it('drops virtualized value markup when its detail interaction closes', () => {
+    const { container, unmount } = render(
+      <TextValueViewer value={'x'.repeat(VIRTUALIZED_TEXT_THRESHOLD + TEXT_CHUNK_SIZE)} />,
+    );
+
+    unmount();
+    expect(container.textContent).toBe('');
+  });
+});

package/src/ui/__tests__/panel.test.tsx

@@ -0,0 +1,382 @@
+// @vitest-environment jsdom
+
+import { act, type ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { StorageEventMap } from '../../shared/messaging';
+import type { StorageDescriptor, StorageTarget } from '../../shared/types';
+
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+type Listener = (payload: unknown) => void;
+type SortingItem = { id: string; desc: boolean };
+
+const mocks = vi.hoisted(() => {
+  const listeners = new Map<string, Set<Listener>>();
+  const send = vi.fn();
+  const request = vi.fn();
+  const onMessage = vi.fn((type: string, listener: Listener) => {
+    const typeListeners = listeners.get(type) ?? new Set<Listener>();
+    typeListeners.add(listener);
+    listeners.set(type, typeListeners);
+    return { remove: () => typeListeners.delete(listener) };
+  });
+  return {
+    client: { send, onMessage, request },
+    searchChange: undefined as ((event: React.ChangeEvent<HTMLInputElement>) => void) | undefined,
+    sortKey: undefined as (() => void) | undefined,
+    emit: (type: keyof StorageEventMap, payload: unknown) =>
+      listeners.get(type)?.forEach((listener) => listener(payload)),
+    reset: () => {
+      listeners.clear();
+      send.mockReset();
+      request.mockReset();
+      onMessage.mockClear();
+      mocks.searchChange = undefined;
+      mocks.sortKey = undefined;
+    },
+  };
+});
+
+vi.mock('@rozenite/plugin-bridge', () => ({
+  useRozeniteDevToolsClient: () => mocks.client,
+}));
+vi.mock('@rozenite/ui', async () => {
+  const React = await import('react');
+  const PassThrough = ({ children }: { children?: ReactNode }) => <>{children}</>;
+  const PluginShell = Object.assign(PassThrough, { Body: PassThrough });
+  const Split = Object.assign(PassThrough, {
+    Pane: PassThrough,
+    Handle: PassThrough,
+  });
+  const Sidebar = Object.assign(PassThrough, {
+    Group: PassThrough,
+    Item: ({
+      children,
+      onClick,
+      trailing,
+    }: {
+      children?: ReactNode;
+      onClick: () => void;
+      trailing?: ReactNode;
+    }) => (
+      <button onClick={onClick}>
+        {children}
+        {trailing}
+      </button>
+    ),
+  });
+  const Toolbar = Object.assign(PassThrough, {
+    Group: PassThrough,
+    Separator: PassThrough,
+    Button: ({
+      children,
+      onClick,
+      disabled,
+      'aria-label': ariaLabel,
+      title,
+    }: {
+      children?: ReactNode;
+      onClick: () => void;
+      disabled?: boolean;
+      'aria-label'?: string;
+      title?: string;
+    }) => (
+      <button onClick={onClick} disabled={disabled} aria-label={ariaLabel} title={title}>
+        {children}
+      </button>
+    ),
+  });
+  return {
+    Badge: PassThrough,
+    Button: ({ children, onClick }: { children?: ReactNode; onClick?: () => void }) => (
+      <button onClick={onClick}>{children}</button>
+    ),
+    ConfirmDialog: () => null,
+    EmptyState: () => <div />,
+    PluginShell,
+    SearchField: ({
+      value,
+      onChange,
+    }: {
+      value: string;
+      onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    }) => {
+      mocks.searchChange = onChange;
+      return <input value={value} onChange={onChange} />;
+    },
+    Sidebar,
+    Split,
+    Toolbar,
+    VirtualizedDataTable: ({
+      data,
+      onEndReached,
+      onRowClick,
+      onSortingChange,
+    }: {
+      data: { key: string }[];
+      onEndReached?: () => void;
+      onRowClick?: (entry: { key: string }) => void;
+      onSortingChange?: (updater: (current: SortingItem[]) => SortingItem[]) => void;
+    }) => {
+      mocks.sortKey = () => {
+        onSortingChange?.((current) => {
+          const keySort = current.find((item) => item.id === 'key');
+          if (!keySort) return [{ id: 'key', desc: false }];
+          if (!keySort.desc) return [{ id: 'key', desc: true }];
+          return [];
+        });
+      };
+      return (
+        <div>
+          <button onClick={onEndReached}>reach end</button>
+          <button onClick={mocks.sortKey}>sort key</button>
+          {data.map((entry) => (
+            <button key={entry.key} onClick={() => onRowClick?.(entry)}>
+              {entry.key}
+            </button>
+          ))}
+        </div>
+      );
+    },
+  };
+});
+vi.mock('../add-entry-dialog', () => ({ AddEntryDialog: () => null }));
+vi.mock('../edit-entry-dialog', () => ({ EditEntryDialog: () => null }));
+vi.mock('../entry-detail-dialog', () => ({ EntryDetailDialog: () => null }));
+vi.mock('../import-dialog', () => ({ ImportDialog: () => null }));
+vi.mock('../utils', () => ({
+  buildExportFilename: vi.fn(() => 'snapshot.json'),
+  downloadJson: vi.fn(),
+}));
+
+import StoragePanel from '../panel';
+
+const target: StorageTarget = { adapterId: 'mmkv', storageId: 'first' };
+const descriptors: StorageDescriptor[] = [
+  {
+    target,
+    adapterName: 'MMKV',
+    storageName: 'First',
+    entryCount: 1,
+    capabilities: { supportedTypes: ['string'] },
+    supportsSubscriptions: true,
+  },
+];
+const previewResponse = (cursor?: string) => ({
+  type: 'entry-previews' as const,
+  requestId: `page-${cursor ?? 'first'}`,
+  target,
+  items: [
+    {
+      key: cursor ?? 'first',
+      type: 'string' as const,
+      preview: cursor ?? 'first',
+      valueSize: 5,
+      isTruncated: false,
+    },
+  ],
+  nextCursor: cursor ? undefined : 'next',
+});
+const renderPanel = async () => {
+  const container = document.createElement('div');
+  document.body.append(container);
+  const root = createRoot(container);
+  await act(async () => root.render(<StoragePanel />));
+  return { root, container };
+};
+const discoveryRequests = () =>
+  mocks.client.send.mock.calls.filter(([type]) => type === 'discover-storages');
+const discover = async () => {
+  const request = discoveryRequests().at(-1)?.[1];
+  await act(async () =>
+    mocks.emit('storage-descriptors', {
+      type: 'storage-descriptors',
+      requestId: request.requestId,
+      storages: descriptors,
+    }),
+  );
+};
+
+describe('StoragePanel preview query cutover', () => {
+  beforeEach(() => {
+    mocks.reset();
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+    mocks.client.request.mockImplementation(
+      ({ payload }: { payload: { type: string; cursor?: string; key?: string } }) => {
+        if (payload.type === 'list-entry-previews')
+          return Promise.resolve(previewResponse(payload.cursor));
+        if (payload.type === 'get-entry')
+          return Promise.resolve({
+            type: 'entry',
+            requestId: 'full-1',
+            target,
+            entry: { key: payload.key, type: 'string', value: 'full value' },
+          });
+        return Promise.resolve({
+          type: 'export-snapshot-result',
+          requestId: 'export-1',
+          target,
+          snapshot: {},
+        });
+      },
+    );
+  });
+  afterEach(() => {
+    document.body.innerHTML = '';
+    delete globalThis.IS_REACT_ACT_ENVIRONMENT;
+    vi.useRealTimers();
+  });
+
+  it('loads bounded preview pages and guards duplicate edge fetches', async () => {
+    const { root, container } = await renderPanel();
+    await discover();
+    expect(container.textContent).toContain('1');
+    await act(async () => {
+      await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(1));
+      await vi.waitFor(() =>
+        expect(
+          Array.from(container.querySelectorAll('button')).some(
+            (button) => button.textContent === 'first',
+          ),
+        ).toBe(true),
+      );
+    });
+    await act(async () => {
+      const edge = Array.from(container.querySelectorAll('button')).find(
+        (button) => button.textContent === 'reach end',
+      );
+      edge?.click();
+      edge?.click();
+    });
+    await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(2));
+    expect(mocks.client.request.mock.calls.map(([options]) => options.payload.cursor)).toEqual([
+      undefined,
+      'next',
+    ]);
+    await act(async () => root.unmount());
+  });
+
+  it('debounces search into a new device-owned query sequence', async () => {
+    vi.useFakeTimers();
+    const { root, container } = await renderPanel();
+    await discover();
+    await act(async () => {
+      await vi.waitFor(() => expect(container.textContent).toContain('first'));
+    });
+    await act(async () => {
+      mocks.searchChange?.({
+        target: { value: '  Needle  ' },
+      } as React.ChangeEvent<HTMLInputElement>);
+      vi.advanceTimersByTime(250);
+    });
+    await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(2));
+    expect(mocks.client.request.mock.calls[1][0].payload).toMatchObject({
+      cursor: undefined,
+      search: 'needle',
+    });
+    await act(async () => root.unmount());
+  });
+
+  it('cycles Key sorting back to ascending after descending', async () => {
+    const { root, container } = await renderPanel();
+    await discover();
+    await act(async () => {
+      await vi.waitFor(() => expect(container.textContent).toContain('first'));
+    });
+    const sortKey = () => {
+      if (!mocks.sortKey) throw new Error('Sort control is not mounted.');
+      mocks.sortKey();
+    };
+
+    await act(async () => sortKey());
+    await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(2));
+    expect(mocks.client.request.mock.calls[1][0].payload).toMatchObject({
+      keySortDirection: 'descending',
+    });
+
+    await act(async () => sortKey());
+    await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(3));
+    expect(mocks.client.request.mock.calls[2][0].payload).toMatchObject({
+      keySortDirection: 'ascending',
+    });
+
+    await act(async () => sortKey());
+    await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(4));
+    expect(mocks.client.request.mock.calls[3][0].payload).toMatchObject({
+      keySortDirection: 'descending',
+    });
+    await act(async () => root.unmount());
+  });
+
+  it('fetches a full value only when a preview row opens details', async () => {
+    const { root, container } = await renderPanel();
+    await discover();
+    await vi.waitFor(() => expect(container.textContent).toContain('first'));
+    await act(async () =>
+      Array.from(container.querySelectorAll('button'))
+        .find((button) => button.textContent === 'first')
+        ?.click(),
+    );
+    await vi.waitFor(() =>
+      expect(mocks.client.request.mock.calls[1][0].payload).toMatchObject({
+        type: 'get-entry',
+        key: 'first',
+      }),
+    );
+    await act(async () => root.unmount());
+  });
+
+  it('refreshes from the first page without changing the query', async () => {
+    const { root, container } = await renderPanel();
+    await discover();
+    await act(async () => {
+      await vi.waitFor(() => expect(container.textContent).toContain('first'));
+    });
+    await act(async () =>
+      Array.from(container.querySelectorAll('button'))
+        .find((button) => button.getAttribute('aria-label') === 'Refresh storage')
+        ?.click(),
+    );
+    await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(2));
+    expect(mocks.client.request.mock.calls[1][0].payload.cursor).toBeUndefined();
+    await act(async () => root.unmount());
+  });
+
+  it('coalesces invalidation events into one active preview refetch', async () => {
+    const { root } = await renderPanel();
+    await discover();
+    await act(async () => {
+      await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(1));
+      mocks.emit('storage-invalidated', {
+        type: 'storage-invalidated',
+        target,
+        key: 'first',
+        operation: 'set',
+      });
+      mocks.emit('storage-invalidated', {
+        type: 'storage-invalidated',
+        target,
+        key: 'next',
+      });
+    });
+    await vi.waitFor(() => expect(mocks.client.request).toHaveBeenCalledTimes(2));
+    await act(async () => root.unmount());
+  });
+
+  // The panel is recreated on every app reload and asks for storages before the
+  // app's React tree has mounted the plugin, so its first request is dropped.
+  it('runs discovery again when the device announces itself', async () => {
+    const { root, container } = await renderPanel();
+    expect(discoveryRequests()).toHaveLength(1);
+    expect(container.textContent).toContain('Waiting for storages');
+
+    await act(async () => mocks.emit('device-ready', { type: 'device-ready' }));
+    expect(discoveryRequests()).toHaveLength(2);
+    await discover();
+
+    expect(container.textContent).toContain('First');
+    await act(async () => root.unmount());
+  });
+});

package/src/ui/__tests__/storage-groups.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildStorageSidebarGroups,
+  parseStorageViewId,
+  type StorageSnapshotEntry,
+} from '../storage-groups';
+
+const entry = (
+  adapterId: string,
+  storageId: string,
+  adapterName: string,
+  storageName: string,
+  entryCount: number,
+): StorageSnapshotEntry => ({
+  target: { adapterId, storageId },
+  adapterName,
+  storageName,
+  entryCount,
+});
+
+describe('buildStorageSidebarGroups', () => {
+  it('groups snapshots by adapterId, using adapterName as the group label', () => {
+    const snapshots = new Map([
+      ['mmkv:default', entry('mmkv', 'default', 'MMKV', 'default', 3)],
+      ['mmkv:user', entry('mmkv', 'user', 'MMKV', 'user', 1)],
+      ['async-storage:default', entry('async-storage', 'default', 'AsyncStorage', 'default', 5)],
+    ]);
+
+    expect(buildStorageSidebarGroups(snapshots)).toEqual([
+      {
+        adapterId: 'mmkv',
+        adapterName: 'MMKV',
+        items: [
+          { viewId: 'mmkv:default', storageName: 'default', entryCount: 3 },
+          { viewId: 'mmkv:user', storageName: 'user', entryCount: 1 },
+        ],
+      },
+      {
+        adapterId: 'async-storage',
+        adapterName: 'AsyncStorage',
+        items: [
+          {
+            viewId: 'async-storage:default',
+            storageName: 'default',
+            entryCount: 5,
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('preserves insertion order of both groups and items within a group', () => {
+    const snapshots = new Map([
+      ['b:1', entry('b', '1', 'B', '1', 0)],
+      ['a:1', entry('a', '1', 'A', '1', 0)],
+      ['b:2', entry('b', '2', 'B', '2', 0)],
+    ]);
+
+    const groups = buildStorageSidebarGroups(snapshots);
+
+    expect(groups.map((g) => g.adapterId)).toEqual(['b', 'a']);
+    expect(groups[0].items.map((i) => i.viewId)).toEqual(['b:1', 'b:2']);
+  });
+
+  it('returns an empty array for an empty map', () => {
+    expect(buildStorageSidebarGroups(new Map())).toEqual([]);
+  });
+});
+
+describe('parseStorageViewId', () => {
+  it('splits at the first colon', () => {
+    expect(parseStorageViewId('mmkv:default')).toEqual({
+      adapterId: 'mmkv',
+      storageId: 'default',
+    });
+  });
+
+  it('treats any further colons as part of the storageId', () => {
+    expect(parseStorageViewId('mmkv:namespace:default')).toEqual({
+      adapterId: 'mmkv',
+      storageId: 'namespace:default',
+    });
+  });
+
+  it('returns null when there is no colon', () => {
+    expect(parseStorageViewId('invalid')).toBeNull();
+  });
+});