@micha.bigler/ui-core-micha 2.15.0 → 2.16.0

package/tests/messagingComposer.test.jsx

@@ -0,0 +1,111 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key, options) => options?.message ? `${key}:${options.message}` : (options?.sender ? `${key}:${options.sender}` : key) }) }));
+
+const realtimeSubscribers = new Map();
+vi.mock('../src/notifications/realtime', () => ({
+  useRealtime: () => ({
+    subscribe: (envelope, handler) => { realtimeSubscribers.set(envelope, handler); return () => realtimeSubscribers.delete(envelope); },
+    onReconnect: () => () => {},
+  }),
+}));
+function dispatchMessagingFrame(frame) { realtimeSubscribers.get('messaging')?.(frame); }
+
+import { AuthContext } from '../src/auth/AuthContext';
+import { AttachmentList } from '../src/messaging/AttachmentList';
+import { Composer } from '../src/messaging/Composer';
+import { messagingReducer, MessagingProvider, useMessaging } from '../src/messaging/MessagingProvider';
+
+function State() { const { cache } = useMessaging(); return <output data-testid="cache">{JSON.stringify(cache)}</output>; }
+function makeApi() {
+  return {
+    listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }),
+    createMessage: vi.fn(), uploadAttachments: vi.fn(), getAttachment: vi.fn().mockResolvedValue(new Blob(['file'])), getAttachmentThumbnail: vi.fn().mockResolvedValue(new Blob(['image'], { type: 'image/png' })),
+  };
+}
+function renderComposer(api, { userId } = {}) {
+  const tree = <MessagingProvider api={api} active={false}><Composer conversationId={7} /><State /></MessagingProvider>;
+  return render(userId ? <AuthContext.Provider value={{ user: { id: userId, username: 'me' } }}>{tree}</AuthContext.Provider> : tree);
+}
+function typeAndSend(text = 'hello') { fireEvent.change(screen.getByLabelText('MessagingComposer.MESSAGE'), { target: { value: text } }); fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.SEND' })); }
+const state = () => JSON.parse(screen.getByTestId('cache').textContent);
+
+afterEach(() => { cleanup(); realtimeSubscribers.clear(); });
+
+describe('Composer optimistic send and attachments', () => {
+  it('reconciles REST then websocket confirmation into exactly one row', () => {
+    const pending = { id: 'local-r1', conversation_id: 7, client_request_id: 'r1', status: 'pending' };
+    const rest = { id: 88, conversation_id: 7, body: 'hello', client_request_id: 'r1' };
+    let next = messagingReducer({ conversations: {}, messages: {}, cursors: { conversations: null, messages: {}, threads: {} } }, { type: 'messageOptimistic', message: pending });
+    next = messagingReducer(next, { type: 'messageReconciled', message: rest });
+    next = messagingReducer(next, { type: 'frame', frame: { type: 'message', conversation_id: 7, message: rest } });
+    expect(Object.values(next.messages)).toHaveLength(1);
+    expect(next.messages[88].client_request_id).toBe('r1');
+  });
+
+  it('reconciles websocket then REST confirmation into exactly one row', () => {
+    const pending = { id: 'local-r2', conversation_id: 7, client_request_id: 'r2', status: 'pending' };
+    const websocket = { id: 89, conversation_id: 7, body: 'hello', client_request_id: 'r2' };
+    let next = messagingReducer({ conversations: {}, messages: {}, cursors: { conversations: null, messages: {}, threads: {} } }, { type: 'messageOptimistic', message: pending });
+    next = messagingReducer(next, { type: 'frame', frame: { type: 'message', conversation_id: 7, message: websocket } });
+    next = messagingReducer(next, { type: 'messageReconciled', message: websocket });
+    expect(Object.values(next.messages)).toHaveLength(1);
+    expect(next.messages[89].client_request_id).toBe('r2');
+  });
+
+  it('retries a failed send with the same idempotency key and optimistic row', async () => {
+    const api = makeApi(); api.createMessage.mockRejectedValueOnce(new Error('offline')).mockResolvedValueOnce({ id: 90, conversation_id: 7, body: 'hello' });
+    renderComposer(api); typeAndSend(); await screen.findByRole('alert'); const first = api.createMessage.mock.calls[0][1].client_request_id;
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.RETRY' }));
+    await waitFor(() => expect(api.createMessage).toHaveBeenCalledTimes(2));
+    expect(api.createMessage.mock.calls[1][1].client_request_id).toBe(first);
+    await waitFor(() => expect(Object.keys(state().messages)).toEqual(['90']));
+  });
+
+  it('shows the server validation message for a rejected attachment upload', async () => {
+    // dcm's ConversationAttachmentView translates a rejected upload into a
+    // field-keyed {"files": [...]} body (the MSG-2 chunk-4 fix), not {detail}.
+    const api = makeApi(); api.uploadAttachments.mockRejectedValue({ response: { data: { files: ['File type application/octet-stream is not allowed.'] } } });
+    renderComposer(api); const input = document.querySelector('input[type=file]'); const file = new File(['x'], 'bad.exe', { type: 'application/octet-stream' });
+    fireEvent.change(input, { target: { files: [file] } }); fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.SEND' }));
+    await screen.findByText('MessagingComposer.UPLOAD_ERROR:File type application/octet-stream is not allowed.');
+  });
+
+  it('shows the server validation message when it arrives as {detail} (the text-message error shape)', async () => {
+    const api = makeApi(); api.createMessage.mockRejectedValue({ response: { data: { detail: 'Posting is not permitted.' } } });
+    renderComposer(api); typeAndSend('hello');
+    await screen.findByText('MessagingComposer.SEND_ERROR:Posting is not permitted.');
+  });
+
+  it('populates the optimistic row with the current user as sender, not "unknown sender"', async () => {
+    let resolveCreate; const api = makeApi(); api.createMessage.mockReturnValue(new Promise((resolve) => { resolveCreate = resolve; }));
+    renderComposer(api, { userId: 9 }); typeAndSend('hello');
+    await waitFor(() => expect(Object.keys(state().messages)).toHaveLength(1));
+    const [optimistic] = Object.values(state().messages);
+    expect(optimistic.status).toBe('pending');
+    expect(optimistic.sender).toEqual({ id: 9, display_name: 'me' });
+    resolveCreate({ id: 91, conversation_id: 7, body: 'hello' });
+  });
+
+  it('end-to-end: a real in-flight send reconciled by a WS frame arriving before the REST response settles produces exactly one row', async () => {
+    let resolveCreate; const api = makeApi(); api.createMessage.mockReturnValue(new Promise((resolve) => { resolveCreate = resolve; }));
+    renderComposer(api); typeAndSend('hello');
+    await waitFor(() => expect(Object.keys(state().messages)).toHaveLength(1));
+    const requestId = api.createMessage.mock.calls[0][1].client_request_id;
+    // The WS frame for this message's creation arrives while the REST POST is still in flight.
+    act(() => dispatchMessagingFrame({ envelope: 'messaging', type: 'message', conversation_id: 7, message: { id: 91, conversation_id: 7, body: 'hello', client_request_id: requestId } }));
+    expect(Object.keys(state().messages)).toEqual(['91']);
+    // The REST response for the same send resolves afterward and must not create a second row.
+    await act(async () => resolveCreate({ id: 91, conversation_id: 7, body: 'hello', client_request_id: requestId }));
+    expect(Object.keys(state().messages)).toEqual(['91']);
+  });
+
+  it('mounts Composer and AttachmentList independently', async () => {
+    const api = makeApi(); const { unmount } = renderComposer(api); expect(screen.getByLabelText('MessagingComposer.LABEL')).toBeTruthy(); unmount();
+    render(<MessagingProvider api={api} active={false}><AttachmentList attachments={[{ id: 1, filename: 'note.pdf', content_type: 'application/pdf' }]} /></MessagingProvider>);
+    expect(screen.getByLabelText('MessagingAttachments.LABEL')).toBeTruthy();
+  });
+});

package/tests/messagingExports.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { AttachmentList, Composer, ConversationLaunchers, ConversationList, MessageBubble, MessagingProvider, MessagingScopeConfig, messagingTranslations, PollCard, ReactionBar, ReadTicks, Thread, useMessaging } from '../src/index';
+
+describe('messaging barrel exports', () => {
+  it('exports the provider, hook, standalone list and launchers', () => {
+    expect(MessagingProvider).toBeDefined();
+    expect(useMessaging).toBeDefined();
+    expect(ConversationList).toBeDefined();
+    expect(ConversationLaunchers).toBeDefined();
+    expect(Thread).toBeDefined();
+    expect(MessageBubble).toBeDefined();
+    expect(ReadTicks).toBeDefined();
+    expect(Composer).toBeDefined();
+    expect(AttachmentList).toBeDefined();
+    expect(ReactionBar).toBeDefined();
+    expect(PollCard).toBeDefined();
+    expect(MessagingScopeConfig).toBeDefined();
+    expect(messagingTranslations).toBeDefined();
+  });
+});

package/tests/messagingInteractions.test.jsx

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key, options) => options?.message ? `${key}:${options.message}` : key }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: () => () => {}, onReconnect: () => () => {} }) }));
+
+import { Composer } from '../src/messaging/Composer';
+import { MessagingProvider, useMessaging } from '../src/messaging/MessagingProvider';
+import { PollCard } from '../src/messaging/PollCard';
+import { ReactionBar } from '../src/messaging/ReactionBar';
+import { MessagingScopeConfig } from '../src/messaging/MessagingScopeConfig';
+
+function CacheState() { const { cache } = useMessaging(); return <output data-testid="cache">{JSON.stringify(cache)}</output>; }
+
+const baseApi = () => ({ listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }), addReaction: vi.fn(), removeReaction: vi.fn(), votePoll: vi.fn(), closePoll: vi.fn(), createPoll: vi.fn() });
+afterEach(cleanup);
+
+describe('messaging reactions and polls', () => {
+  it('round-trips add and remove reactions through the cache-backed API', async () => {
+    const api = baseApi(); api.addReaction.mockResolvedValue({ reactions: [{ emoji: '👍', count: 1, reacted: true }] }); api.removeReaction.mockResolvedValue({ reactions: [] });
+    const { rerender } = render(<MessagingProvider api={api} active={false}><ReactionBar message={{ id: 7, reactions: [{ emoji: '👍', count: 1, reacted: false }] }} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingReactions.TOGGLE' })); await waitFor(() => expect(api.addReaction).toHaveBeenCalledWith(7, '👍'));
+    rerender(<MessagingProvider api={api} active={false}><ReactionBar message={{ id: 7, reactions: [{ emoji: '👍', count: 1, reacted: true }] }} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingReactions.TOGGLE' })); await waitFor(() => expect(api.removeReaction).toHaveBeenCalledWith(7, '👍'));
+  });
+
+  it('uses single selection for a single poll and preserves selections for a multi poll', async () => {
+    const single = baseApi(); single.votePoll.mockResolvedValue({ poll: { id: 1, options: [] } });
+    const { unmount } = render(<MessagingProvider api={single} active={false}><PollCard message={{ id: 7, poll: { id: 1, question: 'One', options: [{ id: 1, text: 'A' }, { id: 2, text: 'B' }], allow_multiple: false }}} /></MessagingProvider>);
+    const choices = screen.getAllByRole('checkbox'); fireEvent.click(choices[0]); fireEvent.click(choices[1]); fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.VOTE' })); await waitFor(() => expect(single.votePoll).toHaveBeenCalledWith(1, [2])); unmount();
+    const multiple = baseApi(); multiple.votePoll.mockResolvedValue({ poll: { id: 2, options: [] } }); render(<MessagingProvider api={multiple} active={false}><PollCard message={{ id: 8, poll: { id: 2, question: 'Many', options: [{ id: 1, text: 'A' }, { id: 2, text: 'B' }], allow_multiple: true }}} /></MessagingProvider>);
+    const multiChoices = screen.getAllByRole('checkbox'); fireEvent.click(multiChoices[0]); fireEvent.click(multiChoices[1]); fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.VOTE' })); await waitFor(() => expect(multiple.votePoll).toHaveBeenCalledWith(2, [1, 2]));
+  });
+
+  it('only exposes close to the creator/capability and surfaces a forbidden close', async () => {
+    const api = baseApi(); api.closePoll.mockRejectedValue({ response: { data: { detail: 'Not permitted' } } });
+    const { rerender } = render(<MessagingProvider api={api} active={false}><PollCard message={{ id: 7, poll: { id: 1, question: 'Q', options: [], created_by: 2 }}} /></MessagingProvider>);
+    expect(screen.queryByRole('button', { name: 'MessagingPoll.CLOSE' })).toBeNull();
+    rerender(<MessagingProvider api={api} active={false}><PollCard canClose message={{ id: 7, poll: { id: 1, question: 'Q', options: [] }}} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.CLOSE' })); await screen.findByRole('alert');
+  });
+
+  it('creates polls with an idempotency key', async () => {
+    const api = baseApi(); api.createPoll.mockResolvedValue({ id: 70, conversation_id: 4, poll: { id: 1 } });
+    render(<MessagingProvider api={api} active={false}><Composer conversationId={4} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.CREATE' })); fireEvent.change(screen.getByLabelText('MessagingPoll.QUESTION'), { target: { value: 'Where?' } });
+    const options = screen.getAllByLabelText(/MessagingPoll.OPTION/); fireEvent.change(options[0], { target: { value: 'Here' } }); fireEvent.change(options[1], { target: { value: 'There' } });
+    fireEvent.click(screen.getAllByRole('button', { name: 'MessagingPoll.CREATE' })[0]); await waitFor(() => expect(api.createPoll).toHaveBeenCalled());
+    expect(api.createPoll.mock.calls[0][2].idempotencyKey).toBeTruthy();
+  });
+
+  it('mounts the scope config as an independent provider collaborator', async () => {
+    const api = baseApi(); api.getConversationConfig = vi.fn().mockResolvedValue({ dm_policy: 'all', group_chat_enabled: true, everyone_can_post: false });
+    render(<MessagingProvider api={api} active={false}><MessagingScopeConfig conversationId={4} /></MessagingProvider>);
+    await screen.findByLabelText('MessagingConfig.LABEL');
+    expect(api.getConversationConfig).toHaveBeenCalledWith(4);
+  });
+
+  it('creates an announcement with a title, body and host-supplied link target', async () => {
+    const api = baseApi(); api.createMessage = vi.fn().mockResolvedValue({ id: 90, conversation_id: 4, kind: 'announcement', title: 'Heads up' });
+    render(<MessagingProvider api={api} active={false}><Composer conversationId={4} allowAnnouncement linkTarget="/events/4/info" /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingAnnouncement.CREATE' }));
+    fireEvent.change(screen.getByLabelText('MessagingAnnouncement.TITLE'), { target: { value: 'Heads up' } });
+    fireEvent.change(screen.getByLabelText('MessagingAnnouncement.BODY'), { target: { value: 'Schedule changed.' } });
+    fireEvent.click(screen.getAllByRole('button', { name: 'MessagingAnnouncement.SEND' })[0]);
+    await waitFor(() => expect(api.createMessage).toHaveBeenCalled());
+    const [, payload] = api.createMessage.mock.calls[0];
+    expect(payload).toMatchObject({ kind: 'announcement', title: 'Heads up', body: 'Schedule changed.', link_target: '/events/4/info' });
+  });
+
+  it('carries title and link_target into the optimistic row, not just the final REST payload', async () => {
+    const api = baseApi(); api.createMessage = vi.fn().mockReturnValue(new Promise(() => {}));
+    render(<MessagingProvider api={api} active={false}><Composer conversationId={4} allowAnnouncement linkTarget="/events/4/info" /><CacheState /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingAnnouncement.CREATE' }));
+    fireEvent.change(screen.getByLabelText('MessagingAnnouncement.TITLE'), { target: { value: 'Heads up' } });
+    fireEvent.click(screen.getAllByRole('button', { name: 'MessagingAnnouncement.SEND' })[0]);
+    await waitFor(() => {
+      const [optimistic] = Object.values(JSON.parse(screen.getByTestId('cache').textContent).messages);
+      expect(optimistic.status).toBe('pending');
+      expect(optimistic.title).toBe('Heads up');
+      expect(optimistic.link_target).toBe('/events/4/info');
+    });
+  });
+
+  it('does not offer announcement composing unless the host opts in', () => {
+    const api = baseApi();
+    render(<MessagingProvider api={api} active={false}><Composer conversationId={4} /></MessagingProvider>);
+    expect(screen.queryByRole('button', { name: 'MessagingAnnouncement.CREATE' })).toBeNull();
+  });
+
+  it('disables the chip while pending, then rolls back and re-enables it on API failure', async () => {
+    let rejectAdd; const api = baseApi(); api.addReaction.mockReturnValue(new Promise((_, reject) => { rejectAdd = reject; }));
+    render(<MessagingProvider api={api} active={false}><ReactionBar message={{ id: 7, reactions: [{ emoji: '👍', count: 1, reacted: false }] }} /></MessagingProvider>);
+    const chip = screen.getByRole('button', { name: 'MessagingReactions.TOGGLE' });
+    fireEvent.click(chip);
+    await waitFor(() => expect(chip.className.includes('Mui-disabled')).toBe(true));
+    rejectAdd({ response: { data: { detail: 'Reactions disabled' } } });
+    await screen.findByRole('alert');
+    expect(chip.className.includes('Mui-disabled')).toBe(false);
+  });
+
+  it('ignores a second click on the same reaction while the first toggle is still in flight', async () => {
+    let resolveAdd; const api = baseApi(); api.addReaction.mockReturnValue(new Promise((resolve) => { resolveAdd = resolve; }));
+    render(<MessagingProvider api={api} active={false}><ReactionBar message={{ id: 7, reactions: [{ emoji: '👍', count: 1, reacted: false }] }} /></MessagingProvider>);
+    const chip = screen.getByRole('button', { name: 'MessagingReactions.TOGGLE' });
+    fireEvent.click(chip); fireEvent.click(chip);
+    resolveAdd({ reactions: [{ emoji: '👍', count: 2, reacted: true }] });
+    await waitFor(() => expect(api.addReaction).toHaveBeenCalledTimes(1));
+  });
+});

package/tests/realtime.test.jsx

@@ -37,6 +37,13 @@ function StreamConsumer({ envelope, testId }) {
   return <output data-testid={testId}>{JSON.stringify(received)}</output>;
 }
 
+function ReconnectConsumer() {
+  const { onReconnect } = useRealtime();
+  const [count, setCount] = React.useState(0);
+  React.useEffect(() => onReconnect(() => setCount((current) => current + 1)), [onReconnect]);
+  return <output data-testid="reconnect-count">{count}</output>;
+}
+
 function NotificationsConsumer() {
   const notifications = useNotifications();
   return (
@@ -181,6 +188,26 @@ describe('realtime primitive (NOTIF-13)', () => {
     }
   });
 
+  it('additively signals consumers when a closed connection re-establishes', async () => {
+    vi.useFakeTimers();
+    try {
+      render(
+        <AuthContext.Provider value={{ user: { id: 4 } }}>
+          <NotificationsProvider><ReconnectConsumer /></NotificationsProvider>
+        </AuthContext.Provider>,
+      );
+      await vi.waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+      MockWebSocket.instances[0].onopen();
+      expect(screen.getByTestId('reconnect-count').textContent).toBe('0');
+      MockWebSocket.instances[0].onclose();
+      await vi.advanceTimersByTimeAsync(1_000);
+      MockWebSocket.instances[1].onopen();
+      await vi.waitFor(() => expect(screen.getByTestId('reconnect-count').textContent).toBe('1'));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("NotificationsProvider's public context value is unchanged", async () => {
     renderWithStreams();
     await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));

package/vite.config.mjs

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+});

package/work-orders/DX-1.md

@@ -0,0 +1,166 @@
+# DX-1 — minimal Vite dev harness for ucm components
+
+Status: planned · Tier 1 (dev-only tooling; **adds devDependencies → approval-gated**) · Target repo: `ui-core-micha` (main)
+
+---
+
+## Part A — Envelope (Expertenchat, 2026-07-31)
+
+### Goal
+
+Give `ui-core-micha` a way to **render** its components during development. Today `package.json`
+exposes only `build` (tsc) and `test` (vitest): there is no Storybook, no demo app, no dev page. Every
+shipped surface — auth, onboarding, notifications, charts — has only ever been verified in jsdom or
+after a consuming app pinned it.
+
+Immediate driver: MSG-3 is ~3700 LOC of new UI (jg's parity target: `Thread.jsx` alone is 2470 LOC)
+that no app mounts until MSG-5, and the operator granted a redesign licence, which is only iterable
+if the result can be looked at. But the gap is not messaging-specific and the harness is not
+messaging-specific.
+
+### Expected outcome
+
+- A `pnpm dev` (or equivalent) script starting a Vite dev server that mounts ucm components in a
+  browser, with the repo's MUI theme, `react-i18next` and router context wired the way a host app
+  wires them.
+- A small set of harness entries covering the existing surfaces well enough to prove the harness is
+  real: at minimum one notifications surface and one charts surface. Adding an entry for a new
+  component must be a few lines, not a framework.
+- **A single component must be mountable standalone**, not only a whole assembled surface. MSG-3
+  relies on this: it requires one harness entry per named component as its decomposition forcing
+  function, so the harness must not assume an entry equals a full page.
+- A **mock transport layer** the entries drive: fixture data plus an injectable API/realtime adapter,
+  so a surface can be exercised without a backend. Where a component takes its data through a
+  provider, the harness supplies a mock provider rather than patching the component.
+- Light/dark theme and viewport switching, since responsive and dark-mode correctness is exactly what
+  jsdom cannot show.
+- Harness code lives outside the published package: not exported from `src/index.js`, excluded from
+  `tsconfig.build.json`, and adding **zero** runtime dependencies. `dist/` must be byte-identical in
+  content to a build from before this WO.
+- `README` (or `CONTRIBUTING`) gains a short section on running the harness and adding an entry.
+
+### Non-goals / do-not-touch
+
+Storybook (deliberately not chosen — a dev page is a fraction of the config surface and this repo has
+no story-writing habit to build on; revisit only if the harness proves insufficient); visual
+regression / screenshot testing; publishing the harness; any change to component source, exports, or
+public API; any change to the existing vitest setup; CI wiring (the harness is a local dev tool, not
+a gate).
+
+### Required tests to WRITE
+
+This is dev tooling, so the meaningful assertions are about **not** affecting the product:
+
+- The published barrel (`src/index.js`) is unchanged — the existing exports regression test
+  (`tests/notificationsExports.test.js` pattern) must still pass, and no harness module is reachable
+  from it.
+- A build (`tsc -p tsconfig.build.json`) succeeds and emits no harness files into `dist/`.
+- `package.json` `dependencies` and `peerDependencies` are unchanged; additions are confined to
+  `devDependencies`.
+
+No component behaviour is under test here — the existing suite covers that and must stay green.
+
+### Risks
+
+- **Dependency addition** is the real cost and the reason this is approval-gated: Vite plus a React
+  plugin. Keep it to the minimum; do not pull in a UI-catalog framework.
+- **Harness fidelity.** A mock adapter can drift from the real REST/realtime contract and produce
+  confidence that does not transfer. Mitigation: fixtures are shaped from the actual dcm contract in
+  `django-core-micha/docs/design/messaging-platform.md` §REST/§Realtime, and the harness is a
+  development aid — it never replaces the tests or the independent review.
+- Scope creep into "a component gallery". The deliverable is a dev page, not a product.
+
+### Preconditions
+
+Operator approval for the devDependency additions — granted 2026-07-31 as part of the MSG-3 scoping
+decision. This WO **runs before MSG-3**.
+
+### Execution directive
+
+Implement through `codex exec` in the background — invoked **directly via Bash** (never the
+`debugger`/`*_coder` Agent wrappers) with **both** flags `--skip-git-repo-check` and
+`--dangerously-bypass-approvals-and-sandbox`, prompt passed as a positional argument from a file;
+fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
+
+### Release
+
+**No version bump, no publish.** Dev-only tooling changes nothing in the package. The next ucm
+publish rides whatever WO follows (MSG-3).
+
+### Mini-handover (pastable)
+
+Orchestrator: implement `work-orders/DX-1.md` in `ui-core-micha` (main). `git pull` first, read the
+WO, then follow `orchestrate-codex` (Codex-first, own independent review, commit on green, **no
+publish**).
+
+---
+
+## Part B — Implementation map (Orchestrator)
+
+### Target repo / working directory
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root; package `@micha.bigler/ui-core-micha`,
+current published version 2.15.0 — **unchanged by this WO**, no publish).
+
+### Context package
+
+**Repo conventions to mirror:**
+- `package.json` — current `scripts`: `build` (`tsc -p tsconfig.build.json`), `test` (`vitest run`).
+  No `dev` script exists yet; add one. `peerDependencies`/`dependencies` must not change;
+  `devDependencies` gains Vite + `@vitejs/plugin-react` only (or whatever minimal set a Vite+React+JSX
+  dev server needs) — no UI-catalog framework, no Storybook.
+- `tsconfig.build.json` — `"include": ["src"]`, `rootDir: "./src"`, `outDir: "dist"`. The harness must
+  live **outside** `src/` (e.g. a top-level `dev/` directory) so it is never included by this config
+  and never emitted into `dist/`. Confirm after writing: `dist/` from a build with the harness present
+  must be byte-identical to a build from before this WO (no new/changed files under `dist/`).
+- `src/index.js` — the published barrel. Do not add anything here for the harness itself; the harness
+  imports FROM the barrel (or directly from component source, orchestrator's/Codex's call — importing
+  from source is likely simpler and avoids a dist rebuild loop during dev) but nothing is added TO it.
+- `tests/notificationsExports.test.js` — the existing exports-regression pattern to confirm still
+  passes untouched (proves the barrel didn't change).
+- `src/notifications/realtime.jsx` — `useRealtimeCore({ active, wsUrl })` returns `{ subscribe }`;
+  `RealtimeContext` is the context the mock realtime provider must satisfy so components under it can
+  call `useRealtime()` without throwing. The harness's mock realtime adapter should provide a
+  `RealtimeContext.Provider` with an injectable `subscribe` (e.g. a manual event-dispatch harness) so
+  a harness entry can simulate a WS frame arriving, without opening a real socket.
+- `src/notifications/NotificationsProvider.jsx` (read for the provider-wrapping pattern) — a
+  representative provider-consuming surface for the "at minimum one notifications surface" harness
+  entry requirement.
+- `src/i18n/notificationsTranslations.ts` / `src/i18n/chartsTranslations.ts` — the flat i18n key
+  pattern; the harness needs `react-i18next` wired with at least these (or a minimal fixture set) so
+  mounted components render translated text instead of raw keys.
+- Chart components (`ChartFrame`/`BarChart`/`LineChart`, per `tests/ChartFrame.test.jsx` etc.) — the
+  "at minimum one charts surface" harness entry.
+
+**Invariants:**
+- Zero new runtime dependencies (peer or direct) — Vite/plugin additions are dev-only.
+- Harness is not exported, not built, not tested for behavior (only the three "does not affect the
+  product" assertions in Required Tests below).
+- No change to the existing vitest test setup/config or any existing test file.
+- No CI wiring — this is a local dev tool.
+
+### Required tests
+
+Per envelope: extend/confirm the exports-regression test still passes with nothing new reachable from
+it; a `build` succeeds and diffing `dist/` before/after shows no harness files and no content change;
+inspect `package.json` to confirm `dependencies`/`peerDependencies` are byte-identical and only
+`devDependencies` gained entries.
+
+### Progress contract
+
+Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (file opened, file
+edited, command/test run) and `PROGRESS: [<n>/<total>] done` on step completion, spaced so no gap
+exceeds ~2 min, stdout unbuffered, and exactly one final `RESULT: DONE|BLOCKED <reason>`.
+
+### Preamble (must be appended verbatim to the Codex prompt)
+
+The text above is the COMPLETE spec — read nearest `AGENTS.md`, `.codex/skills/<role>/SKILL.md` (if
+present), and this repo's `MEMORY.md` only for conventions; stay in scope; do not touch
+`peerDependencies`/`dependencies`, only `devDependencies`; do not touch `src/index.js`'s exports; do
+not update `MEMORY.md`; do NOT `git add`/`commit`/`push` — leave the change uncommitted in the working
+tree for the orchestrator's independent review. WRITE and RUN the three required checks (exports test,
+build + dist diff, package.json dependency diff) yourself to confirm — that is your only verification
+run: do NOT run the full vitest suite as a "review" and do NOT run any review; the orchestrator does
+both after you finish (though re-running `vitest run` in full is harmless and encouraged as a sanity
+check since it's the existing test command, just don't treat it as satisfying the review step).