@oxy.so/services 13.5.0 → 13.7.0

package/lib/typescript/module/ui/utils/entryLink.d.ts

@@ -0,0 +1,8 @@
+import { type CampaignAttribution } from '@oxy.so/contracts/client';
+export declare function readCampaignAttribution(value: unknown): CampaignAttribution | undefined;
+/** Consumes only explicit locale/campaign parameters, never the URL or referrer itself. */
+export declare function readEntryLink(url: string | null): {
+    language?: string;
+    campaignAttribution?: CampaignAttribution;
+};
+//# sourceMappingURL=entryLink.d.ts.map

package/lib/typescript/module/ui/utils/entryLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entryLink.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/entryLink.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAC;AAWlC,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAavF;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C,CAuBA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/services",
-  "version": "13.5.0",
+  "version": "13.7.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -151,7 +151,7 @@
     "delete-dts.js": "find ./lib/commonjs -name '*.d.js*' -delete && find ./lib/module -name '*.d.js*' -delete"
   },
   "dependencies": {
-    "@oxy.so/contracts": "^6.0.0",
+    "@oxy.so/contracts": "^6.1.0",
     "color": "^5.0.3",
     "@peable.to/sdk": "0.4.1"
   },
@@ -160,7 +160,7 @@
     "@commitlint/config-conventional": "^21.2.0",
     "@expo/app-integrity": "~58.0.2",
     "@expo/vector-icons": "^15.0.3",
-    "@oxy.so/core": "7.2.0",
+    "@oxy.so/core": "7.6.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^12.0.1",
     "@react-native/babel-preset": "^0.88.0",
@@ -210,13 +210,13 @@
     "expo-video": "~58.0.12"
   },
   "//@oxy.so/bloom": "Bloom 11.1.0 adds the shared grouped sections, usage card, subscription plans, frame appearance and overlay navigation APIs used by this SDK. First-party Bloom peers remain open above this tested minimum.",
