@micha.bigler/ui-core-micha 3.13.1 → 3.14.3

package/tests/chatTranslations.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { chatTranslations } from '../src/i18n/chatTranslations';
+
+const LOCALES = ['de', 'en', 'fr', 'sw'];
+
+describe('chatTranslations', () => {
+  it('has every key in all four languages', () => {
+    for (const [key, value] of Object.entries(chatTranslations)) {
+      for (const locale of LOCALES) {
+        expect(typeof value[locale], `${key}.${locale}`).toBe('string');
+        expect(value[locale].trim(), `${key}.${locale}`).not.toBe('');
+      }
+    }
+  });
+
+  it('uses the Envelope copy verbatim in English', () => {
+    expect(chatTranslations['Chat.driver.claude_cli'].en).toBe('Claude Code subscription');
+    expect(chatTranslations['Chat.driver.anthropic_api'].en).toBe('Anthropic API');
+    expect(chatTranslations['Chat.driver.openai_api'].en).toBe('OpenAI API');
+    expect(chatTranslations['Chat.usageLimit'].en).toBe('Usage limit reached for {{model}}. Choose another model or try again later.');
+    expect(chatTranslations['Chat.answerIncomplete'].en).toBe('The answer could not be completed.');
+    expect(chatTranslations['Chat.unavailable'].en).toBe('Chat is not available');
+    expect(chatTranslations['Chat.noModel'].en).toBe('No language model is configured on this server.');
+    expect(chatTranslations['Chat.payPerUse'].en).toBe('pay per use');
+    expect(chatTranslations['Chat.interrupted'].en).toBe('Interrupted');
+    expect(chatTranslations['Chat.reconnecting'].en).toBe('Reconnecting');
+    expect(chatTranslations['Chat.archived'].en).toBe('Archived');
+  });
+
+  it('includes non-empty driver names in every locale', () => {
+    for (const id of ['claude_cli', 'anthropic_api', 'openai_api']) {
+      const value = chatTranslations[`Chat.driver.${id}`];
+      expect(value).toBeTruthy();
+      for (const locale of LOCALES) expect(value[locale].trim(), `${id}.${locale}`).not.toBe('');
+    }
+  });
+
+  it('keeps interpolation placeholders in every language', () => {
+    for (const [key, value] of Object.entries(chatTranslations)) {
+      const wanted = [...value.en.matchAll(/\{\{(\w+)\}\}/g)].map((m) => m[1]).sort();
+      for (const locale of LOCALES) {
+        const found = [...value[locale].matchAll(/\{\{(\w+)\}\}/g)].map((m) => m[1]).sort();
+        expect(found, `${key}.${locale}`).toEqual(wanted);
+      }
+    }
+  });
+});

package/tests/chatWorkspace.test.jsx

