@everysk/apps-sdk 0.1.0-beta.0

package/src/lib/datastoreTable.ts

@@ -0,0 +1,159 @@
+import type { Datastore } from "@/types/datastore";
+import type { AnyRecord } from "@/types/anyRecord";
+
+type Cell = string | number | null;
+type DatastoreData = Cell[][];
+
+/**
+ * Converts a datastore table (2D array) into an array of objects.
+ *
+ * The input `data` is expected to be a 2D array where:
+ * - Row 0 typically contains the headers (but headers are provided explicitly via `headers`)
+ * - Rows 1..N contain the data values
+ *
+ * Key behaviors:
+ * - Skips the first row of `data` (starts at index 1), assuming it is the header row.
+ * - Adds a `datastoreId` field to every generated object so each record can be traced
+ *   back to its source datastore.
+ * - Maps each header to the corresponding cell value by column index.
+ *
+ * @template T A record type whose values are compatible with `Cell` (string | number | null).
+ *
+ * @param datastoreId The id of the datastore to attach to each row as `datastoreId`.
+ * @param headers The column names used as object keys (positionally aligned with row cells).
+ * @param data The datastore matrix (rows x columns). Row 0 is assumed to be headers.
+ *
+ * @returns An array of objects (one per data row), each containing:
+ * - `datastoreId`
+ * - one property per header (with the corresponding cell value)
+ *
+ * @example
+ * const headers = ["name", "age"];
+ * const data = [
+ *   ["name", "age"],
+ *   ["Alice", 30],
+ *   ["Bob", null],
+ * ];
+ * const rows = tableToObjects("ds_123", headers, data);
+ * // [
+ * //   { datastoreId: "ds_123", name: "Alice", age: 30 },
+ * //   { datastoreId: "ds_123", name: "Bob", age: null }
+ * // ]
+ */
+export const tableToObjects = <T extends Record<string, Cell>>(datastoreId: string, headers: string[], data: DatastoreData): T[] => {
+  const result: T[] = [];
+
+  for (let i = 1; i < data?.length; i++) {
+    const item: Record<string, Cell> = {};
+
+    item.datastoreId = datastoreId;
+
+    headers.forEach((header: string, index: number) => {
+      item[header] = data[i][index];
+    });
+
+    result.push(item as T);
+  }
+
+  return result;
+};
+
+/**
+ * Converts an array of objects into a datastore table (2D array).
+ *
+ * Key behaviors:
+ * - Produces a 2D array where the first row is the provided `headers`.
+ * - For each object in `data`, creates a row by mapping `headers` to values in the object.
+ * - If a header is missing in an object, the corresponding cell is set to `null`.
+ *
+ * @template T A record type whose values are compatible with `Cell` (string | number | null).
+ *
+ * @param headers Column names (and output table header row).
+ * @param data Array of objects to convert into rows.
+ *
+ * @returns A datastore matrix where:
+ * - Row 0 is `headers`
+ * - Rows 1..N contain cell values aligned with `headers`
+ *
+ * @example
+ * const headers = ["name", "age"];
+ * const rows = objectsToTable(headers, [
+ *   { name: "Alice", age: 30 },
+ *   { name: "Bob" }, // age missing -> null
+ * ]);
+ * // [
+ * //   ["name", "age"],
+ * //   ["Alice", 30],
+ * //   ["Bob", null]
+ * // ]
+ */
+export const objectsToTable = <T extends Record<string, Cell>>(headers: string[] ,data: T[]): DatastoreData => {
+  const rows: DatastoreData = data.map((d) => headers.map<Cell>((h) => d[h as string] ?? null));
+
+  return [headers, ...rows];
+};
+
+/**
+ * Flattens multiple datastore row arrays into a single array.
+ *
+ * This is typically used after fetching multiple datastores, where each datastore is
+ * represented as `AnyRecord[]` (i.e., an array of row objects).
+ *
+ * @param datastores A list of datastores, each represented as an array of row objects.
+ *
+ * @returns A single array containing all rows from all datastores, in the same order.
+ *
+ * @example
+ * const merged = mergeDatastores([
+ *   [{ datastoreId: "a", x: 1 }],
+ *   [{ datastoreId: "b", x: 2 }, { datastoreId: "b", x: 3 }],
+ * ]);
+ * // [{...}, {...}, {...}]
+ */
+export const mergeDatastores = (datastores: AnyRecord[][]): AnyRecord[] => {
+  const result: AnyRecord[] = [];
+
+  datastores.forEach((datastore: AnyRecord[]) => {
+    result.push(...datastore);
+  });
+
+  return result;
+};
+
+/**
+ * buildDatastoreProps
+ *
+ * Extracts and maps the metadata properties of a `Datastore` into a plain object
+ * for UI usage, discarding raw data rows.
+ *
+ * - `header` is derived from `datastore.data?.[0]` (the first row of the data matrix),
+ *   which is expected to contain the column names. Falls back to `[]` if not present.
+ *
+ * @param {Datastore} datastore - The source datastore object.
+ * @returns Metadata object with the datastore's descriptive properties and header.
+ *
+ * @example
+ * const meta = buildDatastoreProps(datastore);
+ * // {
+ * //   name: "my-datastore",
+ * //   workspace: "ws-1",
+ * //   header: ["col1", "col2"],
+ * //   ...
+ * // }
+ */
+export const buildDatastoreProps = (datastore: Datastore) => {
+    return {
+        name: datastore.name,
+        date: datastore.date,
+        version: datastore.version,
+        description: datastore.description,
+        tags: datastore.tags,
+        link_uid: datastore.link_uid,
+        workspace: datastore.workspace,
+        date_time: datastore.date_time,
+        created: datastore.created,
+        updated: datastore.updated,
+        level: datastore.level,
+        header: datastore.data?.[0] || [],
+    };
+};