-  "//@oxy.so/core": "Core 7.2.0 supplies `assets.cachedUrl`, with which `useFileDownloadUrl` answers an already-resolved URL in its first render; 6.16.0 supplies `requireServerVerdict` and `onHolderRejected`, with which the cold boot checks a session it painted from the cache; 6.13.0 supplies the `accounts.settings.*` strings (picture, categories) the account settings speak in every language; 6.12.0 supplies `fileManagement.contentLost` and the `lost` file status a lost file is listed with; 6.11.0 supplies the `follow.errors.*` strings the follow error codes are worded with; 6.4.0 the `follow.*` strings the follow buttons read for every verb and language; 6.1.0 the `oxy.auth.email.{startChange,change,remove}` and `oxy.auth.password.remove` the sign-in & security panels call. Keep one Core instance per app; raise this floor with the root catalogue when new runtime APIs are required.",
+  "//@oxy.so/core": "Core 7.6.0 forwards guest locale and first-touch campaign metadata through signup; 7.3.0 supplies `users.lookupMany`, with which the account members screen fails (and retries) a profile read whose chunk failed instead of caching those members as handle-less; 7.2.0 supplies `assets.cachedUrl`, with which `useFileDownloadUrl` answers an already-resolved URL in its first render; 6.16.0 supplies `requireServerVerdict` and `onHolderRejected`, with which the cold boot checks a session it painted from the cache; 6.13.0 supplies the `accounts.settings.*` strings (picture, categories) the account settings speak in every language; 6.12.0 supplies `fileManagement.contentLost` and the `lost` file status a lost file is listed with; 6.11.0 supplies the `follow.errors.*` strings the follow error codes are worded with; 6.4.0 the `follow.*` strings the follow buttons read for every verb and language; 6.1.0 the `oxy.auth.email.{startChange,change,remove}` and `oxy.auth.password.remove` the sign-in & security panels call. Keep one Core instance per app; raise this floor with the root catalogue when new runtime APIs are required.",
   "//react-native": "React Native 0.81 to 0.88, React 19.1+ and Expo SDK 54 to 58. The floors are the Expo SDK 54 stack (react-native 0.81.6, react 19.1.4, react-native-web 0.21.4, expo 54.0.38 and the module versions its bundledNativeModules.json pins), which compat/expo-54 installs as an external consumer and checks on every CI run (`bun check.mjs`): every peer here admits that stack, services' published src typechecks against its types, and <OxyProvider> mounts and settles its cold boot on iOS (React Native 0.81), web (react-native-web 0.21) and react-native-macos 0.81 with the native modules macOS lacks absent. Astro, Oxy's browser, runs react-native-macos 0.81 (0.83 is its latest release), which is why the floor is not 0.85. The SDK 56 floors these replaced were the versions current when the ranges were first written, not measurements.",
   "peerDependencies": {
     "@expo/app-integrity": ">=0.1.10 <59.0.0",
     "@expo/vector-icons": "^15.0.3",
     "@oxy.so/bloom": ">=11.1.0",
-    "@oxy.so/core": "^7.2.0",
+    "@oxy.so/core": "^7.6.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": ">=11.4.1 <13.0.0",
     "@tanstack/query-async-storage-persister": "^5.101",

package/src/ui/components/AccountLanguageBoundary.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+import { FALLBACK_LOCALE, getPrimaryLanguage } from '@oxy.so/core';
+import { useOxy } from '../context/oxyRuntimeContext';
+import { useCurrentUser } from '../hooks/queries/useAccountQueries';
+import type { OxyLanguageConfig } from '../types/navigation';
+import { LanguageBridge } from './LanguageBridge';
+
+/** Owner preferences are not part of the public device/account summary. */
+export function AccountLanguageBoundary({
+  language,
+  children,
+}: {
+  language?: OxyLanguageConfig;
+  children: ReactNode;
+}) {
+  const { canUsePrivateApi, user, currentLanguage } = useOxy();
+  const profile = useCurrentUser({ enabled: canUsePrivateApi });
+  // The query mirrors its result into the account runtime in an effect. Wait for
+  // that projection as well as the request, so the bridge never publishes the
+  // compact session's fallback locale in the frame before its real preference.
+  const accountReady =
+    !user ||
+    !canUsePrivateApi ||
+    profile.fetchStatus === 'paused' ||
+    user.languages !== undefined ||
+    profile.isError ||
+    (profile.dataUpdatedAt > 0 &&
+      profile.data?.id === user.id &&
+      currentLanguage === (getPrimaryLanguage(profile.data) ?? FALLBACK_LOCALE));
+  return (
+    <LanguageBridge config={language} accountReady={accountReady}>
+      {children}
+    </LanguageBridge>
+  );
+}

package/src/ui/components/LanguageBridge.tsx

@@ -1,49 +1,53 @@
-import { useEffect, useMemo, useRef } from 'react';
+import { useEffect, useRef, useState, type ReactNode } from 'react';
 import { coerceToSupportedLocale } from '@oxy.so/core';
 import { useOxy } from '../context/oxyRuntimeContext';
 import type { OxyLanguageConfig } from '../types/navigation';
 
-/**
- * `OxyProvider`'s language config prop, realized. Oxy decides which
- * language an account (or, signed out, the device/guest locale) should see;
- * this is the ONE place that decision reaches the host app's own i18n library
- * — so an app never re-derives or imperatively tracks a language of its own,
- * and never mounts anything extra to get it. It owns only its translation
- * catalogs.
- *
- * `currentLanguage` may name a locale the host app never shipped a catalog
- * for — {@link coerceToSupportedLocale} narrows it to the closest one the app
- * actually has (exact match, then same base language, then `fallbackLocale`).
- *
- * Renders nothing. Mounted by `OxyProvider` INSIDE `OxyRuntimeProvider` only
- * when this config is supplied, so an app with no i18n of its own pays
- * nothing.
- */
+/** The SDK resolves the entry/account locale before exposing translated app content. */
 export function LanguageBridge({
-  supportedLocales,
-  fallbackLocale,
-  onChange,
-  onError,
-}: OxyLanguageConfig): null {
-  const { currentLanguage } = useOxy();
-  const resolvedLocale = useMemo(
-    () => coerceToSupportedLocale(currentLanguage, supportedLocales, fallbackLocale),
-    [currentLanguage, supportedLocales, fallbackLocale],
-  );
-
-  // Refs, not effect dependencies: an inline `onChange`/`onError` (the common
-  // case) must not re-fire the effect on every render — only a genuine
-  // change in the RESOLVED locale should call it again.
-  const onChangeRef = useRef(onChange);
-  onChangeRef.current = onChange;
-  const onErrorRef = useRef(onError);
-  onErrorRef.current = onError;
+  config,
+  accountReady = true,
+  children,
+}: {
+  config?: OxyLanguageConfig;
+  accountReady?: boolean;
+  children: ReactNode;
+}) {
+  const { currentLanguage, isLanguageReady, isAuthResolved } = useOxy();
+  const resolvedLocale = config
+    ? coerceToSupportedLocale(currentLanguage, config.supportedLocales, config.fallbackLocale)
+    : currentLanguage;
+  const configRef = useRef(config);
+  configRef.current = config;
+  const pendingChange = useRef(Promise.resolve());
+  const [prepared, setPrepared] = useState(false);
 
   useEffect(() => {
-    Promise.resolve(onChangeRef.current(resolvedLocale)).catch((error: unknown) => {
-      onErrorRef.current?.(error, resolvedLocale);
+    if (!isLanguageReady || !isAuthResolved || !accountReady) return;
+    let active = true;
+    // A slow earlier catalog must finish before a later locale is committed.
+    // Children stay mounted after boot: changing language never destroys route state.
+    pendingChange.current = pendingChange.current.then(async () => {
+      if (!active) return;
+      const current = configRef.current;
+      try {
+        await current?.onChange(resolvedLocale);
+      } catch (error) {
+        current?.onError?.(error, resolvedLocale);
+        if (current && resolvedLocale !== current.fallbackLocale) {
+          try {
+            await current.onChange(current.fallbackLocale);
+          } catch (fallbackError) {
+            current.onError?.(fallbackError, current.fallbackLocale);
+          }
+        }
+      }
+      if (active) setPrepared(true);
     });
-  }, [resolvedLocale]);
+    return () => {
+      active = false;
+    };
+  }, [accountReady, isAuthResolved, isLanguageReady, resolvedLocale]);
 
-  return null;
+  return !config || prepared ? children : null;
 }

