npm - create-brainerce-store - Versions diffs - 1.52.4 → 1.53.0 - Mend

create-brainerce-store 1.52.4 → 1.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/LICENSE +21 -0
package/dist/index.js +4 -2
package/messages/en.json +2 -0
package/messages/he.json +2 -0
package/package.json +1 -1
package/templates/nextjs/base/next.config.ts +86 -76
package/templates/nextjs/base/src/app/layout.tsx.ejs +227 -223
package/templates/nextjs/base/src/components/checkout/checkout-form.tsx +118 -4
package/templates/nextjs/base/src/core/providers/store-provider.tsx.ejs +10 -1
package/templates/nextjs/designs/atelier/app-overlay/layout.tsx.ejs +255 -251
package/templates/nextjs/designs/atelier/ui/shared/icons.tsx +269 -269

package/templates/nextjs/base/src/app/layout.tsx.ejs CHANGED Viewed

@@ -1,223 +1,227 @@
-<% if (i18nEnabled) { %>
-import type { Metadata } from 'next';
-<%- fontImport %>
-import { StoreProvider } from '@/core/providers/store-provider';
-import { AnnouncementBar } from '@/ui/layout/announcement-bar';
-import { SiteHeader } from '@/ui/layout/site-header';
-import { SiteFooter } from '@/ui/layout/site-footer';
-import { BrainerceBotWidget } from '@/components/brainerce-bot';
-import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
-import { getDirection, supportedLocales } from '@/i18n';
-import { getNonce } from '@/core/lib/nonce';
-import '../globals.css';
-<%- fontVariable %>
-const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com';
-export const metadata: Metadata = {
-  metadataBase: new URL(baseUrl),
-  title: {
-    default: <%- storeNameJs %>,
-    template: <%- titleTemplateJs %>,
-  },
-  description: <%- storeNameJs %>,
-  alternates: {
-    canonical: '/',
-  },
-  openGraph: {
-    siteName: <%- storeNameJs %>,
-    type: 'website',
-  },
-  robots: {
-    index: true,
-    follow: true,
-  },
-};
-const organizationJsonLd = {
-  '@context': 'https://schema.org',
-  '@type': 'Organization',
-  name: <%- storeNameJs %>,
-  url: baseUrl,
-};
-export function generateStaticParams() {
-  return supportedLocales.map((locale) => ({ locale }));
-}
-export default async function RootLayout({
-  children,
-  params,
-}: {
-  children: React.ReactNode;
-  params: Promise<{ locale: string }>;
-}) {
-  const { locale } = await params;
-  const dir = getDirection(locale);
-  const nonce = await getNonce();
-  // Merchant-driven layout chrome — fetched server-side. Each call falls back
-  // to null/[] on 404 so the layout never crashes when the merchant hasn't
-  // seeded a particular content type yet. New stores ship with default rows
-  // seeded by the backend (StoresService.seedDefaultContent).
-  const client = getServerClient(locale);
-  const [announcements, siteHeader, siteFooter, storeInfo] = await Promise.all([
-    client.content.announcement.list(locale).catch(() => []),
-    client.content.header.get('main', locale).catch(() => null),
-    client.content.footer.get('main', locale).catch(() => null),
-    // SSR-fetch store config so PriceDisplay / FreeShippingBar / upsell UI
-    // render with the real currency, feature flags, and i18n config at frame 0
-    // — without this, Googlebot sees USD/defaults baked into the HTML.
-    fetchStoreInfo(locale),
-  ]);
-  return (
-    <html lang={locale} dir={dir}>
-      <head>
-        <script
-          type="application/ld+json"
-          nonce={nonce}
-          suppressHydrationWarning
-          dangerouslySetInnerHTML={{
-            __html: JSON.stringify(organizationJsonLd)
-              .replace(/</g, '\\u003c')
-              .replace(/>/g, '\\u003e')
-              .replace(/&/g, '\\u0026'),
-          }}
-        />
-        {/* Brainerce cookieless traffic analytics — auto-tracks pageviews +
-            SPA route changes. Cookieless (no consent banner needed); the
-            merchant can toggle it per sales channel in the dashboard. */}
-        <script
-          defer
-          src={`${process.env.NEXT_PUBLIC_BRAINERCE_PIXEL_URL || 'https://api.brainerce.com'}/t.js`}
-          data-channel={
-            process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID || '<%= connectionId %>'
-          }
-          nonce={nonce}
-          suppressHydrationWarning
-        />
-      </head>
-      <body className={font.className}>
-        <StoreProvider locale={locale} initialStoreInfo={storeInfo}>
-          <div className="min-h-screen flex flex-col">
-            <AnnouncementBar announcements={announcements} />
-            <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />
-            <main className="flex-1">{children}</main>
-            <SiteFooter footer={siteFooter} storeName={<%- storeNameJs %>} />
-          </div>
-          <BrainerceBotWidget />
-        </StoreProvider>
-      </body>
-    </html>
-  );
-}
-<% } else { %>
-import type { Metadata } from 'next';
-<%- fontImport %>
-import { StoreProvider } from '@/core/providers/store-provider';
-import { AnnouncementBar } from '@/ui/layout/announcement-bar';
-import { SiteHeader } from '@/ui/layout/site-header';
-import { SiteFooter } from '@/ui/layout/site-footer';
-import { BrainerceBotWidget } from '@/components/brainerce-bot';
-import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
-import { getNonce } from '@/core/lib/nonce';
-import './globals.css';
-<%- fontVariable %>
-const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com';
-export const metadata: Metadata = {
-  metadataBase: new URL(baseUrl),
-  title: {
-    default: <%- storeNameJs %>,
-    template: <%- titleTemplateJs %>,
-  },
-  description: <%- storeNameJs %>,
-  alternates: {
-    canonical: '/',
-  },
-  openGraph: {
-    siteName: <%- storeNameJs %>,
-    locale: '<%= ogLocale %>',
-    type: 'website',
-  },
-  robots: {
-    index: true,
-    follow: true,
-  },
-};
-const organizationJsonLd = {
-  '@context': 'https://schema.org',
-  '@type': 'Organization',
-  name: <%- storeNameJs %>,
-  url: baseUrl,
-};
-export default async function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const nonce = await getNonce();
-  // Merchant-driven layout chrome — fetched server-side. Each call falls back
-  // to null/[] on 404 so the layout never crashes when the merchant hasn't
-  // seeded a particular content type yet. New stores ship with default rows
-  // seeded by the backend (StoresService.seedDefaultContent).
-  const client = getServerClient();
-  const [announcements, siteHeader, siteFooter, storeInfo] = await Promise.all([
-    client.content.announcement.list().catch(() => []),
-    client.content.header.get('main').catch(() => null),
-    client.content.footer.get('main').catch(() => null),
-    // SSR-fetch store config so PriceDisplay / FreeShippingBar / upsell UI
-    // render with the real currency, feature flags, and i18n config at frame 0
-    // — without this, Googlebot sees USD/defaults baked into the HTML.
-    fetchStoreInfo(),
-  ]);
-  return (
-    <html lang="<%= language %>" dir="<%= direction %>">
-      <head>
-        <script
-          type="application/ld+json"
-          nonce={nonce}
-          suppressHydrationWarning
-          dangerouslySetInnerHTML={{
-            __html: JSON.stringify(organizationJsonLd)
-              .replace(/</g, '\\u003c')
-              .replace(/>/g, '\\u003e')
-              .replace(/&/g, '\\u0026'),
-          }}
-        />
-        {/* Brainerce cookieless traffic analytics — auto-tracks pageviews +
-            SPA route changes. Cookieless (no consent banner needed); the
-            merchant can toggle it per sales channel in the dashboard. */}
-        <script
-          defer
-          src={`${process.env.NEXT_PUBLIC_BRAINERCE_PIXEL_URL || 'https://api.brainerce.com'}/t.js`}
-          data-channel={
-            process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID || '<%= connectionId %>'
-          }
-          nonce={nonce}
-          suppressHydrationWarning
-        />
-      </head>
-      <body className={font.className}>
-        <StoreProvider initialStoreInfo={storeInfo}>
-          <div className="min-h-screen flex flex-col">
-            <AnnouncementBar announcements={announcements} />
-            <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />
-            <main className="flex-1">{children}</main>
-            <SiteFooter footer={siteFooter} storeName={<%- storeNameJs %>} />
-          </div>
-          <BrainerceBotWidget />
-        </StoreProvider>
-      </body>
-    </html>
-  );
-}
-<% } %>
+<% if (i18nEnabled) { %>
+import type { Metadata } from 'next';
+<%- fontImport %>
+import { StoreProvider } from '@/core/providers/store-provider';
+import { AnnouncementBar } from '@/ui/layout/announcement-bar';
+import { SiteHeader } from '@/ui/layout/site-header';
+import { SiteFooter } from '@/ui/layout/site-footer';
+import { BrainerceBotWidget } from '@/components/brainerce-bot';
+import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
+import { getDirection, getMessages, supportedLocales } from '@/i18n';
+import { getNonce } from '@/core/lib/nonce';
+import '../globals.css';
+<%- fontVariable %>
+const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com';
+export const metadata: Metadata = {
+  metadataBase: new URL(baseUrl),
+  title: {
+    default: <%- storeNameJs %>,
+    template: <%- titleTemplateJs %>,
+  },
+  description: <%- storeNameJs %>,
+  alternates: {
+    canonical: '/',
+  },
+  openGraph: {
+    siteName: <%- storeNameJs %>,
+    type: 'website',
+  },
+  robots: {
+    index: true,
+    follow: true,
+  },
+};
+const organizationJsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'Organization',
+  name: <%- storeNameJs %>,
+  url: baseUrl,
+};
+export function generateStaticParams() {
+  return supportedLocales.map((locale) => ({ locale }));
+}
+export default async function RootLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ locale: string }>;
+}) {
+  const { locale } = await params;
+  const dir = getDirection(locale);
+  const nonce = await getNonce();
+  // Merchant-driven layout chrome — fetched server-side. Each call falls back
+  // to null/[] on 404 so the layout never crashes when the merchant hasn't
+  // seeded a particular content type yet. New stores ship with default rows
+  // seeded by the backend (StoresService.seedDefaultContent).
+  const client = getServerClient(locale);
+  const [announcements, siteHeader, siteFooter, storeInfo, messages] = await Promise.all([
+    client.content.announcement.list(locale).catch(() => []),
+    client.content.header.get('main', locale).catch(() => null),
+    client.content.footer.get('main', locale).catch(() => null),
+    // SSR-fetch store config so PriceDisplay / FreeShippingBar / upsell UI
+    // render with the real currency, feature flags, and i18n config at frame 0
+    // — without this, Googlebot sees USD/defaults baked into the HTML.
+    fetchStoreInfo(locale),
+    // SSR-fetch UI message strings so translated text renders at frame 0 —
+    // without this, every page (and every locale switch) shows raw
+    // "namespace.key" strings until the client-only fetch resolves.
+    getMessages(locale),
+  ]);
+  return (
+    <html lang={locale} dir={dir}>
+      <head>
+        <script
+          type="application/ld+json"
+          nonce={nonce}
+          suppressHydrationWarning
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify(organizationJsonLd)
+              .replace(/</g, '\\u003c')
+              .replace(/>/g, '\\u003e')
+              .replace(/&/g, '\\u0026'),
+          }}
+        />
+        {/* Brainerce cookieless traffic analytics — auto-tracks pageviews +
+            SPA route changes. Cookieless (no consent banner needed); the
+            merchant can toggle it per sales channel in the dashboard. */}
+        <script
+          defer
+          src={`${process.env.NEXT_PUBLIC_BRAINERCE_PIXEL_URL || 'https://api.brainerce.com'}/t.js`}
+          data-channel={
+            process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID || '<%= connectionId %>'
+          }
+          nonce={nonce}
+          suppressHydrationWarning
+        />
+      </head>
+      <body className={font.className}>
+        <StoreProvider locale={locale} initialStoreInfo={storeInfo} initialMessages={messages}>
+          <div className="min-h-screen flex flex-col">
+            <AnnouncementBar announcements={announcements} />
+            <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />
+            <main className="flex-1">{children}</main>
+            <SiteFooter footer={siteFooter} storeName={<%- storeNameJs %>} />
+          </div>
+          <BrainerceBotWidget />
+        </StoreProvider>
+      </body>
+    </html>
+  );
+}
+<% } else { %>
+import type { Metadata } from 'next';
+<%- fontImport %>
+import { StoreProvider } from '@/core/providers/store-provider';
+import { AnnouncementBar } from '@/ui/layout/announcement-bar';
+import { SiteHeader } from '@/ui/layout/site-header';
+import { SiteFooter } from '@/ui/layout/site-footer';
+import { BrainerceBotWidget } from '@/components/brainerce-bot';
+import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
+import { getNonce } from '@/core/lib/nonce';
+import './globals.css';
+<%- fontVariable %>
+const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com';
+export const metadata: Metadata = {
+  metadataBase: new URL(baseUrl),
+  title: {
+    default: <%- storeNameJs %>,
+    template: <%- titleTemplateJs %>,
+  },
+  description: <%- storeNameJs %>,
+  alternates: {
+    canonical: '/',
+  },
+  openGraph: {
+    siteName: <%- storeNameJs %>,
+    locale: '<%= ogLocale %>',
+    type: 'website',
+  },
+  robots: {
+    index: true,
+    follow: true,
+  },
+};
+const organizationJsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'Organization',
+  name: <%- storeNameJs %>,
+  url: baseUrl,
+};
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const nonce = await getNonce();
+  // Merchant-driven layout chrome — fetched server-side. Each call falls back
+  // to null/[] on 404 so the layout never crashes when the merchant hasn't
+  // seeded a particular content type yet. New stores ship with default rows
+  // seeded by the backend (StoresService.seedDefaultContent).
+  const client = getServerClient();
+  const [announcements, siteHeader, siteFooter, storeInfo] = await Promise.all([
+    client.content.announcement.list().catch(() => []),
+    client.content.header.get('main').catch(() => null),
+    client.content.footer.get('main').catch(() => null),
+    // SSR-fetch store config so PriceDisplay / FreeShippingBar / upsell UI
+    // render with the real currency, feature flags, and i18n config at frame 0
+    // — without this, Googlebot sees USD/defaults baked into the HTML.
+    fetchStoreInfo(),
+  ]);
+  return (
+    <html lang="<%= language %>" dir="<%= direction %>">
+      <head>
+        <script
+          type="application/ld+json"
+          nonce={nonce}
+          suppressHydrationWarning
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify(organizationJsonLd)
+              .replace(/</g, '\\u003c')
+              .replace(/>/g, '\\u003e')
+              .replace(/&/g, '\\u0026'),
+          }}
+        />
+        {/* Brainerce cookieless traffic analytics — auto-tracks pageviews +
+            SPA route changes. Cookieless (no consent banner needed); the
+            merchant can toggle it per sales channel in the dashboard. */}
+        <script
+          defer
+          src={`${process.env.NEXT_PUBLIC_BRAINERCE_PIXEL_URL || 'https://api.brainerce.com'}/t.js`}
+          data-channel={
+            process.env.NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID || '<%= connectionId %>'
+          }
+          nonce={nonce}
+          suppressHydrationWarning
+        />
+      </head>
+      <body className={font.className}>
+        <StoreProvider initialStoreInfo={storeInfo}>
+          <div className="min-h-screen flex flex-col">
+            <AnnouncementBar announcements={announcements} />
+            <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />
+            <main className="flex-1">{children}</main>
+            <SiteFooter footer={siteFooter} storeName={<%- storeNameJs %>} />
+          </div>
+          <BrainerceBotWidget />
+        </StoreProvider>
+      </body>
+    </html>
+  );
+}
+<% } %>