package/src/lib/queryClient.ts

@@ -0,0 +1,60 @@
+import { QueryClient, type QueryClientConfig, type QueryFunction } from "@tanstack/react-query";
+
+async function throwIfResNotOk(res: Response) {
+    if (!res.ok) {
+        const text = (await res.text()) || res.statusText;
+        throw new Error(`${res.status}: ${text}`);
+    }
+}
+
+type UnauthorizedBehavior = "returnNull" | "throw";
+export const getQueryFn: <T>(options: {
+    on401: UnauthorizedBehavior;
+}) => QueryFunction<T> =
+    ({ on401: unauthorizedBehavior }) =>
+        async ({ queryKey }) => {
+            const res = await fetch(queryKey.join("/") as string, {
+                credentials: "include",
+            });
+
+            if (unauthorizedBehavior === "returnNull" && res.status === 401) {
+                return null;
+            }
+
+            await throwIfResNotOk(res);
+            return await res.json();
+        };
+
+/**
+ * createQueryClient
+ *
+ * Builds a `QueryClient` carrying the defaults every Everysk app shares: the fetch-based
+ * `queryFn` above, no retries, no refetch on focus or interval, and `staleTime: Infinity`.
+ *
+ * This is a factory rather than the shared instance the template exported. A module-level
+ * `new QueryClient()` inside a published package is a single cache shared by every consumer
+ * of that copy of the module: it cannot be configured per app, it cannot be reset, and in
+ * tests it leaks state from one case into the next. The app owns the instance and passes it
+ * to `QueryClientProvider` — `EveryskApp` does this for you when you don't pass one.
+ *
+ * @param {QueryClientConfig} [config] - Merged over the defaults, one level deep, so passing
+ *  `defaultOptions.queries` replaces the whole `queries` object rather than merging into it.
+ * @returns {QueryClient} A fresh client.
+ */
+export const createQueryClient = (config?: QueryClientConfig): QueryClient =>
+    new QueryClient({
+        ...config,
+        defaultOptions: {
+            queries: {
+                queryFn: getQueryFn({ on401: "throw" }),
+                refetchInterval: false,
+                refetchOnWindowFocus: false,
+                staleTime: Infinity,
+                retry: false,
+            },
+            mutations: {
+                retry: false,
+            },
+            ...config?.defaultOptions,
+        },
+    });

package/src/portfolio/index.ts

@@ -0,0 +1,13 @@
+// The portfolio entity slice: API calls, entity hooks and types.
+//
+// Re-exported from the package root rather than its own subpath: nothing here carries an
+// optional peer, so there is nothing for a subpath to isolate.
+//
+// `export *` rather than a hand-written list: a slice is exactly "everything these modules
+// expose", and an enumerated list silently drops an export when the slice grows.
+
+export * from "@/api/portfolio";
+export * from "@/types/portfolio";
+export * from "@/hooks/portfolio/useFetchPortfolio";
+export * from "@/hooks/portfolio/useFetchPortfolios";
+export * from "@/hooks/portfolio/usePortfolioMutations";