package/src/ui/components/OxyProvider.tsx

@@ -20,19 +20,10 @@ import { isNetConnectivityOnline } from '../utils/netConnectivity';
 import { KeyboardBoundary } from './KeyboardBoundary';
 import { SafeAreaRoot } from './SafeAreaRoot';
 import { ProductAnalyticsObserver } from '../analytics/productAnalytics';
-import { LanguageBridge } from './LanguageBridge';
+import { AccountLanguageBoundary } from './AccountLanguageBoundary';
 import { BloomLocaleBridge } from './BloomLocaleBridge';
-import { useOxy } from '../context/oxyRuntimeContext';
-import { useCurrentUser } from '../hooks/queries/useAccountQueries';
 import { SupervisionStateObserver } from '../hooks/queries/useSupervision';
 
-/** Hydrate owner preferences after the bearer is ready, including on cold boot. */
-function AccountProfileObserver() {
-  const { canUsePrivateApi } = useOxy();
-  useCurrentUser({ enabled: canUsePrivateApi });
-  return null;
-}
-
 const bootStyles = StyleSheet.create({
   providerRoot: {
     flex: 1,
@@ -114,6 +105,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
   requireAuth = 'off',
   backgroundSession = false,
   language,
+  campaignAttribution = false,
 }) => {
   const support = useMemo(
     () => ({ onAskAlia, documentationUrl, aliaAvatar, oxyOneArtwork }),
@@ -279,26 +271,28 @@ const OxyProvider: FC<OxyProviderProps> = ({
         sessionMode={sessionMode}
         webAuthMode={webAuthMode}
         backgroundSession={backgroundSession}
+        legacyLanguageKeys={language?.legacyStorageKeys}
+        captureCampaignAttribution={campaignAttribution}
         platformStorage={platformStorage}
         accountQueries={accountQueries}
         onAuthStateChange={onAuthStateChange as OxyRuntimeProviderProps['onAuthStateChange']}
       >
-        <AccountProfileObserver />
         <SupervisionStateObserver />
         {productAnalytics ? <ProductAnalyticsObserver analytics={productAnalytics} /> : null}
-        {language ? <LanguageBridge {...language} /> : null}
-        <BloomLocaleBridge>
-          <OxySupportContext.Provider value={support}>
-            <SurfaceProvider>
-              {requireAuth === 'off' ? (
-                children
-              ) : (
-                <RequireOxyAuth prompt={requireAuth}>{children}</RequireOxyAuth>
-              )}
-            </SurfaceProvider>
-          </OxySupportContext.Provider>
-          <ToastOutlet />
-        </BloomLocaleBridge>
+        <AccountLanguageBoundary language={language}>
+          <BloomLocaleBridge>
+            <OxySupportContext.Provider value={support}>
+              <SurfaceProvider>
+                {requireAuth === 'off' ? (
+                  children
+                ) : (
+                  <RequireOxyAuth prompt={requireAuth}>{children}</RequireOxyAuth>
+                )}
+              </SurfaceProvider>
+            </OxySupportContext.Provider>
+            <ToastOutlet />
+          </BloomLocaleBridge>
+        </AccountLanguageBoundary>
       </OxyRuntimeProvider>
     </QueryClientProvider>
   );

package/src/ui/components/__tests__/AccountLanguageBoundary.test.tsx

@@ -0,0 +1,87 @@
+import React from 'react';
+import { render, waitFor } from '@testing-library/react';
+import { AccountLanguageBoundary } from '../AccountLanguageBoundary';
+
+let mockCurrentLanguage = 'en-US';
+let mockCanUsePrivateApi = true;
+const mockUser = { id: 'account', publicKey: '', username: 'ada', name: {} };
+let mockQuery: {
+  data?: typeof mockUser & { languages?: string[] };
+  dataUpdatedAt: number;
+  isError: boolean;
+  fetchStatus?: 'fetching' | 'paused' | 'idle';
+};
+jest.mock('../../context/oxyRuntimeContext', () => ({
+  useOxy: () => ({
+    canUsePrivateApi: mockCanUsePrivateApi,
+    user: mockUser,
+    currentLanguage: mockCurrentLanguage,
+    isLanguageReady: true,
+    isAuthResolved: true,
+  }),
+}));
+jest.mock('../../hooks/queries/useAccountQueries', () => ({ useCurrentUser: () => mockQuery }));
+
+it('waits for the owner preference query and its runtime projection before painting the account app', async () => {
+  mockQuery = { data: mockUser, dataUpdatedAt: 0, isError: false };
+  const onChange = jest.fn();
+  const config = { supportedLocales: ['en-US', 'es-ES'], fallbackLocale: 'en-US', onChange };
+  const screen = render(
+    <AccountLanguageBoundary language={config}>
+      <span>App</span>
+    </AccountLanguageBoundary>,
+  );
+  expect(screen.queryByText('App')).toBeNull();
+  mockQuery = { data: { ...mockUser, languages: ['es-ES'] }, dataUpdatedAt: 123, isError: false };
+  screen.rerender(
+    <AccountLanguageBoundary language={config}>
+      <span>App</span>
+    </AccountLanguageBoundary>,
+  );
+  expect(screen.queryByText('App')).toBeNull();
+  expect(onChange).not.toHaveBeenCalled();
+  mockCurrentLanguage = 'es-ES';
+  screen.rerender(
+    <AccountLanguageBoundary language={config}>
+      <span>App</span>
+    </AccountLanguageBoundary>,
+  );
+  await waitFor(() => expect(screen.getByText('App')).toBeTruthy());
+  expect(onChange.mock.calls).toEqual([['es-ES']]);
+});
+
+it.each(['paused', 'disabled', 'error'] as const)(
+  'renders the resolved fallback when the account query is %s, then adopts its preference without remounting',
+  async (unavailable) => {
+    mockCurrentLanguage = 'en-US';
+    mockCanUsePrivateApi = unavailable !== 'disabled';
+    mockQuery = {
+      data: mockUser,
+      dataUpdatedAt: 0,
+      isError: unavailable === 'error',
+      fetchStatus: unavailable === 'paused' ? 'paused' : 'idle',
+    };
+    const onChange = jest.fn();
+    const config = { supportedLocales: ['en-US', 'es-ES'], fallbackLocale: 'en-US', onChange };
+    const view = () => (
+      <AccountLanguageBoundary language={config}>
+        <input aria-label="Draft" defaultValue="Kept" />
+      </AccountLanguageBoundary>
+    );
+    const screen = render(view());
+    await waitFor(() => expect(screen.getByLabelText('Draft')).toBeTruthy());
+    const draft = screen.getByLabelText('Draft');
+    expect(onChange.mock.calls).toEqual([['en-US']]);
+    mockCanUsePrivateApi = true;
+    mockQuery = {
+      data: { ...mockUser, languages: ['es-ES'] },
+      dataUpdatedAt: 123,
+      isError: false,
+      fetchStatus: 'idle',
+    };
+    mockCurrentLanguage = 'es-ES';
+    screen.rerender(view());
+    await waitFor(() => expect(onChange.mock.calls).toEqual([['en-US'], ['es-ES']]));
+    expect(screen.getByLabelText('Draft')).toBe(draft);
+  },
+);

package/src/ui/components/__tests__/LanguageBridge.test.tsx

@@ -1,91 +1,111 @@
 import React from 'react';
-import { render } from '@testing-library/react';
+import { act, render, waitFor } from '@testing-library/react';
 import { LanguageBridge } from '../LanguageBridge';
 
-/**
- * `OxyProvider`'s language config prop, realized: the one place Oxy's
- * resolved language reaches a host app's own i18n library. `useOxy` is mocked here —
- * it is the SDK's own well-tested context — so these tests exercise exactly
- * what this component adds: coercion to the caller's catalog, and calling
- * back only when the RESOLVED locale actually changes.
- */
-
 let mockCurrentLanguage = 'en-US';
+let mockLanguageReady = true;
+let mockAuthResolved = true;
 jest.mock('../../context/oxyRuntimeContext', () => ({
-  useOxy: () => ({ currentLanguage: mockCurrentLanguage }),
+  useOxy: () => ({
+    currentLanguage: mockCurrentLanguage,
+    isLanguageReady: mockLanguageReady,
+    isAuthResolved: mockAuthResolved,
+  }),
 }));
-
 const HOST_CATALOG = ['en-US', 'es-ES', 'fr-FR'] as const;
-
 beforeEach(() => {
   mockCurrentLanguage = 'en-US';
+  mockLanguageReady = true;
+  mockAuthResolved = true;
 });
 
-it('resolves and reports the account language on mount', () => {
-  mockCurrentLanguage = 'es-ES';
+it.each([
+  ['es-ES', 'es-ES'],
+  ['es-MX', 'es-ES'],
+  ['ja-JP', 'en-US'],
+])('resolves %s to the host catalog %s', async (locale, expected) => {
+  mockCurrentLanguage = locale;
   const onChange = jest.fn();
   render(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
+    <LanguageBridge config={{ supportedLocales: HOST_CATALOG, fallbackLocale: 'en-US', onChange }}>
+      <span>App</span>
+    </LanguageBridge>,
   );
-
-  expect(onChange).toHaveBeenCalledWith('es-ES');
+  await waitFor(() => expect(onChange).toHaveBeenCalledWith(expected));
 });
 
-it('coerces a locale the host never shipped a catalog for, by base language', () => {
-  mockCurrentLanguage = 'es-MX';
-  const onChange = jest.fn();
-  render(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
+it('does not paint any app text before saved preferences, account restoration and catalog loading finish', async () => {
+  mockLanguageReady = false;
+  mockAuthResolved = false;
+  let finishCatalog: (() => void) | undefined;
+  const onChange = jest.fn(
+    () =>
+      new Promise<void>((resolve) => {
+        finishCatalog = resolve;
+      }),
   );
-
-  expect(onChange).toHaveBeenCalledWith('es-ES');
-});
-
-it('falls back to the caller default when nothing matches, even by base', () => {
-  mockCurrentLanguage = 'ja-JP';
-  const onChange = jest.fn();
-  render(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
-  );
-
-  expect(onChange).toHaveBeenCalledWith('en-US');
+  const config = { supportedLocales: HOST_CATALOG, fallbackLocale: 'en-US', onChange };
+  const children = <span>Translated app</span>;
+  const screen = render(<LanguageBridge config={config}>{children}</LanguageBridge>);
+  expect(screen.queryByText('Translated app')).toBeNull();
+  expect(onChange).not.toHaveBeenCalled();
+  mockLanguageReady = true;
+  mockCurrentLanguage = 'es-ES';
+  screen.rerender(<LanguageBridge config={config}>{children}</LanguageBridge>);
+  expect(onChange).not.toHaveBeenCalled();
+  mockAuthResolved = true;
+  screen.rerender(<LanguageBridge config={config}>{children}</LanguageBridge>);
+  await waitFor(() => expect(onChange).toHaveBeenCalledWith('es-ES'));
+  expect(screen.queryByText('Translated app')).toBeNull();
+  await act(async () => finishCatalog?.());
+  expect(screen.getByText('Translated app')).toBeTruthy();
 });
 
-it('calls back again only when the RESOLVED locale changes', () => {
+it('keeps route state mounted across a language change and ignores callback identity changes', async () => {
+  let mounts = 0;
+  function Page() {
+    React.useEffect(() => {
+      mounts += 1;
+    }, []);
+    return <span>App</span>;
+  }
   const onChange = jest.fn();
-  const { rerender } = render(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
+  const config = { supportedLocales: HOST_CATALOG, fallbackLocale: 'en-US', onChange };
+  const screen = render(
+    <LanguageBridge config={config}>
+      <Page />
+    </LanguageBridge>,
   );
-  expect(onChange).toHaveBeenCalledTimes(1);
-
-  // Same resolved locale, brand-new callback identity (the common case for an
-  // inline arrow function) — must not re-fire.
-  rerender(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={() => {}} />,
+  await waitFor(() => expect(mounts).toBe(1));
+  screen.rerender(
+    <LanguageBridge config={{ ...config, onChange: jest.fn() }}>
+      <Page />
+    </LanguageBridge>,
   );
   expect(onChange).toHaveBeenCalledTimes(1);
-
   mockCurrentLanguage = 'fr-FR';
-  rerender(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
+  screen.rerender(
+    <LanguageBridge config={config}>
+      <Page />
+    </LanguageBridge>,
   );
-  expect(onChange).toHaveBeenCalledTimes(2);
-  expect(onChange).toHaveBeenLastCalledWith('fr-FR');
+  await waitFor(() => expect(onChange).toHaveBeenLastCalledWith('fr-FR'));
+  expect(mounts).toBe(1);
 });
 
-it('reports a rejected onChange to onError instead of throwing', async () => {
-  const failure = new Error('catalog failed to load');
-  const onChange = jest.fn().mockRejectedValue(failure);
+it('reports a failed catalog and initializes the fallback before showing children', async () => {
+  mockCurrentLanguage = 'es-ES';
+  const failure = new Error('catalog unavailable');
+  const onChange = jest.fn().mockRejectedValueOnce(failure).mockResolvedValueOnce(undefined);
   const onError = jest.fn();
-  render(
+  const screen = render(
     <LanguageBridge
-      supportedLocales={HOST_CATALOG}
-      fallbackLocale="en-US"
-      onChange={onChange}
-      onError={onError}
-    />,
+      config={{ supportedLocales: HOST_CATALOG, fallbackLocale: 'en-US', onChange, onError }}
+    >
+      <span>App</span>
+    </LanguageBridge>,
   );
-
-  await new Promise((resolve) => setTimeout(resolve, 0));
-  expect(onError).toHaveBeenCalledWith(failure, 'en-US');
+  await waitFor(() => expect(screen.getByText('App')).toBeTruthy());
+  expect(onError).toHaveBeenCalledWith(failure, 'es-ES');
+  expect(onChange.mock.calls.map(([locale]) => locale)).toEqual(['es-ES', 'en-US']);
 });

package/src/ui/components/signIn/OxySignUpPanel.tsx

@@ -67,7 +67,13 @@ export const OxySignUpPanel: React.FC<OxySignUpPanelProps> = ({
   host = 'page',
 }) => {
   const { t } = useI18n();
-  const { oxyServices, handleWebSession, accountDialogController } = useOxy();
+  const {
+    oxyServices,
+    handleWebSession,
+    accountDialogController,
+    currentLanguage,
+    campaignAttribution,
+  } = useOxy();
   const snapshot = useAccountDialogSnapshot(accountDialogController);
   const flowOwner = host === 'dialog' ? accountDialogController : null;
   const [saved] = useState(() => readSignInFlow<SavedSignUpFlow>(flowOwner, SIGN_UP_FLOW_KEY));
@@ -139,6 +145,8 @@ export const OxySignUpPanel: React.FC<OxySignUpPanelProps> = ({
         username: username.trim(),
         email,
         emailTicket: ticket,
+        languages: [currentLanguage],
+        ...(campaignAttribution ? { campaignAttribution } : {}),
       });
       await handleWebSession(session);
       writeSignInFlow(flowOwner, SIGN_UP_FLOW_KEY, undefined);

package/src/ui/context/OxyContext.tsx

@@ -62,6 +62,7 @@ import {
 import { createTokenLossRecovery, TOKEN_RECOVERY_BACKOFF_MS } from '../session/tokenLossRecovery';
 import { createCachedBootStore, type CachedBootStore } from '../session/cachedBoot';
 import { bindAuthStoreToRuntime } from '../stores/authStore';
+import { useEntryLink } from '../hooks/useEntryLink';
 import { useLanguageManagement } from '../hooks/useLanguageManagement';
 import { useSessionManagement } from '../hooks/useSessionManagement';
 import { useAuthOperations, clearPersistedAuthSafe } from './hooks/useAuthOperations';
@@ -153,6 +154,8 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   sessionMode = 'account',
   webAuthMode = 'popup',
   backgroundSession = false,
+  legacyLanguageKeys,
+  captureCampaignAttribution = false,
   platformStorage,
   accountQueries,
   onAuthStateChange,
@@ -415,8 +418,10 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       .catch((err) => {
         // Nothing persisted can be restored; the account cache still has to
         // become ready, or RequireOxyAuth would wait forever.
-        accountQueryPersistence.setStorage(createMemoryStorage());
+        const memoryStorage = createMemoryStorage();
+        accountQueryPersistence.setStorage(memoryStorage);
         if (mounted) {
+          setStorage(memoryStorage);
           logger('Failed to initialize storage', err);
           onError?.({
             message: 'Failed to initialize storage',
@@ -430,8 +435,15 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     };
   }, [accountQueryPersistence, logger, onError, platformStorage, runtime, storageReady]);
 
+  const entryLink = useEntryLink({
+    storage,
+    storageKey: `${storageKeyPrefix}_campaign_attribution`,
+    captureCampaign: captureCampaignAttribution,
+    onError: logger,
+  });
   const {
     currentLanguage,
+    isLanguageReady,
     languages: currentLanguages,
     metadata: currentLanguageMetadata,
     languageName: currentLanguageName,
@@ -441,6 +453,9 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   } = useLanguageManagement({
     storage,
     languageKey: storageKeys.language,
+    entryUrl: entryLink.url,
+    entryLinkReady: entryLink.ready,
+    legacyLanguageKeys,
     user,
     onError,
     logger,
@@ -1751,6 +1766,8 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       webAuthMode,
       error,
       currentLanguage,
+      isLanguageReady: isLanguageReady && entryLink.campaignReady,
+      campaignAttribution: entryLink.campaignAttribution,
       currentLanguages,
       currentLanguageMetadata,
       currentLanguageName,
@@ -1808,6 +1825,9 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       webAuthMode,
       error,
       currentLanguage,
+      isLanguageReady,
+      entryLink.campaignReady,
+      entryLink.campaignAttribution,
       currentLanguages,
       currentLanguageMetadata,
       currentLanguageName,

package/src/ui/context/oxyContextTypes.ts

@@ -1,3 +1,4 @@
+import type { CampaignAttribution } from '@oxy.so/contracts';
 import type {
   StartNativeOAuthSignInOptions,
   NativeOAuthSignInResult,
@@ -85,6 +86,8 @@ export interface OxyContextState {
   error: string | null;
   /** Active UI locale (`language-REGION`): the account's primary locale when signed in, else the guest/device locale. */
   currentLanguage: string;
+  isLanguageReady: boolean;
+  campaignAttribution?: CampaignAttribution;
   /** Ordered account locales (primary first) when signed in, or the single guest override when signed out. */
   currentLanguages: string[];
   currentLanguageMetadata: ReturnType<typeof useLanguageManagement>['metadata'];
@@ -180,6 +183,8 @@ export interface OxyContextState {
 }
 
 export interface OxyRuntimeProviderProps {
+  legacyLanguageKeys?: readonly string[];
+  captureCampaignAttribution?: boolean;
   children: ReactNode;
   oxyServices?: OxyServices;
   baseURL?: string;