package/templates/nextjs/base/src/components/checkout/checkout-form.tsx CHANGED Viewed

@@ -1,10 +1,17 @@
 'use client';
 import { useState, useEffect, useRef } from 'react';
-import type { SetShippingAddressDto, ShippingDestinations } from 'brainerce';
+import type { SetShippingAddressDto, ShippingDestinations, AddressSuggestion } from 'brainerce';
 import { useTranslations } from '@/core/lib/translations';
 import { cn } from '@/core/lib/utils';
 import { isValidEmail } from '@/core/lib/validation';
+import { getClient } from '@/core/lib/brainerce';
+// Debounce address-suggestion calls rather than firing on every keystroke —
+// both to avoid a jumpy dropdown and to keep autocomplete-session call volume
+// reasonable (see `getAddressSuggestions` doc in the SDK).
+const ADDRESS_SEARCH_DEBOUNCE_MS = 300;
+const ADDRESS_SEARCH_MIN_CHARS = 3;
 interface CheckoutConsent {
   acceptsMarketing: boolean;
@@ -51,6 +58,84 @@ export function CheckoutForm({
   const tc = useTranslations('common');
   const hasAppliedPrefill = useRef(!!initialValues);
+  // Address-autocomplete state — groups one address-entry attempt for
+  // session-token billing (see `getAddressSuggestions` in the SDK). A fresh
+  // token is minted whenever a suggestion is picked, ending that session.
+  const [addressSuggestions, setAddressSuggestions] = useState<AddressSuggestion[]>([]);
+  const [showAddressSuggestions, setShowAddressSuggestions] = useState(false);
+  const [isSearchingAddress, setIsSearchingAddress] = useState(false);
+  const [outsideDeliveryZone, setOutsideDeliveryZone] = useState(false);
+  const addressSessionToken = useRef(
+    typeof crypto !== 'undefined' ? crypto.randomUUID() : `${Date.now()}-${Math.random()}`
+  );
+  const addressSearchTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    return () => {
+      if (addressSearchTimer.current) clearTimeout(addressSearchTimer.current);
+    };
+  }, []);
+  function handleLine1Change(value: string) {
+    updateField('line1', value);
+    setOutsideDeliveryZone(false);
+    if (addressSearchTimer.current) clearTimeout(addressSearchTimer.current);
+    const query = value.trim();
+    if (query.length < ADDRESS_SEARCH_MIN_CHARS) {
+      setAddressSuggestions([]);
+      setShowAddressSuggestions(false);
+      return;
+    }
+    addressSearchTimer.current = setTimeout(async () => {
+      setIsSearchingAddress(true);
+      try {
+        const results = await getClient().getAddressSuggestions(
+          query,
+          addressSessionToken.current
+        );
+        setAddressSuggestions(results);
+        setShowAddressSuggestions(results.length > 0);
+      } catch {
+        // Autocomplete is a soft enhancement — a failed lookup just means no
+        // suggestions this keystroke; the shopper can keep typing manually.
+        setAddressSuggestions([]);
+        setShowAddressSuggestions(false);
+      } finally {
+        setIsSearchingAddress(false);
+      }
+    }, ADDRESS_SEARCH_DEBOUNCE_MS);
+  }
+  async function handleSelectAddressSuggestion(suggestion: AddressSuggestion) {
+    setShowAddressSuggestions(false);
+    try {
+      const { address, inZone } = await getClient().getAddressDetails(
+        suggestion.placeId,
+        addressSessionToken.current
+      );
+      setFormData((prev) => ({
+        ...prev,
+        line1: address.line1 || prev.line1,
+        city: address.city || prev.city,
+        region: address.region || prev.region,
+        postalCode: address.postalCode || prev.postalCode,
+        country: address.country || prev.country,
+      }));
+      setOutsideDeliveryZone(!inZone);
+    } catch {
+      // Resolution failed — keep whatever the shopper had typed/selected as
+      // the visible text; they can still fill in the rest manually.
+    } finally {
+      // New session for the next address-entry attempt.
+      addressSessionToken.current =
+        typeof crypto !== 'undefined' ? crypto.randomUUID() : `${Date.now()}-${Math.random()}`;
+      setAddressSuggestions([]);
+    }
+  }
   // Sync prefill data when it arrives async (e.g. from getCheckoutPrefillData)
   useEffect(() => {
     if (!initialValues || hasAppliedPrefill.current) return;
@@ -261,20 +346,49 @@ export function CheckoutForm({
             </div>
           </div>
-          {/* Address line 1 */}
-          <div>
+          {/* Address line 1 — autocomplete typeahead */}
+          <div className="relative">
             <label htmlFor="line1" className="text-foreground mb-1 block text-sm font-medium">
               {t('address')} <span className="text-destructive">*</span>
             </label>
             <input
               id="line1"
               type="text"
+              autoComplete="off"
               value={formData.line1}
-              onChange={(e) => updateField('line1', e.target.value)}
+              onChange={(e) => handleLine1Change(e.target.value)}
+              onFocus={() => setShowAddressSuggestions(addressSuggestions.length > 0)}
+              onBlur={() => setTimeout(() => setShowAddressSuggestions(false), 150)}
               className={cn(inputClass, errors.line1 ? 'border-destructive' : 'border-border')}
               placeholder={t('streetAddress')}
             />
             {errors.line1 && <p className="text-destructive mt-1 text-xs">{errors.line1}</p>}
+            {showAddressSuggestions && addressSuggestions.length > 0 && (
+              <ul className="bg-background border-border absolute z-10 mt-1 max-h-60 w-full overflow-y-auto rounded border shadow-lg">
+                {addressSuggestions.map((suggestion) => (
+                  <li key={suggestion.placeId}>
+                    <button
+                      type="button"
+                      // onMouseDown fires before the input's onBlur, so the
+                      // click registers before the dropdown closes.
+                      onMouseDown={() => handleSelectAddressSuggestion(suggestion)}
+                      className="hover:bg-muted w-full px-3 py-2 text-start text-sm"
+                    >
+                      {suggestion.description}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            )}
+            {isSearchingAddress && (
+              <p className="text-muted-foreground mt-1 text-xs">{t('searchingAddress')}</p>
+            )}
+            {outsideDeliveryZone && (
+              <p className="mt-2 rounded border border-amber-300 bg-amber-50 px-3 py-2 text-xs text-amber-800 dark:border-amber-800 dark:bg-amber-950 dark:text-amber-200">
+                {t('outsideDeliveryZone')}
+              </p>
+            )}
           </div>
           {/* Address line 2 */}

package/templates/nextjs/base/src/core/providers/store-provider.tsx.ejs CHANGED Viewed

@@ -74,10 +74,12 @@ export function StoreProvider({
   children,
   locale,
   initialStoreInfo = null,
+  initialMessages,
 }: {
   children: React.ReactNode;
   locale?: string;
   initialStoreInfo?: PublicStoreInfo | null;
+  initialMessages?: Record<string, Record<string, string>>;
 }) {
 <% } else { %>
 export function StoreProvider({
@@ -99,7 +101,14 @@ export function StoreProvider({
   const [cart, setCart] = useState<Cart | null>(null);
   const [cartLoading, setCartLoading] = useState(true);
 <% if (i18nEnabled) { %>
-  const [messages, setMessages] = useState<Record<string, Record<string, string>>>({});
+  // Seed from server-rendered messages (see RootLayout) so translated text
+  // renders at frame 0 instead of a window of raw "namespace.key" strings
+  // before the client-only fetch in the effect below resolves — this also
+  // closes the same gap on every locale switch, since RootLayout re-runs
+  // server-side per locale and StoreProvider remounts with fresh initial data.
+  const [messages, setMessages] = useState<Record<string, Record<string, string>>>(
+    initialMessages ?? {}
+  );
 <% } %>
   // Check auth status via httpOnly cookie (server-side validation)