package/src/profile/index.ts

@@ -0,0 +1,11 @@
+// The profile entity slice: API calls, entity hooks and types.
+//
+// Re-exported from the package root rather than its own subpath: nothing here carries an
+// optional peer, so there is nothing for a subpath to isolate.
+//
+// `export *` rather than a hand-written list: a slice is exactly "everything these modules
+// expose", and an enumerated list silently drops an export when the slice grows.
+
+export * from "@/api/profile";
+export * from "@/types/profile";
+export * from "@/hooks/profile/useFetchProfile";

package/src/socket/index.ts

@@ -0,0 +1,19 @@
+// `@everysk/apps-sdk/socket` — real-time notifications over Socket.IO.
+//
+// `socket.io-client` is an OPTIONAL peer, so an app without real-time features does not
+// install it.
+//
+// This layer supersedes the broadcast channel context that used to be a core provider: it
+// covers both cross-tab messaging and server push, which is what `modules.json` already said
+// about the `socket` module. `WebSocketProvider` only needs to wrap its children, so it goes
+// in `EveryskApp`'s `providers` array rather than into a named slot.
+
+export * from "@/contexts/webSocketContext";
+export * from "@/contexts/webSocketContext/provider";
+export * from "@/contexts/webSocketContext/types";
+export * from "@/contexts/webSocketContext/constants";
+export * from "@/contexts/webSocketContext/handler";
+export * from "@/contexts/webSocketContext/hooks/useWebSocket";
+export * from "@/contexts/webSocketContext/hooks/useWebSocketSubscription";
+export * from "@/contexts/webSocketContext/hooks/useAppNotificationSubscription";
+export * from "@/api/websocketsConfig";

package/src/test/index.ts

@@ -0,0 +1,10 @@
+// `@everysk/apps-sdk/test` — helpers for testing apps built on the SDK.
+//
+// A separate subpath so the testing-library peers stay optional: an app that never imports
+// this entry point does not need them installed.
+
+export {
+    renderWithProviders,
+    renderHookWithProviders,
+    createTestQueryClient,
+} from "./renderWithProviders";

package/src/test/mocks/agGridEnterprise.ts

@@ -0,0 +1,45 @@
+let lastKey: string | null = null;
+
+/**
+ * agGridEnterpriseMock
+ *
+ * A stand-in for `ag-grid-enterprise`, for a test that renders something registering the AG Grid
+ * licence. The real `LicenseManager` validates the key and warns on the console when it does not
+ * like it, which is noise a test neither needs nor should depend on.
+ *
+ * ```ts
+ * import { getAgGridLicenseKey } from "@everysk/apps-sdk/test/mocks";
+ *
+ * vi.mock("ag-grid-enterprise", async () =>
+ *   (await import("@everysk/apps-sdk/test/mocks")).agGridEnterpriseMock(),
+ * );
+ *
+ * it("registers the licence the app passes", () => {
+ *   render(<App />);
+ *   expect(getAgGridLicenseKey()).toBe("test-key");
+ * });
+ * ```
+ *
+ * `setLicenseKey` is a plain function rather than a `vi.fn`, and the key is captured at module
+ * level, for the same reason the socket double is built that way: a config with `restoreMocks`
+ * wipes a `vi.fn`'s implementation between tests, so a spy created inside the factory stops
+ * recording after the first case. Reading the captured key works whatever the config does.
+ *
+ * Opt-in, never applied from the shared setup file — `ag-grid-enterprise` is an OPTIONAL peer,
+ * and `vi.mock` on a module that cannot be resolved fails the whole test file at transform time.
+ */
+export const agGridEnterpriseMock = () => ({
+    LicenseManager: {
+        setLicenseKey: (key: string) => {
+            lastKey = key;
+        },
+    },
+});
+
+/** The licence key last registered, or null when nothing registered one. */
+export const getAgGridLicenseKey = (): string | null => lastKey;
+
+/** Drops the captured key between tests. */
+export const resetAgGridLicense = (): void => {
+    lastKey = null;
+};