@@ -0,0 +1,234 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key, values) => (values?.model !== undefined ? `${key}:${values.model}` : key) }) }));
+vi.mock('@mui/icons-material', () => ({ MoreVert: () => null }));
+
+import ChatWorkspace from '../src/chat/ChatWorkspace';
+
+class FakeSocket {
+  static OPEN = 1;
+  static instances = [];
+  constructor(url) { this.url = url; this.readyState = 0; this.sent = []; FakeSocket.instances.push(this); }
+  open() { this.readyState = 1; this.onopen?.(); }
+  push(frame) { this.onmessage?.({ data: JSON.stringify(frame) }); }
+  send(data) { this.sent.push(JSON.parse(data)); }
+  close(code = 1000) { this.readyState = 3; this.onclose?.({ code }); }
+}
+
+const catalogue = {
+  entries: [
+    { id: 'cli-sonnet', driver: 'claude_cli', model: 'sonnet', label: 'Sonnet', efforts: ['low', 'high'], billing: 'subscription' },
+    { id: 'oa', driver: 'openai_api', model: 'gpt', label: 'GPT', efforts: ['medium'], billing: 'pay_per_use' },
+  ],
+  default: { entry: 'cli-sonnet', effort: 'high' },
+};
+const baseChat = { id: 7, title: 'Budget', archived_at: null, selection: { entry: 'cli-sonnet', effort: 'high' } };
+
+function makeApi(extra = {}) {
+  return {
+    getStatus: vi.fn().mockResolvedValue({ status: 'available' }),
+    getCatalogue: vi.fn().mockResolvedValue(catalogue),
+    listChats: vi.fn().mockImplementation(async ({ archived } = {}) => ({ results: archived ? [] : [baseChat], next: null })),
+    createChat: vi.fn().mockResolvedValue({ ...baseChat, id: 8, title: '' }),
+    updateChat: vi.fn().mockImplementation(async (id, patch) => ({ ...baseChat, id, ...patch })),
+    deleteChat: vi.fn().mockResolvedValue(null),
+    listTurns: vi.fn().mockResolvedValue({ results: [], next: null }),
+    ...extra,
+  };
+}
+
+async function openChat(api) {
+  render(<ChatWorkspace api={api} wsUrl={(id) => `ws://test/${id}`} />);
+  fireEvent.click(await screen.findByText('Budget'));
+  await waitFor(() => expect(FakeSocket.instances.length).toBe(1));
+  const socket = FakeSocket.instances[0];
+  act(() => socket.open());
+  return socket;
+}
+
+beforeEach(() => { globalThis.WebSocket = FakeSocket; });
+afterEach(() => { cleanup(); delete globalThis.WebSocket; FakeSocket.instances = []; });
+
+describe('ChatWorkspace streaming', () => {
+  it('streams deltas into the answer and replaces them with the final turn and its sources', async () => {
+    const socket = await openChat(makeApi());
+    fireEvent.change(screen.getByRole('textbox', { name: 'Chat.message' }), { target: { value: 'Hello' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.send' }));
+    expect(socket.sent).toEqual([{ type: 'send', message: 'Hello' }]);
+    expect(screen.getByText('Hello')).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'Chat.stop' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'Chat.send' }).disabled).toBe(true);
+
+    act(() => socket.push({ type: 'tool', phase: 'start', name: 'kb', label: 'Searching the knowledge base' }));
+    expect(screen.getByText('Searching the knowledge base')).toBeTruthy();
+    act(() => { socket.push({ type: 'delta', text: 'Par' }); socket.push({ type: 'delta', text: 'tial' }); });
+    expect(screen.getByText('Partial')).toBeTruthy();
+
+    act(() => socket.push({ type: 'turn', turn: { id: 40, seq: 1, user_text: 'Hello', assistant_text: 'Final text', state: 'completed', sources: [{ label: 'KB-1', reference: 'kb://1' }], driver: 'claude_cli', model: 'Sonnet', effort: 'high' } }));
+    expect(screen.queryByText('Partial')).toBeNull();
+    expect(screen.getByText('Final text')).toBeTruthy();
+    expect(screen.getByText('KB-1')).toBeTruthy();
+    expect(screen.queryByText('Searching the knowledge base')).toBeNull();
+    expect(screen.getByRole('button', { name: 'Chat.send' })).toBeTruthy();
+  });
+
+  it('sends stop over the socket while a turn runs', async () => {
+    const socket = await openChat(makeApi());
+    fireEvent.change(screen.getByRole('textbox', { name: 'Chat.message' }), { target: { value: 'Hello' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.send' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.stop' }));
+    expect(socket.sent.at(-1)).toEqual({ type: 'stop' });
+  });
+
+  it('does not resend anything after a reconnect', async () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    try {
+      const socket = await openChat(makeApi());
+      fireEvent.change(screen.getByRole('textbox', { name: 'Chat.message' }), { target: { value: 'Hello' } });
+      fireEvent.click(screen.getByRole('button', { name: 'Chat.send' }));
+      act(() => socket.close(1006));
+      act(() => { vi.advanceTimersByTime(1000); });
+      expect(FakeSocket.instances).toHaveLength(2);
+      act(() => FakeSocket.instances[1].open());
+      expect(FakeSocket.instances[1].sent).toEqual([]);
+    } finally { vi.useRealTimers(); }
+  });
+});
+
+describe('ChatWorkspace edge states', () => {
+  it('shows the usage-limit state with Change model, which opens the picker', async () => {
+    const socket = await openChat(makeApi());
+    fireEvent.change(screen.getByRole('textbox', { name: 'Chat.message' }), { target: { value: 'Hello' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.send' }));
+    act(() => socket.push({ type: 'error', code: 'quota_exceeded' }));
+    expect(screen.getByText('Chat.usageLimit:Sonnet')).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.changeModel' }));
+    expect(screen.getByRole('group', { name: 'Chat.driver.openai_api' })).toBeTruthy();
+  });
+
+  it('shows an interrupted turn from history with Retry, which sends its text again only on click', async () => {
+    const api = makeApi({ listTurns: vi.fn().mockResolvedValue({ results: [{ id: 5, seq: 1, user_text: 'Again please', assistant_text: 'Half', state: 'interrupted', sources: [], driver: 'claude_cli', model: 'Sonnet', effort: 'high' }], next: null }) });
+    const socket = await openChat(api);
+    await screen.findByText('Chat.interrupted');
+    expect(socket.sent).toEqual([]);
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.retry' }));
+    expect(socket.sent).toEqual([{ type: 'send', message: 'Again please' }]);
+  });
+
+  it('shows Reconnecting while the connection is being re-established and blocks Send', async () => {
+    const socket = await openChat(makeApi());
+    act(() => socket.close(1006));
+    expect(screen.getByText('Chat.reconnecting')).toBeTruthy();
+    fireEvent.change(screen.getByRole('textbox', { name: 'Chat.message' }), { target: { value: 'x' } });
+    expect(screen.getByRole('button', { name: 'Chat.send' }).disabled).toBe(true);
+  });
+
+  it.each([[4401, 'Chat.sessionEnded'], [4403, 'Chat.accessLost'], [4429, 'Chat.rateLimited']])('stops reconnecting on close code %s and shows its state', async (code, text) => {
+    const socket = await openChat(makeApi());
+    act(() => socket.close(code));
+    expect(screen.getByText(text)).toBeTruthy();
+    expect(FakeSocket.instances).toHaveLength(1);
+  });
+
+  it('shows the not-configured state and loads no chat list', async () => {
+    const api = makeApi({ getStatus: vi.fn().mockResolvedValue({ status: 'not_configured' }) });
+    render(<ChatWorkspace api={api} />);
+    expect(await screen.findByText('Chat.unavailable')).toBeTruthy();
+    expect(screen.getByText('Chat.noModel')).toBeTruthy();
+    expect(screen.queryByRole('button', { name: 'Chat.newChat' })).toBeNull();
+  });
+
+  it('opens an archived chat read-only: Send is disabled and Restore is offered', async () => {
+    const archivedChat = { ...baseChat, archived_at: '2026-10-01T00:00:00Z' };
+    const api = makeApi({ listChats: vi.fn().mockImplementation(async ({ archived } = {}) => ({ results: archived ? [archivedChat] : [], next: null })) });
+    render(<ChatWorkspace api={api} wsUrl={(id) => `ws://test/${id}`} />);
+    fireEvent.click(await screen.findByRole('button', { name: /Chat.archived/ }));
+    fireEvent.click(screen.getByText('Budget'));
+    expect(await screen.findByText('Chat.archivedReadOnly')).toBeTruthy();
+    expect(screen.getByRole('textbox', { name: 'Chat.message' }).disabled).toBe(true);
+    expect(screen.getByRole('button', { name: 'Chat.send' }).disabled).toBe(true);
+    fireEvent.click(screen.getAllByRole('button', { name: 'Chat.restore' })[0]);
+    await waitFor(() => expect(api.updateChat).toHaveBeenCalledWith(7, { archived: false }));
+  });
+
+  it('shows an empty new chat', async () => {
+    const api = makeApi();
+    render(<ChatWorkspace api={api} wsUrl={(id) => `ws://test/${id}`} />);
+    fireEvent.click((await screen.findAllByRole('button', { name: 'Chat.newChat' }))[0]);
+    expect(await screen.findByText('Chat.emptyTitle')).toBeTruthy();
+    expect(api.createChat).toHaveBeenCalled();
+  });
+});
+
+describe('ChatWorkspace load order', () => {
+  it('shows no Reconnecting chip on the first connect', async () => {
+    render(<ChatWorkspace api={makeApi()} wsUrl={(id) => `ws://test/${id}`} />);
+    fireEvent.click(await screen.findByText('Budget'));
+    await waitFor(() => expect(FakeSocket.instances.length).toBe(1));
+    expect(screen.queryByText('Chat.reconnecting')).toBeNull();
+  });
+
+  it('does not request catalogue or chat lists when no model is configured', async () => {
+    const api = makeApi({ getStatus: vi.fn().mockResolvedValue({ status: 'not_configured' }) });
+    render(<ChatWorkspace api={api} />);
+    await screen.findByText('Chat.unavailable');
+    expect(api.getCatalogue).not.toHaveBeenCalled();
+    expect(api.listChats).not.toHaveBeenCalled();
+  });
+});
+
+describe('ChatWorkspace wiring', () => {
+  it('calls the update endpoint when the picker selection changes', async () => {
+    const api = makeApi();
+    await openChat(api);
+    fireEvent.click(screen.getByRole('button', { name: 'Sonnet · Chat.effort.high' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.effort.low' }));
+    await waitFor(() => expect(api.updateChat).toHaveBeenCalledWith(7, { selection: { entry: 'cli-sonnet', effort: 'low' } }));
+  });
+  it('wires rename, archive and delete of a chat to the endpoints', async () => {
+    const api = makeApi();
+    render(<ChatWorkspace api={api} wsUrl={(id) => `ws://test/${id}`} />);
+    await screen.findByText('Budget');
+    const menu = () => fireEvent.click(screen.getAllByRole('button', { name: 'Chat.actions' })[0]);
+    menu();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Chat.rename' }));
+    fireEvent.change(screen.getByRole('textbox', { name: 'Chat.renameLabel' }), { target: { value: 'Plan' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.save' }));
+    await waitFor(() => expect(api.updateChat).toHaveBeenCalledWith(7, { title: 'Plan' }));
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+    menu();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Chat.archive' }));
+    await waitFor(() => expect(api.updateChat).toHaveBeenCalledWith(7, { archived: true }));
+    await waitFor(() => expect(screen.queryByRole('menu')).toBeNull());
+    menu();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Chat.delete' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.delete' }));
+    await waitFor(() => expect(api.deleteChat).toHaveBeenCalledWith(7));
+  });
+
+  it('offers no Retry on an archived chat', async () => {
+    const archivedChat = { ...baseChat, archived_at: '2026-10-01T00:00:00Z' };
+    const api = makeApi({
+      listChats: vi.fn().mockImplementation(async ({ archived } = {}) => ({ results: archived ? [archivedChat] : [], next: null })),
+      listTurns: vi.fn().mockResolvedValue({ results: [{ id: 5, seq: 1, user_text: 'q', assistant_text: 'half', state: 'interrupted', sources: [] }], next: null }),
+    });
+    render(<ChatWorkspace api={api} wsUrl={(id) => `ws://test/${id}`} />);
+    fireEvent.click(await screen.findByRole('button', { name: /Chat.archived/ }));
+    fireEvent.click(screen.getByText('Budget'));
+    await screen.findByText('Chat.interrupted');
+    expect(screen.queryByRole('button', { name: 'Chat.retry' })).toBeNull();
+  });
+
+  it('keeps an interrupted turn visible when Retry is clicked without a connection', async () => {
+    const api = makeApi({ listTurns: vi.fn().mockResolvedValue({ results: [{ id: 5, seq: 1, user_text: 'Again', assistant_text: 'half', state: 'interrupted', sources: [] }], next: null }) });
+    const socket = await openChat(api);
+    await screen.findByText('Chat.interrupted');
+    act(() => socket.close(4403));
+    fireEvent.click(screen.getByRole('button', { name: 'Chat.retry' }));
+    expect(screen.getByText('Again')).toBeTruthy();
+    expect(socket.sent).toEqual([]);
+  });
+});

package/tests/i18nAggregate.test.js

@@ -15,6 +15,7 @@ vi.mock('@mui/icons-material', () => ({
 import {
   authTranslations as publicAuthTranslations,
   chartsTranslations as publicChartsTranslations,
+  chatTranslations as publicChatTranslations,
   messagingTranslations as publicMessagingTranslations,
   notificationsTranslations as publicNotificationsTranslations,
   onboardingTranslations as publicOnboardingTranslations,
@@ -29,6 +30,7 @@ const bundleImporters = import.meta.glob('../src/i18n/*.ts');
 const PUBLIC_BUNDLES = {
   authTranslations: publicAuthTranslations,
   chartsTranslations: publicChartsTranslations,
+  chatTranslations: publicChatTranslations,
   messagingTranslations: publicMessagingTranslations,
   notificationsTranslations: publicNotificationsTranslations,
   onboardingTranslations: publicOnboardingTranslations,

package/work-orders/UCM-AUTH-13.md

@@ -0,0 +1,47 @@
+# UCM-AUTH-13 — Preserve profile edits during a same-person refresh
+
+## A. Envelope — operator-approved correction
+
+The Spesix first-steps browser trace proves that a background current-user response can arrive while the privacy checkbox is being edited. `ProfileComponent` currently resets every form field whenever the context user object changes, losing the person's input.
+
+Expected outcome: preserve unsaved name and consent edits across a background refresh of the same person. Continue to refresh untouched fields from server data. A change of person, including logout followed by login, must initialize the form from the new person's data and never transfer consent or edits between people. Initial asynchronous user hydration must still work.
+
+Scope: the existing shared ProfileComponent form state, targeted regression tests, a patch release, and subsequent Spesix dependency consumption. No change to authentication, permissions, consent policy, API payload shape, statement requests, layout or copy. No prototype; existing components and labels remain the visual specification. Token delta: EMPTY. Copy list: EMPTY.
+
+Tier 3: shared-core and profile/consent surface. Operator explicitly approved correction, checking, publication and Spesix pin update in the Spesix orchestration chat on 2026-10-14.
+
+Risks: stale pristine fields, failure to hydrate an initially absent user, or carrying unsaved consent into a different account. Tests to write: same-person object replacement preserves typed first/last names and both edited consent values in the submitted payload; untouched fields update; different identity and logout/login reset all fields; initial hydration works. Use real form controls and context rerenders.
+
+## B. Implementation map — addressed to the implementer
+
+Target: `C:/Users/Micha Bigler/Documents/webapps/ui-core-micha`.
+
+Own only `src/components/ProfileComponent.jsx` and new `tests/ProfileComponent.refresh.test.jsx`. Read `tests/AccountPage.profileStatements.test.jsx` for the existing Vitest/jsdom, MUI and AuthContext conventions; `src/auth/AuthContext.jsx` for user identity shape; and `src/pages/AccountPage.jsx` for the caller contract. The library is not a joined application: one author owns component and focused unit tests.
+
+The synchronization effect at ProfileComponent lines 56–65 currently depends on `[user]` and unconditionally assigns username, email, first/last name and both consent flags. The editable controls are near lines 205–250. `handleSubmit` near line 117 constructs the existing optional-fields payload; preserve it. Username/email remain read-only. Statement loading effects and visibility props are unchanged. AccountPage passes its profile update callback into this component. Work from these seams; do not broadly explore or change AuthContext or callers. Verify the identity contract before choosing synchronization behavior; do not use object reference as person identity.
+
+### Required preamble and progress contract
+
+The text above is the COMPLETE spec. Read root AGENTS.md and `.codex/skills/frontend-engineering/SKILL.md` only for conventions. Stay in scope. Do not edit WORK_ORDERS.md, MEMORY.md, package files, lockfiles, changelog, CI or unrelated files. Tools are only for reading the named context and editing assigned source/tests, plus one run of the new tests using the existing direct Vitest runner. No installs, package-manager commands, git, self-review or reviewer dispatch. Leave edits uncommitted. Your run is not the gate; the Orchestrator runs the affected set and independent reviews.
+
+Use explicit UTF-8 file I/O. You share this checkout: preserve all other edits, including the foreign scratchpad directory. Native cwd bootstrap is the workspace root; assigned paths and test cwd must be absolute, without changing the shared process cwd. Start with `PLAN: ...`, report `PROGRESS: [n/total] ...` at meaningful actions with gaps below two minutes, and finish with exactly one `RESULT: DONE|BLOCKED <reason>`.
+
+## C. Orchestrator only — NOT addressed to the implementer
+
+> STOP here if you are the implementer. Everything below belongs to the Orchestrator after implementation. Do not execute it or dispatch anyone.
+
+Dispatch a fresh native worker, explicit codex/gpt-6-luna, fresh context. Record requested and exposed effective metadata honestly; native provider/cwd/sandbox are unverified if not exposed.
+
+Gate #1 is the explicit operator approval recorded above. Run independent envelope, regression, duplication and tests lenses plus UI and security concurrently on the corrected diff, read-only, configured Luna. Parent checks profile payload/identity boundaries in addition. Run focused ProfileComponent and existing AccountPage tests and the build. Root owns patch metadata and publication through the existing main-push workflow; no workflow dispatch is authorized by this file. Verify published version before changing Spesix pin, and inspect the intervening 3.12.0-to-current changes. No screenshots are needed for this state correction.
+
+Foreign scratchpad is excluded. Commit only owned explicit paths. Update register with actual author, reviews, checks, release and consumption evidence; never claim completion before those checks.
+
+### Execution and gate evidence
+
+Fresh native `/root/ucm_auth13_author`, requested codex/gpt-6-luna/high, completed only the two assigned files; no git or package operations. Native provider/cwd/sandbox are not exposed. Author's one test attempt failed before collection on Windows Vitest cache EPERM. Parent authoritative elevated run passed: ProfileComponent.refresh (5) and existing AccountPage suites (6), 11 tests in 3 files. Parent added the independently edited-versus-pristine editable-fields case. Existing-dependency TypeScript build passed. Diff whitespace check passed. Root checked unchanged payload construction, statement effects, visibility flags and server-side authority; local edit tracking resets at identity/logout boundaries.
+
+Six fresh CLI codex/gpt-6-luna read-only lanes ran concurrently against the same frozen diff, including package/changelog and complete component/caller context. Each exited 0 with requested model, openai provider and library cwd confirmed in banner. Envelope, duplication, UI and security reported No findings. Regression raised mutable fallback identity for consumers without IDs: not accepted as a defect in the supported AuthContext contract, which maps the immutable API id; without an immutable identity the component cannot establish that two changed fallback identities are the same person, and preserving consent across them would weaken account isolation. Tests raised that identity/logout/hydration guards also pass against the previous code: not accepted; these are explicitly required preservation cases and catch a naive freeze-after-first-hydration fix, while two same-person tests discriminate the actual defect and submitted consent values. Review: codex/gpt-6-luna; lenses envelope, regression, duplication, tests, ui, security; 2 raised, 0 accepted, worst accepted none. Some optional narrow reads failed process setup; reviewers completed from the full inline diff/context. UI attempted a second blocked narrow read; no command actually executed. No screenshots or image reviews.
+
+npm version verified as 3.13.1 before reserving patch 3.13.2. Existing publish.yml builds and runs the library suite on main push before Trusted Publishing; no manual dispatch. Root inspected the consumer's intervening 3.12.0-to-3.13.1 code: AccountPage adds optional showProfileStatements default true, preserving existing controls/payload; SectionNav adds ListItem wrappers with existing selection/callbacks/labels. No changed exports or dependency requirements. Published patch and Spesix installed-package proof remain pending.
+
+Release completion: main f29d1dd, publish workflow38640512864 succeeded (build,90 test files and npm Trusted Publishing). Public registry confirms3.13.2, published2026-10-14T21:33:03Z after propagation. Spesix consumed exact3.13.2 in a30de18; real installed Welcome/ProfileComponent, AuthRoutesIntegration and AccountHub tests8/8 passed, shared i18next resolution confirmed. Spesix's separate SPX-DEP-5 owns its pending real-browser/capture CI38641555651@7eaefcc. The library correction/release is complete; no production app promotion occurred.

package/work-orders/UCM-CHAT-1.md

@@ -0,0 +1,190 @@
+# UCM-CHAT-1 — Shared AI chat surface: chat list, streaming thread, sources, model and effort picker
+
+Prepared: 2026-10-15. Target repository: `ui-core-micha` (`main`). Backend counterpart and transport contract: `django-core-micha/DCM-CHAT-1`. First consumer: `cockpit/CP-CHAT-4`.
+
+# A. Envelope — addressed to everyone
+
+## Goal and expected outcome
+
+`django-core-micha/DCM-CHAT-1` adds a shared AI chat core with a fixed WebSocket and REST contract. This order adds the matching surface to ui-core-micha, so that an app shows a complete chat by mounting one component. maana's chat UI (`maana/frontend/src/qda/assistant/`) is the functional template, without its proposals, grants and plan views.
+
+Expected outcome: ui-core-micha exports a chat workspace that lists the user's chats (with archive), streams answers into a thread, renders Markdown safely, shows the sources each answer used, and lets the user pick model and effort per chat. The parts are also exported individually so that an app can arrange them differently.
+
+## Visual spec
+
+Prototype: [`work-orders/assets/UCM-CHAT-1-ai-chat.html`](assets/UCM-CHAT-1-ai-chat.html), drawn in cockpit's theme as the first consumer. It shows:
+- at 1280 px, the main working state;
+- at 375 px, the thread, the chat list drawer and the model picker sheet;
+- a 1280 px gallery of the edge states.
+
+The prototype declares its coverage at the top. The built components take every colour, type and radius from the consuming app's MUI theme, never from literals.
+
+**Parity guardrail:** the prototype governs the look and the interaction only. Behaviour, permissions and the data contract come from `DCM-CHAT-1` and are not changed by anything drawn here.
+
+## Operator decisions this Envelope records (2026-10-15)
+
+- Several persistent chats per user, in a list. Each chat can be renamed, archived and deleted. Archived chats sit behind an "Archived" entry with a count, open read-only, and can be restored.
+- Model and effort are chosen per chat, from the app's catalogue. The picker groups the entries by driver and marks pay-per-use entries. A change applies from the next turn, and the thread marks where the model changed.
+- The sources of each answer appear as chips under it. A chip shows the source's short label, and the full reference appears on hover.
+- A prototype was requested and is the visual spec.
+
+## Scope
+
+- **Workspace component.** At wide widths it has a list column and a thread column. At narrow widths the list becomes a drawer and the picker a bottom sheet; the prototype shows the 375 px arrangement.
+- **Chat list:**
+  - new chat;
+  - select a chat;
+  - per-row overflow menu with Rename, Archive and Delete;
+  - Delete asks for confirmation inside the UI;
+  - the archived section with its count;
+  - restore an archived chat.
+- **Thread:**
+  - user messages;
+  - assistant answers rendered as Markdown, streamed live from `delta` frames;
+  - a typing indicator before the first delta;
+  - a tool-activity chip while a tool runs, labelled with the tool's own label from the `tool` frame;
+  - source chips once the turn completes;
+  - a quiet model and effort line under each answer;
+  - a divider where the model changed between turns;
+  - older turns loaded by cursor when scrolling up.
+- **Composer:** a multi-line input and Send. Stop appears next to Send while a turn runs. Send stays disabled while a turn runs, while the chat is archived, and while the connection is down.
+- **Model and effort picker:** a popover at wide widths and a bottom sheet at narrow widths.
+  - Entries come from the catalogue endpoint, grouped by driver, with the billing tag on pay-per-use entries.
+  - Effort is a segmented control with the four normalised levels. Levels the selected entry does not allow are disabled.
+  - The current selection shows in the thread bar as "model · effort".
+- **Edge states, as drawn:**
+  - a new chat with no messages;
+  - the usage limit reached, with "Change model";
+  - an interrupted answer with an "Interrupted" chip and Retry;
+  - connection lost, with a "Reconnecting" chip;
+  - no model configured on this server;
+  - an archived chat opened.
+- **Socket hook:** one WebSocket per open chat, reconnecting with backoff and no automatic resend. It parses the frames listed in `DCM-CHAT-1`, and on close codes 4401, 4403 and 4429 it stops reconnecting and surfaces the matching state.
+- **API client:** a default implementation of every REST call in `DCM-CHAT-1`. The default set is exported, and a consumer can override single functions while the others keep their defaults.
+  - This avoids the `MessagingProvider` limitation described in `webapp-management/SHARED_CAPABILITIES.md`: there, passing any `api` prop replaces the whole default set.
+- **Markdown rendering** uses `react-markdown` with `remark-gfm`, configured like maana's `MarkdownReply.jsx`: no raw HTML, no images, and links rendered as text. Both packages are new dependencies of this repository. They are approved with this order.
+- **Strings:** all strings are registered through ui-core-micha's i18n contract in a new translations module, in German, English, French and Swahili like the existing modules.
+- **Documentation:** a row in `webapp-management/SHARED_CAPABILITIES.md` for the chat surface, as a small companion change in that repository.
+
+## Copy list (released with this Envelope)
+
+Hint and state texts beyond control labels, verbatim from the prototype:
+- "Usage limit reached for {model}. Choose another model or try again later."
+- "The answer could not be completed."
+- "Chat is not available"
+- "No language model is configured on this server."
+- "pay per use" (catalogue billing tag)
+- Chips: "Interrupted", "Reconnecting", "Archived".
+
+The tool-activity text, for example "Searching the knowledge base", is not ui-core-micha copy. It is the label each app gives its tool.
+
+## Token delta list
+
+None. Drawn from the theme.
+
+## Replaces / removes
+
+Nothing. This is a new surface. The existing `messaging` components stay unchanged.
+
+## Non-goals
+
+- Proposals, plans, grants, context inspection, or anything else from maana's domain UI.
+- Credential entry for own logins or API keys (stage 4, `django-core-micha/DCM-CHAT-3`).
+- Search across chats, sharing, attachments, voice input.
+- Mounting the surface in any app. cockpit does that in `CP-CHAT-4`.
+- Changes to `messaging/`, `notifications/` or the theme factory.
+
+## Tier
+
+Tier 3: a new shared-core surface with new dependencies.
+
+## Risks
+
+- **Markdown as an injection path:** answers can echo text from retrieved documents. The renderer must never interpret raw HTML or load images or links automatically. The allow-list configuration above is the control.
+- **Contract drift:** the component is built against the transport contract of `DCM-CHAT-1` before that module is published. Any deviation found later is a change to that contract, not a local adaptation here.
+- **Theme coupling:** literal colours copied from the prototype would make the component look like cockpit in every app. Colours must come from the theme.
+
+## Required tests to write
+
+- Socket hook:
+  - deltas append to the streaming answer;
+  - the `turn` frame replaces it with the final text and sources;
+  - reconnect without resending;
+  - 4401, 4403 and 4429 stop reconnecting and show their state.
+- Thread:
+  - Markdown renders a list and a table;
+  - raw HTML in an answer is shown as text and not executed;
+  - an image reference is not loaded;
+  - source chips show the label, with the reference on hover;
+  - the model-change divider appears between turns with different selections.
+- Picker:
+  - entries are grouped by driver;
+  - a pay-per-use entry shows its tag;
+  - effort levels the entry does not allow are disabled;
+  - a change calls the update-selection endpoint.
+- Chat list:
+  - rename, archive, restore and delete call their endpoints;
+  - delete asks for confirmation first;
+  - an archived chat disables Send.
+- Edge states: the usage-limit, interrupted and not-configured states render from their error codes.
+- API client: overriding one function keeps the defaults for all others.
+- Translations: every key of the new module exists in all four languages.
+
+# B. Implementation map — addressed to the implementer
+
+## Context package
+
+Work from this package; do not explore broadly. Open only the files named here to verify. Target working directory: `C:/Users/Micha Bigler/Documents/webapps/ui-core-micha` (never the workspace root). Dependencies `react-markdown` 10.1.0 and `remark-gfm` 4.0.1 are already installed in `package.json` and the lockfile; do not touch either.
+
+**Templates to read (maana, read-only, do not edit):** `maana/frontend/src/qda/assistant/` (sibling directory of this repo under the workspace root) — `useAssistantSocket.js` (reconnect with backoff, per-chat socket, close-code mapping), `MarkdownReply.jsx` (the allow-list renderer: copy its approach, but take the table/code region labels from this repo's i18n and colours only from the theme), `ChatThread.jsx`, `ChatList.jsx`, `ChatComposer.jsx`, `ChatWorkspace.jsx` (frame handling around line 118), `assistantApi.js`. Take the structure, not maana's proposals, grants, plans, context dialog or project id. Visual spec: `work-orders/assets/UCM-CHAT-1-ai-chat.html` — read it first; it governs look and interaction, with every colour, radius and type size taken from the MUI theme (palette tokens such as `primary.main`, `text.secondary`, `divider`, `action.hover`, `success/warning/error`), never a literal.
+
+**Repo conventions to match (verify in place):**
+- Source is `.jsx`/`.js` under `src/`, tests in `tests/*.test.jsx` (vitest + @testing-library/react + jsdom); look at `tests/Thread.test.jsx`, `tests/ConversationList.test.jsx` and `tests/MessagingProvider.test.jsx` for how a component is tested here (MUI icons are `vi.mock`ed per test file).
+- HTTP goes through `src/auth/apiClient` exactly like `src/messaging/api.js` (default export `apiClient`, each function returns `response.data`).
+- Strings: `useTranslation()` with keys in a new bundle `src/i18n/chatTranslations.ts` that exports exactly one const `chatTranslations`, entries `{ de, en, fr, sw }`, key prefix `Chat.` (check no key collides with another bundle). Register it in three places: `src/i18n/uiCoreTranslations.js` (spread), `src/index.js` (public export next to `messagingTranslations`), and `tests/i18nAggregate.test.js` (`PUBLIC_BUNDLES` plus its import list). German uses the formal variant.
+- Public exports are added to `src/index.js` in a block next to the messaging block (line ~113). Do not edit `src/messaging/**`, `src/notifications/**` or `src/theme/**`.
+
+## Wire shape (binding on this order; the Orchestrator pinned it from maana's implementation because DCM-CHAT-1 is not published yet)
+
+The Envelope fixes WHICH frames and endpoints exist; the field names below are the working assumption and must be isolated in ONE module (`src/chat/wire.js`: URL builders, frame/field names, the three close codes) so a later contract change touches one file.
+
+- **WebSocket** per chat: URL from a `wsUrl(chatId)` option, default `${ws|wss}://${location.host}/ws/assistant/chats/${chatId}/`. Client frames `{type:"send", message}` and `{type:"stop"}`. Server frames: `{type:"history", turns:[turn…]}` on connect; `{type:"delta", text}`; `{type:"tool", phase:"start"|"end", name, label, sources:[{label, reference}]}`; `{type:"turn", turn}`; `{type:"notice", code, text?}`; `{type:"error", code}` with `code` one of `quota_exceeded`, `provider_error`, `timeout`, `prompt_too_long`, `invalid_output`, `security_violation`, `not_configured`, `rate_limited`, `invalid_selection`, `archived`, `turn_active`, `invalid_frame`. Close codes 4401 -> `session_ended`, 4403 -> `access_lost`, 4429 -> `rate_limited`: no reconnect, state surfaced. Any other close -> reconnect with backoff (1 s, 2 s, 4 s, then stop and show the "connection lost" state with a manual Retry), **never resend a message automatically**; ignore malformed JSON frames.
+- **REST**, base path from an `apiBase` option (default `/api/assistant/`): `GET catalogue/` -> `{entries:[{id, driver, model, label, efforts:["low"|"medium"|"high"|"max"…], billing:"subscription"|"pay_per_use"}], default:{entry, effort}}`; `GET chats/?archived=<bool>&cursor=` -> `{results:[chat…], next}`; `POST chats/` body `{scope?}` -> chat; `PATCH chats/{id}/` body any of `{title, archived, selection:{entry, effort}}` -> chat; `DELETE chats/{id}/`; `GET chats/{id}/turns/?cursor=` -> `{results:[turn…], next}` (newest page first, `next` = cursor for older); `GET status/` -> `{status:"available"|"not_configured"}`.
+- **chat** = `{id, title, archived_at|null, selection:{entry, effort}, updated_at}`. **turn** = `{id, seq, user_text, assistant_text, state:"generating"|"completed"|"failed"|"cancelled"|"interrupted", sources:[{label, reference}], driver, model, effort, error_code|null}`.
+
+## Named files to create (all new; owns `src/chat/**`, `src/i18n/chatTranslations.ts`, `tests/chat*.test.*`, and the three registration edits above)
+
+- `src/chat/wire.js` — constants and URL builders above.
+- `src/chat/api.js` — `createChatApi(overrides = {}, { apiBase })` and the exported `defaultChatApi`: one function per REST call (`getCatalogue, listChats, createChat, updateChat, deleteChat, listTurns, getStatus`) returning `response.data`; `{...defaults, ...overrides}` so overriding one function keeps every other default (the point of this design; contrast `MessagingProvider`).
+- `src/chat/useChatSocket.js` — the hook: `(chatId, {wsUrl, onFrame, onOpen, onClose})` -> `{status, connected, send, reconnect}`. State machine as above. Pass the chat id with every delivered frame so a late frame of a left chat is never applied (maana does this).
+- `src/chat/MarkdownReply.jsx` — allow-list renderer. Allowed elements as maana, `unwrapDisallowed`, links render as text (label plus address when different), images never fetched (alt text or address as text), raw HTML shown as text (no rehype-raw), tables and code in focusable scroll regions, a very long reply falls back to plain text (constant `MARKDOWN_LIMIT`). Styling through `sx` with theme tokens only.
+- `src/chat/ChatThread.jsx` — turns, streaming answer, typing indicator before first delta, tool-activity chip (label from the `tool` frame), source chips (short `label`, full `reference` as tooltip), the quiet "model · effort" line under each answer, a divider between turns whose driver/model/effort differ, older turns loaded by cursor on scroll up/"load older", state chips ("Interrupted" + Retry, "Reconnecting"), and the error states.
+- `src/chat/ChatList.jsx` — new chat, select, per-row overflow menu (Rename, Archive, Delete), Delete confirmation inside a MUI Dialog, "Archived" entry with count, restore of an archived chat, load more.
+- `src/chat/ChatComposer.jsx` — multi-line input, Send, Stop while a turn runs; Send disabled while a turn runs, while the chat is archived, and while the connection is down. Enter sends, Shift+Enter newline.
+- `src/chat/ModelPicker.jsx` — popover (wide) / bottom `Drawer` sheet (narrow, via `useMediaQuery(theme.breakpoints.down('md'))`), entries grouped by driver, "pay per use" tag, effort `ToggleButtonGroup` with levels the entry does not allow disabled; a change calls `updateChat(id, {selection})`; the thread bar shows "model · effort".
+- `src/chat/ChatWorkspace.jsx` — composes list + thread + composer + picker. Props: `apiBase`, `wsUrl`, `api` (partial overrides, merged), `scope`, `sx`. Wide: two columns. Narrow: list in a `Drawer`. Loads status/catalogue, owns the active chat, the streaming state and the edge states: new chat empty state, usage limit (`quota_exceeded` -> "Usage limit reached for {model}. Choose another model or try again later." + "Change model"), interrupted/failed ("The answer could not be completed." + Retry, which re-sends that turn's `user_text` as a new `send` only on the user's click), connection lost ("Reconnecting" chip), `not_configured` ("Chat is not available" / "No language model is configured on this server."), archived (read-only, "Archived" chip, Restore).
+- No `src/chat/index.js`; export from `src/index.js`: `ChatWorkspace, ChatList, ChatThread, ChatComposer, ModelPicker, MarkdownReply, useChatSocket, createChatApi, defaultChatApi, chatTranslations`.
+- `src/i18n/chatTranslations.ts` — every string of the Envelope's copy list verbatim in English, plus control labels, aria-labels and the Markdown region labels; all four languages.
+- Tests (names are guidance): `tests/chatSocket.test.jsx`, `tests/chatThread.test.jsx`, `tests/chatPicker.test.jsx`, `tests/chatList.test.jsx`, `tests/chatEdgeStates.test.jsx`, `tests/chatApi.test.js`, `tests/chatTranslations.test.js`, plus a one-line export check in the style of `tests/messagingExports.test.js`. The socket tests use a fake `WebSocket` class and fake timers.
+
+## Invariants, pitfalls, do-not-touch
+
+- No raw HTML, no image fetch, no auto-loading links anywhere in answers; no `dangerouslySetInnerHTML`. User message text is rendered as plain text.
+- No literal colours, radii or font sizes copied from the prototype; theme tokens and spacing units only. Light and dark themes must both work.
+- Accessibility: the streaming answer sits in a polite live region that is not re-announced on every delta (`aria-busy` while generating), icon buttons have aria-labels, the picker and menus are keyboard operable, touch targets at least 40 px at narrow width.
+- Do not edit `src/messaging/**`, `src/notifications/**`, `src/theme/**`, `package.json`, the lockfile, `README.md`, `CHANGELOG.md` or the register. Docs and the version bump are the Orchestrator's.
+- Package build is `tsc -p tsconfig.build.json` (allowJs, `src` only): new files must compile; `tests/packageTreeShaking.test.js` and `tests/checkKitIntegration.test.jsx` exist: do not introduce a top-level side effect in the new modules.
+- The working tree contains unrelated foreign changes (`WORK_ORDERS.md`, `work-orders/UCM-DEP-1.md`, `package.json`, `pnpm-lock.yaml`): leave them alone.
+
+## Preamble
+
+> The text above is the COMPLETE spec — the committed WO file's content, not a plan to refine; there is no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and the app `MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI unless the spec says so; do not update `MEMORY.md`. **Do NOT edit `WORK_ORDERS.md` — the register row and the review verdicts are the orchestrator's alone.** **Your tools are for editing source and test files and for running the tests you wrote — nothing else.** Do NOT install dependencies, touch a lockfile, run a package manager, or tidy up stray files; if something in the repo state blocks you, stop and report it as `RESULT: BLOCKED <reason>` instead of fixing it. Do NOT `git add`/`commit`/`push` — leave every change uncommitted in the working tree for the orchestrator's independent review. WRITE the tests the `Required tests` section calls for AND **RUN the tests you just wrote** to confirm they execute and pass — that is the ONLY test run you do (NOT the app's affected/full suite, NOT any review). The orchestrator re-runs the authoritative set + does the independent review after you finish — those are the gate; your own run does not count as the gate.
+>
+> Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line `PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final `RESULT: DONE|BLOCKED <reason>`.
+
+
+# C. Orchestrator only — not addressed to the implementer
+
+> **If this WO was dispatched to you as an implementer: STOP here.**
+
+Gate #1 open until recorded in the register row. Can start against the `DCM-CHAT-1` contract in parallel; publish as a new minor version. Prototype in scope: ucm has no host app of its own, so the rendered side-by-side at 375 px and 1280 px runs where the surface is first mounted, in `cockpit/CP-CHAT-4`, and is that order's commit gate; a deviation it finds in the shared components is fixed here and republished.