package/src/test/mocks/agGridReact.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode } from "react";
+
+type ColumnDef = { field?: string; headerName?: string };
+type Row = Record<string, unknown>;
+
+type AgGridReactProps = {
+    rowData?: Row[] | null;
+    columnDefs?: ColumnDef[] | null;
+    children?: ReactNode;
+};
+
+/**
+ * agGridReactMock
+ *
+ * A stand-in for `ag-grid-react` that renders the data as plain DOM instead of running AG
+ * Grid's layout, virtualisation and ResizeObserver work — which is what makes grid tests slow
+ * under jsdom.
+ *
+ * It is deliberately not a black box: rows and cells are rendered with test ids, so
+ * assertions about *what the grid was given* keep working. Only the rendering engine is gone.
+ *
+ * ```tsx
+ * import { agGridReactMock } from "@everysk/apps-sdk/test/mocks";
+ *
+ * vi.mock("ag-grid-react", agGridReactMock);
+ *
+ * it("lists the portfolios", () => {
+ *   renderWithProviders(<PortfolioGrid />);
+ *   expect(screen.getAllByTestId("ag-grid-row")).toHaveLength(3);
+ *   expect(screen.getByTestId("ag-grid-cell-name")).toHaveTextContent("Fund A");
+ * });
+ * ```
+ *
+ * Opt-in on purpose. Applying this from the shared setup file would mock `ag-grid-react` for
+ * every app — including apps that never installed it, since it is an *optional* peer, and
+ * `vi.mock` on a module that cannot be resolved fails the whole test file at transform time.
+ */
+export const agGridReactMock = () => ({
+    AgGridReact: ({ rowData, columnDefs, children }: AgGridReactProps) => {
+        const rows = rowData ?? [];
+        const columns = columnDefs ?? [];
+
+        return (
+            <div data-testid="ag-grid" data-row-count={rows.length}>
+                {rows.map((row, index) => (
+                    <div key={index} data-testid="ag-grid-row">
+                        {columns.map((column) => (
+                            <span
+                                key={column.field ?? column.headerName}
+                                data-testid={`ag-grid-cell-${column.field ?? ""}`}
+                            >
+                                {String(row[column.field ?? ""] ?? "")}
+                            </span>
+                        ))}
+                    </div>
+                ))}
+                {children}
+            </div>
+        );
+    },
+});

package/src/test/mocks/index.ts

@@ -0,0 +1,22 @@
+// `@everysk/apps-sdk/test/mocks` — ready-made doubles for the slow or connection-bound
+// third-party packages the SDK's optional layers sit on.
+//
+// All opt-in: each is a factory a test file hands to `vi.mock`, never applied from the shared
+// setup file. Two reasons. A mock nobody declared is hard to debug when it surprises someone,
+// and `ag-grid-react`, `ag-grid-enterprise` and `socket.io-client` are *optional* peers — `vi.mock` on a module that
+// cannot be resolved fails the entire test file at transform time, so a global mock would
+// break every suite in an app that never installed them.
+
+export { agGridReactMock } from "./agGridReact";
+export {
+    agGridEnterpriseMock,
+    getAgGridLicenseKey,
+    resetAgGridLicense,
+} from "./agGridEnterprise";
+export {
+    socketIoClientMock,
+    createMockSocket,
+    getMockSocket,
+    resetMockSocket,
+} from "./socketIoClient";
+export type { MockSocket, SocketEventHandler } from "./socketIoClient";

package/src/test/mocks/socketIoClient.ts

@@ -0,0 +1,78 @@
+import { vi, type Mock } from "vitest";
+
+export type SocketEventHandler = (...args: unknown[]) => void;
+
+// Typed with `Mock<signature>` rather than `ReturnType<typeof vi.fn>`: the latter erases the
+// call signature, leaving the methods uncallable for a TypeScript consumer of this mock.
+export type MockSocket = {
+    on: Mock<(event: string, handler: SocketEventHandler) => void>;
+    emit: Mock<(event: string, ...args: unknown[]) => void>;
+    removeAllListeners: Mock<() => void>;
+    disconnect: Mock<() => void>;
+    /** Every handler registered through `on`, keyed by event name. */
+    handlers: Record<string, SocketEventHandler>;
+    /** Invokes a registered handler, as the server would. No-op if nothing listens. */
+    fire: (event: string, ...args: unknown[]) => void;
+};
+
+let lastSocket: MockSocket | null = null;
+
+/** Builds a fake socket. Exported for tests that want one without mocking the module. */
+export const createMockSocket = (): MockSocket => {
+    const handlers: Record<string, SocketEventHandler> = {};
+
+    const socket: MockSocket = {
+        handlers,
+        on: vi.fn((event: string, handler: SocketEventHandler) => {
+            handlers[event] = handler;
+        }),
+        emit: vi.fn(),
+        removeAllListeners: vi.fn(),
+        disconnect: vi.fn(),
+        fire: (event, ...args) => handlers[event]?.(...args),
+    };
+
+    return socket;
+};
+
+/**
+ * socketIoClientMock
+ *
+ * A stand-in for `socket.io-client`: `io()` returns a fake socket that records listeners
+ * instead of opening a connection. Reach the socket with `getMockSocket()` and drive it with
+ * `fire(event, payload)`.
+ *
+ * Because `vi.mock` is hoisted above every import, the factory cannot close over a binding
+ * from this module directly — load it inside the factory:
+ *
+ * ```ts
+ * import { getMockSocket } from "@everysk/apps-sdk/test/mocks";
+ *
+ * vi.mock("socket.io-client", async () =>
+ *   (await import("@everysk/apps-sdk/test/mocks")).socketIoClientMock(),
+ * );
+ *
+ * it("reacts to a notification", () => {
+ *   render(...);
+ *   act(() => getMockSocket()?.fire("notification", { type: "DONE" }));
+ * });
+ * ```
+ */
+export const socketIoClientMock = () => ({
+    // A plain function, not a vi.fn, and the socket is built per call rather than once when
+    // the factory runs. Both matter under this config: `restoreMocks: true` wipes a vi.fn's
+    // implementation between tests, and a socket created at factory time would be shared by
+    // every test in the file — and destroyed by the first `resetMockSocket()`.
+    io: () => {
+        lastSocket = createMockSocket();
+        return lastSocket;
+    },
+});
+
+/** The socket handed out by the most recent `io()` call. */
+export const getMockSocket = (): MockSocket | null => lastSocket;
+
+/** Drops the reference between tests. */
+export const resetMockSocket = (): void => {
+    lastSocket = null;
+};

package/src/test/renderWithProviders.tsx

@@ -0,0 +1,114 @@
+import type { ReactElement } from "react";
+
+import {
+    render,
+    renderHook,
+    type RenderOptions,
+    type RenderHookOptions,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient } from "@tanstack/react-query";
+
+import { EveryskApp, type ProviderComponent } from "@/EveryskApp";
+import type { AnyRecord } from "@/types/anyRecord";
+
+/**
+ * Test wrapper for apps built on this SDK.
+ *
+ * It renders through `EveryskApp` — the very component the app mounts — rather than
+ * re-listing the providers. The template's version duplicated the `App.tsx` tree and had to
+ * be kept in sync by hand, which is how you get a suite that passes while the app is broken.
+ *
+ * Each render gets a FRESH QueryClient with retries off and caching disabled, so tests never
+ * share server state. Pass your own via `options.queryClient` to seed the cache or assert on
+ * it. Optional providers (AG Grid's license, the socket provider) are not mounted by default:
+ * pass them in `options.providers` — the template's version wrapped every test in the
+ * broadcast provider, which is one of the things that kept it alive with no consumer.
+ */
+
+/** Build an isolated QueryClient for a single test (no retries, no caching). */
+export function createTestQueryClient(): QueryClient {
+    return new QueryClient({
+        defaultOptions: {
+            queries: { retry: false, gcTime: 0, staleTime: 0, refetchOnWindowFocus: false },
+            mutations: { retry: false },
+        },
+    });
+}
+
+type ProviderOptions = {
+    queryClient?: QueryClient;
+    /** Extra providers, mounted inside the core tree and around the subject. */
+    providers?: ProviderComponent[];
+    /** Injected instead of `window.APP_ID`, so a test needs no page globals. */
+    appId?: string | null;
+    /** Injected instead of `window.APP_CONFIG`. */
+    appEnvironmentVar?: AnyRecord;
+};
+
+const buildWrapper = ({ queryClient, providers, appId, appEnvironmentVar }: ProviderOptions & {
+    queryClient: QueryClient;
+}) =>
+    function Wrapper({ children }: { children?: React.ReactNode }) {
+        return (
+            <EveryskApp
+                queryClient={queryClient}
+                providers={providers}
+                appId={appId}
+                appEnvironmentVar={appEnvironmentVar}
+            >
+                {children}
+            </EveryskApp>
+        );
+    };
+
+/**
+ * Render a component inside the core provider tree.
+ *
+ * Returns everything from RTL's `render`, plus a ready `user` (userEvent.setup()) and the
+ * `queryClient` used, so assertions can reach the cache.
+ */
+export function renderWithProviders(
+    ui: ReactElement,
+    options: ProviderOptions & Omit<RenderOptions, "wrapper"> = {},
+) {
+    const {
+        queryClient = createTestQueryClient(),
+        providers,
+        appId,
+        appEnvironmentVar,
+        ...renderOptions
+    } = options;
+    const user = userEvent.setup();
+
+    const result = render(ui, {
+        wrapper: buildWrapper({ queryClient, providers, appId, appEnvironmentVar }),
+        ...renderOptions,
+    });
+
+    return { user, queryClient, ...result };
+}
+
+/**
+ * Render a hook inside the core provider tree (for entity hooks that need QueryClient,
+ * AppAlert, AppConfig, etc.).
+ */
+export function renderHookWithProviders<Result, Props>(
+    hook: (initialProps: Props) => Result,
+    options: ProviderOptions & Omit<RenderHookOptions<Props>, "wrapper"> = {},
+) {
+    const {
+        queryClient = createTestQueryClient(),
+        providers,
+        appId,
+        appEnvironmentVar,
+        ...hookOptions
+    } = options;
+
+    const result = renderHook(hook, {
+        wrapper: buildWrapper({ queryClient, providers, appId, appEnvironmentVar }),
+        ...hookOptions,
+    });
+
+    return { queryClient, ...result };
+}

package/src/test/setup.ts

@@ -0,0 +1,46 @@
+import { afterEach, vi } from "vitest";
+import { cleanup } from "@testing-library/react";
+
+import "@testing-library/jest-dom/vitest";
+
+// Unmount React trees and clear the jsdom document between tests so they stay isolated.
+afterEach(() => {
+  cleanup();
+});
+
+// jsdom does not implement matchMedia; MUI's `useMediaQuery` needs it. The theme no longer
+// reads it — it is pinned to the brand dark theme — but responsive components still do.
+if (!window.matchMedia) {
+  window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));
+}
+
+// jsdom does not implement ResizeObserver; several MUI components observe their container.
+if (!globalThis.ResizeObserver) {
+  globalThis.ResizeObserver = class {
+    observe(): void {}
+    unobserve(): void {}
+    disconnect(): void {}
+  };
+}
+
+// The template stubbed `BroadcastChannel` here, which jsdom does not implement. Nothing in
+// the SDK constructs one any more — the broadcast context is gone, superseded by the socket
+// layer — so the stub would only be dead setup. Whatever needs it can bring its own.
+
+// Deliberately no `window.APP_ID` / `window.APP_CONFIG` defaults here.
+//
+// The template seeded them ("app_template", {}) because its providers read the globals
+// directly and would otherwise see nothing. The SDK's providers handle absence on their own —
+// `AppConfigProvider` reports `appId: null`, `BroadcastChannelProvider` falls back to its own
+// channel name — and seeding the globals would hide exactly that path from the suite, which is
+// the path every consumer hits in dev. A test that needs configuration injects it:
+// `renderWithProviders(ui, { appId, appEnvironmentVar })`.

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,33 @@
+import type React from "react";
+
+import CssBaseline from "@mui/material/CssBaseline";
+import type { Theme } from "@mui/material/styles";
+import { ThemeProvider as MuiThemeProvider } from "@mui/material/styles";
+
+import { getBrandTheme } from "./themes";
+
+/**
+ * The default an app mounts: the Everysk dark theme.
+ *
+ * Resolved once, at module load. It deliberately does not follow the OS `prefers-color-scheme`
+ * — doing that rendered the app light on a light desktop while every surrounding platform
+ * screen stayed dark. Choosing a theme is a decision the app makes about the surface it is
+ * embedded in, not one the viewer's laptop makes for it.
+ */
+const defaultTheme: Theme = getBrandTheme("dark");
+
+export type ThemeProviderProps = React.PropsWithChildren<{
+    /**
+     * Overrides the default. Pass one of the catalog's themes, or any MUI theme of your own —
+     * `getTheme("Midnight Ember")`, `getBrandTheme("light")` for a light host, or a
+     * `createTheme` result. Omitted, the app gets the Everysk dark theme.
+     */
+    theme?: Theme;
+}>;
+
+export const ThemeProvider = ({ children, theme }: ThemeProviderProps) => (
+    <MuiThemeProvider theme={theme ?? defaultTheme}>
+        <CssBaseline />
+        {children}
+    </MuiThemeProvider>
+);