@weaverse/next 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { Weaverse } from '@weaverse/react';
 export { isBrowser, isIframe, useChildInstances, useItemInstance, useParentInstance, useWeaverse } from '@weaverse/react';
 export { InspectorGroup, PageType, SchemaType, createSchema } from '@weaverse/schema';
-import { g as WeaverseNextClientConfig, f as WeaverseNextClient, h as WeaverseNextCommerceContext, v as WeaverseNextRequestContext, s as WeaverseNextLoaderData, w as WeaverseNextRequestInfo, j as WeaverseNextComponentData, G as WeaverseNextThemeSettingsStore, y as WeaverseNextRuntimeInternal, x as WeaverseNextRuntimeConfig } from './seo-kwaliD-K.mjs';
-export { W as WeaverseArticle, a as WeaverseBlog, b as WeaverseCollection, c as WeaverseMetaObject, i as WeaverseNextComponent, k as WeaverseNextComponentLoaderArgs, l as WeaverseNextComponentProps, n as WeaverseNextCustomPageEntry, o as WeaverseNextFetchCustomPagesOptions, q as WeaverseNextI18n, r as WeaverseNextLoadPageInput, t as WeaverseNextPageData, z as WeaverseNextSeoMetadata, D as WeaverseNextStorefront, H as WeaverseProduct, I as formatWeaverseNextSeoMetadata, J as getWeaverseNextSeoMetadata } from './seo-kwaliD-K.mjs';
+import { h as WeaverseNextClientConfig, g as WeaverseNextClient, i as WeaverseNextCommerceContext, x as WeaverseNextRequestContext, t as WeaverseNextLoaderData, a as TranslationStore, y as WeaverseNextRequestInfo, k as WeaverseNextComponentData, I as WeaverseNextThemeSettingsStore, A as WeaverseNextRuntimeInternal, M as WeaverseNextTranslationMap, z as WeaverseNextRuntimeConfig, J as WeaverseNextTranslationChanges, v as WeaverseNextPageData } from './seo-CpN6tC36.mjs';
+export { T as ThemeTextStore, W as WeaverseArticle, b as WeaverseBlog, c as WeaverseCollection, d as WeaverseMetaObject, j as WeaverseNextComponent, l as WeaverseNextComponentLoaderArgs, m as WeaverseNextComponentProps, o as WeaverseNextCustomPageEntry, p as WeaverseNextFetchCustomPagesOptions, r as WeaverseNextI18n, s as WeaverseNextLoadPageInput, u as WeaverseNextPageAssignment, B as WeaverseNextSeoMetadata, F as WeaverseNextStorefront, K as WeaverseNextTranslationEntry, L as WeaverseNextTranslationItemEntry, N as WeaverseNextTranslationMapEntry, O as WeaverseProduct, P as formatWeaverseNextSeoMetadata, Q as getWeaverseNextSeoMetadata } from './seo-CpN6tC36.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
@@ -61,15 +61,157 @@ interface RunComponentLoadersArgs {
  */
 declare function runWeaverseComponentLoaders(args: RunComponentLoadersArgs): Promise<WeaverseNextLoaderData | null>;
 
+/**
+ * Traverse a nested object by dot-path.
+ *
+ * @example
+ * getNestedKey({ cart: { title: 'Cart' } }, 'cart.title') // => 'Cart'
+ * getNestedKey({}, 'cart.title', 'fallback')              // => 'fallback'
+ */
+declare function getNestedKey(obj: Record<string, unknown>, path: string, fallback?: string): string | undefined;
+/**
+ * Replace `{{variable}}` patterns in a string with provided values.
+ *
+ * @example
+ * interpolate('Hello {{name}}!', { name: 'World' }) // => 'Hello World!'
+ * interpolate('-{{percentage}}% Off', { percentage: 15 }) // => '-15% Off'
+ */
+declare function interpolate(template: string, variables?: Record<string, string | number>): string;
+/**
+ * Signature for a translation function.
+ */
+type TranslateFunction = (key: string, variables?: Record<string, string | number>) => string;
+interface TranslationValue {
+    /** Active-locale translated keys loaded from the storefront API. */
+    merchantOverrides: Record<string, unknown> | null;
+    /**
+     * Translate a key with optional variable interpolation.
+     *
+     * Priority chain (highest wins):
+     * 1. External `t`        (passed into `WeaverseNextRootProvider` / `TranslationProvider`)
+     * 2. Design overrides   (live Builder edits from `TranslationStore`)
+     * 3. `merchantOverrides` (DB/API overrides for the current locale)
+     * 4. `staticContent`     (theme default JSON)
+     * 5. The key itself      (fallback)
+     *
+     * @example
+     * t('cart.title')                           // => "Cart"
+     * t('badge.sale', { percentage: 15 })       // => "-15% Off"
+     */
+    t: TranslateFunction;
+    /**
+     * @deprecated Use {@link TranslationValue.translationStore} instead. Kept as a
+     * backward-compatible alias pointing at the same store instance.
+     */
+    themeTextStore: TranslationStore | null;
+    /** Exposed so the runtime/Studio bridge can attach it to `internal`. */
+    translationStore: TranslationStore | null;
+}
+interface TranslationProviderProps {
+    children: ReactNode;
+    merchantOverrides?: Record<string, unknown>;
+    staticContent: Record<string, unknown>;
+    /**
+     * Optional external translation function.
+     * When provided it becomes the **highest-priority** source:
+     * if it returns a non-empty string that differs from the raw key,
+     * that value is used; otherwise the internal resolution chain continues.
+     */
+    t?: TranslateFunction;
+    /**
+     * @deprecated Use {@link TranslationProviderProps.translationStore} instead.
+     * Still accepted for backward compatibility; ignored when `translationStore`
+     * is also provided.
+     */
+    themeTextStore?: TranslationStore | null;
+    /** Optional store for live design-mode text overrides from the builder. */
+    translationStore?: TranslationStore | null;
+}
+/**
+ * Build the `t()` translation function over a fixed set of sources.
+ *
+ * Resolution order, highest priority first:
+ * 1. `externalT`         – host i18n (e.g. Shopify), unless it echoes the key
+ * 2. `designOverrides`   – live design-mode edits, flat dot-path keys
+ * 3. `merchantOverrides` – locale overrides from the API, nested
+ * 4. `staticContent`     – the theme's default locale JSON
+ * 5. the key itself
+ *
+ * Design overrides are looked up per-key (own properties only) rather than
+ * merged into `merchantOverrides`: a flat key like `cart.title` must override
+ * exactly that leaf without wiping sibling keys (`cart.subtitle`), and a
+ * per-key own-property lookup never builds nested objects from
+ * merchant-controlled keys, so it cannot pollute `Object.prototype`.
+ */
+declare function createTranslate(sources: {
+    staticContent: Record<string, unknown>;
+    merchantOverrides?: Record<string, unknown>;
+    designOverrides?: Record<string, string>;
+    externalT?: TranslateFunction;
+}): TranslateFunction;
+/**
+ * Provider that wraps the app to expose the `t()` function.
+ *
+ * - `staticContent`      – the theme's default locale JSON (from themeSchema.i18n)
+ * - `merchantOverrides`  – locale-specific overrides fetched from the API
+ * - `translationStore`   – optional store for live design-mode text overrides
+ *   (the deprecated `themeTextStore` prop is accepted as a fallback)
+ */
+declare function TranslationProvider({ staticContent, merchantOverrides, t: externalT, translationStore, themeTextStore, children, }: TranslationProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the translation `t()` function.
+ *
+ * Must be used inside a component wrapped by `WeaverseNextRootProvider` or
+ * `TranslationProvider`.
+ *
+ * @example
+ * ```tsx
+ * function CartTitle() {
+ *   let { t } = useTranslation()
+ *   return <h2>{t('cart.title')}</h2>
+ * }
+ * ```
+ */
+declare function useTranslation(): TranslationValue;
+/**
+ * @deprecated Use {@link TranslationProvider} instead.
+ */
+declare const ThemeTextProvider: typeof TranslationProvider;
+/**
+ * @deprecated Use {@link useTranslation} instead.
+ */
+declare const useThemeText: typeof useTranslation;
+/**
+ * @deprecated Use {@link TranslationValue} instead.
+ */
+type ThemeTextValue = TranslationValue;
+/**
+ * @deprecated Use {@link TranslationProviderProps} instead.
+ */
+type ThemeTextProviderProps = TranslationProviderProps;
+
 interface WeaverseNextProviderProps {
     children: ReactNode;
     client?: WeaverseNextClient;
     /** App-provided commerce context (storefront/cart/customer). */
     commerce?: WeaverseNextCommerceContext;
+    /**
+     * Active-locale static-text overrides (nested, from `loadThemeSettings()`).
+     * Adopts the root provider's `merchantOverrides` when omitted.
+     */
+    merchantOverrides?: Record<string, unknown>;
     /** Explicit page/route commerce data (replaces section-level `useLoaderData`). */
     pageData?: unknown;
     /** Explicit root/global data (replaces `useRouteLoaderData('root')`). */
     rootData?: unknown;
+    /**
+     * Theme default locale JSON (`loadThemeSettings().staticContent`). Adopts the
+     * root provider's `staticContent` when omitted, then falls back to
+     * `client.themeSchema.i18n.staticContent`.
+     */
+    staticContent?: Record<string, unknown>;
+    /** Optional external translation function (host i18n); highest priority in `t()`. */
+    t?: TranslateFunction;
     /** Theme settings override; falls back to `client.themeSettings`. */
     themeSettings?: Record<string, unknown>;
 }
@@ -144,13 +286,28 @@ interface RevalidateItemRuntimeLike {
 declare function revalidateWeaverseNextItem(runtime: RevalidateItemRuntimeLike, draftItem: WeaverseNextComponentData, endpoint?: string): Promise<void>;
 
 interface WeaverseNextRootContextValue {
+    /** Active-locale static-text overrides shared with route-level providers. */
+    merchantOverrides?: Record<string, unknown>;
+    /** Theme default locale JSON shared with route-level providers. */
+    staticContent: Record<string, unknown>;
     themeSettingsStore: WeaverseNextThemeSettingsStore;
+    /** Single live design-mode static-text override store for the whole session. */
+    translationStore: TranslationStore;
 }
 interface WeaverseNextRootProviderProps {
     children: ReactNode;
     /** Root-loaded theme settings (published-mode fetch, no design-mode context). */
     initialThemeSettings?: Record<string, unknown>;
+    /** Active-locale static-text overrides from `loadThemeSettings().merchantOverrides`. */
+    merchantOverrides?: Record<string, unknown>;
     publicEnv?: Record<string, string | undefined>;
+    /**
+     * Theme default locale JSON (`loadThemeSettings().staticContent`). Falls back
+     * to `themeSchema.i18n.staticContent` when omitted.
+     */
+    staticContent?: Record<string, unknown>;
+    /** Optional external translation function (host i18n); highest priority in `t()`. */
+    t?: TranslateFunction;
     themeSchema?: unknown;
 }
 /**
@@ -187,14 +344,50 @@ declare class WeaverseNextRuntime extends Weaverse {
     isPreviewMode: boolean;
     isRevisionPreview: boolean;
     sectionType?: string;
-    translationMap: Record<string, unknown>;
+    /**
+     * Translation map received from Builder in design mode, keyed by item ID.
+     * `WeaverseNextItem.getSnapShot()` overlays these onto the data handed to
+     * components, so translations render without mutating the base `_store`.
+     */
+    translationMap: WeaverseNextTranslationMap;
     translationLocale: string;
     translationLanguageId: string;
     constructor(config: WeaverseNextRuntimeConfig);
-    extractTranslationSidecar: () => undefined;
-    setTranslationSidecar: (map?: Record<string, unknown>, locale?: string, languageId?: string) => void;
-    updateTranslation: () => undefined;
-    getTranslationChanges: () => undefined;
+    /**
+     * Pull `translationMap` / `translationLocale` / `translationLanguageId` off
+     * the current page data (Builder attaches them in design mode). Unlike
+     * Hydrogen, this also clears the sidecar to defaults when the new page data
+     * carries none, so a reused runtime / project-data swap can't leave a stale
+     * map overlaying the fresh tree.
+     */
+    extractTranslationSidecar: () => void;
+    /**
+     * Replace the translation sidecar (Builder pushes this when translation data
+     * arrives or the active language changes) and refresh every item so their
+     * merged snapshots recompute.
+     */
+    setTranslationSidecar: (map?: WeaverseNextTranslationMap, locale?: string, languageId?: string) => void;
+    /**
+     * Update a single translatable field for one item. Assigns a new per-item
+     * entry object so `WeaverseNextItem.getSnapShot()`'s translation-ref cache
+     * invalidates, then triggers only that item's subscribers.
+     */
+    updateTranslation: (itemId: string, key: string, originalValue: string, translatedValue: string) => void;
+    /**
+     * Collect translation changes for the save flow. Returns `undefined` unless
+     * both the locale and language ID are set and at least one entry exists;
+     * each entry key is namespaced as `data.<field>` to match Builder.
+     */
+    getTranslationChanges: () => WeaverseNextTranslationChanges | undefined;
+    /**
+     * Re-extract the translation sidecar whenever project data is replaced (route
+     * change / non-design reuse), before rebuilding item stores. Takes the
+     * renderable page shape (`rootId` resolved) that `getRenderablePage()` and
+     * the reuse branch pass in.
+     */
+    setProjectData: (data: WeaverseNextPageData & {
+        rootId: string;
+    }) => void;
 }
 declare function createWeaverseNextRuntime(config: WeaverseNextRuntimeConfig): WeaverseNextRuntime;
 declare function bindWeaverseNextStudioRuntime(runtime: WeaverseNextRuntime): boolean;
@@ -321,4 +514,4 @@ interface WeaverseNextStudioProps extends CreateWeaverseNextStudioInternalsOptio
  */
 declare function WeaverseNextStudio(props: WeaverseNextStudioProps): react_jsx_runtime.JSX.Element;
 
-export { type CreateWeaverseNextStudioInternalsOptions, type CreateWeaverseNextThemeSettingsStoreOptions, DEFAULT_REVALIDATE_ENDPOINT, type LoadWeaverseNextStudioScriptOptions, type ResolveWeaverseNextStudioScriptSrcOptions, type RevalidateItemRuntimeLike, type RunComponentLoadersArgs, WeaverseNextClient, WeaverseNextClientConfig, WeaverseNextCommerceContext, WeaverseNextComponentData, WeaverseNextLoaderData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, WeaverseNextRequestContext, WeaverseNextRequestInfo, type WeaverseNextRootContextValue, WeaverseNextRootProvider, type WeaverseNextRootProviderProps, type WeaverseNextRouterLike, WeaverseNextRuntime, WeaverseNextRuntimeConfig, WeaverseNextRuntimeInternal, WeaverseNextStudio, WeaverseNextStudioBridge, type WeaverseNextStudioBridgeProps, WeaverseNextStudioConnect, type WeaverseNextStudioConnectProps, type WeaverseNextStudioInternals, type WeaverseNextStudioProps, WeaverseNextThemeSettingsStore, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextStudioInternals, createWeaverseNextThemeSettingsStore, loadWeaverseNextStudioScript, resolveWeaverseNextStudioScriptSrc, revalidateWeaverseNextItem, runWeaverseComponentLoaders, useThemeSettings, useWeaverseCommerce, useWeaverseNextStudioInternals, useWeaversePageData, useWeaverseRootData };
+export { type CreateWeaverseNextStudioInternalsOptions, type CreateWeaverseNextThemeSettingsStoreOptions, DEFAULT_REVALIDATE_ENDPOINT, type LoadWeaverseNextStudioScriptOptions, type ResolveWeaverseNextStudioScriptSrcOptions, type RevalidateItemRuntimeLike, type RunComponentLoadersArgs, ThemeTextProvider, type ThemeTextProviderProps, type ThemeTextValue, type TranslateFunction, TranslationProvider, type TranslationProviderProps, TranslationStore, type TranslationValue, WeaverseNextClient, WeaverseNextClientConfig, WeaverseNextCommerceContext, WeaverseNextComponentData, WeaverseNextLoaderData, WeaverseNextPageData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, WeaverseNextRequestContext, WeaverseNextRequestInfo, type WeaverseNextRootContextValue, WeaverseNextRootProvider, type WeaverseNextRootProviderProps, type WeaverseNextRouterLike, WeaverseNextRuntime, WeaverseNextRuntimeConfig, WeaverseNextRuntimeInternal, WeaverseNextStudio, WeaverseNextStudioBridge, type WeaverseNextStudioBridgeProps, WeaverseNextStudioConnect, type WeaverseNextStudioConnectProps, type WeaverseNextStudioInternals, type WeaverseNextStudioProps, WeaverseNextThemeSettingsStore, WeaverseNextTranslationChanges, WeaverseNextTranslationMap, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createTranslate, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextStudioInternals, createWeaverseNextThemeSettingsStore, getNestedKey, interpolate, loadWeaverseNextStudioScript, resolveWeaverseNextStudioScriptSrc, revalidateWeaverseNextItem, runWeaverseComponentLoaders, useThemeSettings, useThemeText, useTranslation, useWeaverseCommerce, useWeaverseNextStudioInternals, useWeaversePageData, useWeaverseRootData };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Weaverse } from '@weaverse/react';
 export { isBrowser, isIframe, useChildInstances, useItemInstance, useParentInstance, useWeaverse } from '@weaverse/react';
 export { InspectorGroup, PageType, SchemaType, createSchema } from '@weaverse/schema';
-import { g as WeaverseNextClientConfig, f as WeaverseNextClient, h as WeaverseNextCommerceContext, v as WeaverseNextRequestContext, s as WeaverseNextLoaderData, w as WeaverseNextRequestInfo, j as WeaverseNextComponentData, G as WeaverseNextThemeSettingsStore, y as WeaverseNextRuntimeInternal, x as WeaverseNextRuntimeConfig } from './seo-kwaliD-K.js';
-export { W as WeaverseArticle, a as WeaverseBlog, b as WeaverseCollection, c as WeaverseMetaObject, i as WeaverseNextComponent, k as WeaverseNextComponentLoaderArgs, l as WeaverseNextComponentProps, n as WeaverseNextCustomPageEntry, o as WeaverseNextFetchCustomPagesOptions, q as WeaverseNextI18n, r as WeaverseNextLoadPageInput, t as WeaverseNextPageData, z as WeaverseNextSeoMetadata, D as WeaverseNextStorefront, H as WeaverseProduct, I as formatWeaverseNextSeoMetadata, J as getWeaverseNextSeoMetadata } from './seo-kwaliD-K.js';
+import { h as WeaverseNextClientConfig, g as WeaverseNextClient, i as WeaverseNextCommerceContext, x as WeaverseNextRequestContext, t as WeaverseNextLoaderData, a as TranslationStore, y as WeaverseNextRequestInfo, k as WeaverseNextComponentData, I as WeaverseNextThemeSettingsStore, A as WeaverseNextRuntimeInternal, M as WeaverseNextTranslationMap, z as WeaverseNextRuntimeConfig, J as WeaverseNextTranslationChanges, v as WeaverseNextPageData } from './seo-CpN6tC36.js';
+export { T as ThemeTextStore, W as WeaverseArticle, b as WeaverseBlog, c as WeaverseCollection, d as WeaverseMetaObject, j as WeaverseNextComponent, l as WeaverseNextComponentLoaderArgs, m as WeaverseNextComponentProps, o as WeaverseNextCustomPageEntry, p as WeaverseNextFetchCustomPagesOptions, r as WeaverseNextI18n, s as WeaverseNextLoadPageInput, u as WeaverseNextPageAssignment, B as WeaverseNextSeoMetadata, F as WeaverseNextStorefront, K as WeaverseNextTranslationEntry, L as WeaverseNextTranslationItemEntry, N as WeaverseNextTranslationMapEntry, O as WeaverseProduct, P as formatWeaverseNextSeoMetadata, Q as getWeaverseNextSeoMetadata } from './seo-CpN6tC36.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
@@ -61,15 +61,157 @@ interface RunComponentLoadersArgs {
  */
 declare function runWeaverseComponentLoaders(args: RunComponentLoadersArgs): Promise<WeaverseNextLoaderData | null>;
 
+/**
+ * Traverse a nested object by dot-path.
+ *
+ * @example
+ * getNestedKey({ cart: { title: 'Cart' } }, 'cart.title') // => 'Cart'
+ * getNestedKey({}, 'cart.title', 'fallback')              // => 'fallback'
+ */
+declare function getNestedKey(obj: Record<string, unknown>, path: string, fallback?: string): string | undefined;
+/**
+ * Replace `{{variable}}` patterns in a string with provided values.
+ *
+ * @example
+ * interpolate('Hello {{name}}!', { name: 'World' }) // => 'Hello World!'
+ * interpolate('-{{percentage}}% Off', { percentage: 15 }) // => '-15% Off'
+ */
+declare function interpolate(template: string, variables?: Record<string, string | number>): string;
+/**
+ * Signature for a translation function.
+ */
+type TranslateFunction = (key: string, variables?: Record<string, string | number>) => string;
+interface TranslationValue {
+    /** Active-locale translated keys loaded from the storefront API. */
+    merchantOverrides: Record<string, unknown> | null;
+    /**
+     * Translate a key with optional variable interpolation.
+     *
+     * Priority chain (highest wins):
+     * 1. External `t`        (passed into `WeaverseNextRootProvider` / `TranslationProvider`)
+     * 2. Design overrides   (live Builder edits from `TranslationStore`)
+     * 3. `merchantOverrides` (DB/API overrides for the current locale)
+     * 4. `staticContent`     (theme default JSON)
+     * 5. The key itself      (fallback)
+     *
+     * @example
+     * t('cart.title')                           // => "Cart"
+     * t('badge.sale', { percentage: 15 })       // => "-15% Off"
+     */
+    t: TranslateFunction;
+    /**
+     * @deprecated Use {@link TranslationValue.translationStore} instead. Kept as a
+     * backward-compatible alias pointing at the same store instance.
+     */
+    themeTextStore: TranslationStore | null;
+    /** Exposed so the runtime/Studio bridge can attach it to `internal`. */
+    translationStore: TranslationStore | null;
+}
+interface TranslationProviderProps {
+    children: ReactNode;
+    merchantOverrides?: Record<string, unknown>;
+    staticContent: Record<string, unknown>;
+    /**
+     * Optional external translation function.
+     * When provided it becomes the **highest-priority** source:
+     * if it returns a non-empty string that differs from the raw key,
+     * that value is used; otherwise the internal resolution chain continues.
+     */
+    t?: TranslateFunction;
+    /**
+     * @deprecated Use {@link TranslationProviderProps.translationStore} instead.
+     * Still accepted for backward compatibility; ignored when `translationStore`
+     * is also provided.
+     */
+    themeTextStore?: TranslationStore | null;
+    /** Optional store for live design-mode text overrides from the builder. */
+    translationStore?: TranslationStore | null;
+}
+/**
+ * Build the `t()` translation function over a fixed set of sources.
+ *
+ * Resolution order, highest priority first:
+ * 1. `externalT`         – host i18n (e.g. Shopify), unless it echoes the key
+ * 2. `designOverrides`   – live design-mode edits, flat dot-path keys
+ * 3. `merchantOverrides` – locale overrides from the API, nested
+ * 4. `staticContent`     – the theme's default locale JSON
+ * 5. the key itself
+ *
+ * Design overrides are looked up per-key (own properties only) rather than
+ * merged into `merchantOverrides`: a flat key like `cart.title` must override
+ * exactly that leaf without wiping sibling keys (`cart.subtitle`), and a
+ * per-key own-property lookup never builds nested objects from
+ * merchant-controlled keys, so it cannot pollute `Object.prototype`.
+ */
+declare function createTranslate(sources: {
+    staticContent: Record<string, unknown>;
+    merchantOverrides?: Record<string, unknown>;
+    designOverrides?: Record<string, string>;
+    externalT?: TranslateFunction;
+}): TranslateFunction;
+/**
+ * Provider that wraps the app to expose the `t()` function.
+ *
+ * - `staticContent`      – the theme's default locale JSON (from themeSchema.i18n)
+ * - `merchantOverrides`  – locale-specific overrides fetched from the API
+ * - `translationStore`   – optional store for live design-mode text overrides
+ *   (the deprecated `themeTextStore` prop is accepted as a fallback)
+ */
+declare function TranslationProvider({ staticContent, merchantOverrides, t: externalT, translationStore, themeTextStore, children, }: TranslationProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the translation `t()` function.
+ *
+ * Must be used inside a component wrapped by `WeaverseNextRootProvider` or
+ * `TranslationProvider`.
+ *
+ * @example
+ * ```tsx
+ * function CartTitle() {
+ *   let { t } = useTranslation()
+ *   return <h2>{t('cart.title')}</h2>
+ * }
+ * ```
+ */
+declare function useTranslation(): TranslationValue;
+/**
+ * @deprecated Use {@link TranslationProvider} instead.
+ */
+declare const ThemeTextProvider: typeof TranslationProvider;
+/**
+ * @deprecated Use {@link useTranslation} instead.
+ */
+declare const useThemeText: typeof useTranslation;
+/**
+ * @deprecated Use {@link TranslationValue} instead.
+ */
+type ThemeTextValue = TranslationValue;
+/**
+ * @deprecated Use {@link TranslationProviderProps} instead.
+ */
+type ThemeTextProviderProps = TranslationProviderProps;
+
 interface WeaverseNextProviderProps {
     children: ReactNode;
     client?: WeaverseNextClient;
     /** App-provided commerce context (storefront/cart/customer). */
     commerce?: WeaverseNextCommerceContext;
+    /**
+     * Active-locale static-text overrides (nested, from `loadThemeSettings()`).
+     * Adopts the root provider's `merchantOverrides` when omitted.
+     */
+    merchantOverrides?: Record<string, unknown>;
     /** Explicit page/route commerce data (replaces section-level `useLoaderData`). */
     pageData?: unknown;
     /** Explicit root/global data (replaces `useRouteLoaderData('root')`). */
     rootData?: unknown;
+    /**
+     * Theme default locale JSON (`loadThemeSettings().staticContent`). Adopts the
+     * root provider's `staticContent` when omitted, then falls back to
+     * `client.themeSchema.i18n.staticContent`.
+     */
+    staticContent?: Record<string, unknown>;
+    /** Optional external translation function (host i18n); highest priority in `t()`. */
+    t?: TranslateFunction;
     /** Theme settings override; falls back to `client.themeSettings`. */
     themeSettings?: Record<string, unknown>;
 }
@@ -144,13 +286,28 @@ interface RevalidateItemRuntimeLike {
 declare function revalidateWeaverseNextItem(runtime: RevalidateItemRuntimeLike, draftItem: WeaverseNextComponentData, endpoint?: string): Promise<void>;
 
 interface WeaverseNextRootContextValue {
+    /** Active-locale static-text overrides shared with route-level providers. */
+    merchantOverrides?: Record<string, unknown>;
+    /** Theme default locale JSON shared with route-level providers. */
+    staticContent: Record<string, unknown>;
     themeSettingsStore: WeaverseNextThemeSettingsStore;
+    /** Single live design-mode static-text override store for the whole session. */
+    translationStore: TranslationStore;
 }
 interface WeaverseNextRootProviderProps {
     children: ReactNode;
     /** Root-loaded theme settings (published-mode fetch, no design-mode context). */
     initialThemeSettings?: Record<string, unknown>;
+    /** Active-locale static-text overrides from `loadThemeSettings().merchantOverrides`. */
+    merchantOverrides?: Record<string, unknown>;
     publicEnv?: Record<string, string | undefined>;
+    /**
+     * Theme default locale JSON (`loadThemeSettings().staticContent`). Falls back
+     * to `themeSchema.i18n.staticContent` when omitted.
+     */
+    staticContent?: Record<string, unknown>;
+    /** Optional external translation function (host i18n); highest priority in `t()`. */
+    t?: TranslateFunction;
     themeSchema?: unknown;
 }
 /**
@@ -187,14 +344,50 @@ declare class WeaverseNextRuntime extends Weaverse {
     isPreviewMode: boolean;
     isRevisionPreview: boolean;
     sectionType?: string;
-    translationMap: Record<string, unknown>;
+    /**
+     * Translation map received from Builder in design mode, keyed by item ID.
+     * `WeaverseNextItem.getSnapShot()` overlays these onto the data handed to
+     * components, so translations render without mutating the base `_store`.
+     */
+    translationMap: WeaverseNextTranslationMap;
     translationLocale: string;
     translationLanguageId: string;
     constructor(config: WeaverseNextRuntimeConfig);
-    extractTranslationSidecar: () => undefined;
-    setTranslationSidecar: (map?: Record<string, unknown>, locale?: string, languageId?: string) => void;
-    updateTranslation: () => undefined;
-    getTranslationChanges: () => undefined;
+    /**
+     * Pull `translationMap` / `translationLocale` / `translationLanguageId` off
+     * the current page data (Builder attaches them in design mode). Unlike
+     * Hydrogen, this also clears the sidecar to defaults when the new page data
+     * carries none, so a reused runtime / project-data swap can't leave a stale
+     * map overlaying the fresh tree.
+     */
+    extractTranslationSidecar: () => void;
+    /**
+     * Replace the translation sidecar (Builder pushes this when translation data
+     * arrives or the active language changes) and refresh every item so their
+     * merged snapshots recompute.
+     */
+    setTranslationSidecar: (map?: WeaverseNextTranslationMap, locale?: string, languageId?: string) => void;
+    /**
+     * Update a single translatable field for one item. Assigns a new per-item
+     * entry object so `WeaverseNextItem.getSnapShot()`'s translation-ref cache
+     * invalidates, then triggers only that item's subscribers.
+     */
+    updateTranslation: (itemId: string, key: string, originalValue: string, translatedValue: string) => void;
+    /**
+     * Collect translation changes for the save flow. Returns `undefined` unless
+     * both the locale and language ID are set and at least one entry exists;
+     * each entry key is namespaced as `data.<field>` to match Builder.
+     */
+    getTranslationChanges: () => WeaverseNextTranslationChanges | undefined;
+    /**
+     * Re-extract the translation sidecar whenever project data is replaced (route
+     * change / non-design reuse), before rebuilding item stores. Takes the
+     * renderable page shape (`rootId` resolved) that `getRenderablePage()` and
+     * the reuse branch pass in.
+     */
+    setProjectData: (data: WeaverseNextPageData & {
+        rootId: string;
+    }) => void;
 }
 declare function createWeaverseNextRuntime(config: WeaverseNextRuntimeConfig): WeaverseNextRuntime;
 declare function bindWeaverseNextStudioRuntime(runtime: WeaverseNextRuntime): boolean;
@@ -321,4 +514,4 @@ interface WeaverseNextStudioProps extends CreateWeaverseNextStudioInternalsOptio
  */
 declare function WeaverseNextStudio(props: WeaverseNextStudioProps): react_jsx_runtime.JSX.Element;
 
-export { type CreateWeaverseNextStudioInternalsOptions, type CreateWeaverseNextThemeSettingsStoreOptions, DEFAULT_REVALIDATE_ENDPOINT, type LoadWeaverseNextStudioScriptOptions, type ResolveWeaverseNextStudioScriptSrcOptions, type RevalidateItemRuntimeLike, type RunComponentLoadersArgs, WeaverseNextClient, WeaverseNextClientConfig, WeaverseNextCommerceContext, WeaverseNextComponentData, WeaverseNextLoaderData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, WeaverseNextRequestContext, WeaverseNextRequestInfo, type WeaverseNextRootContextValue, WeaverseNextRootProvider, type WeaverseNextRootProviderProps, type WeaverseNextRouterLike, WeaverseNextRuntime, WeaverseNextRuntimeConfig, WeaverseNextRuntimeInternal, WeaverseNextStudio, WeaverseNextStudioBridge, type WeaverseNextStudioBridgeProps, WeaverseNextStudioConnect, type WeaverseNextStudioConnectProps, type WeaverseNextStudioInternals, type WeaverseNextStudioProps, WeaverseNextThemeSettingsStore, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextStudioInternals, createWeaverseNextThemeSettingsStore, loadWeaverseNextStudioScript, resolveWeaverseNextStudioScriptSrc, revalidateWeaverseNextItem, runWeaverseComponentLoaders, useThemeSettings, useWeaverseCommerce, useWeaverseNextStudioInternals, useWeaversePageData, useWeaverseRootData };
+export { type CreateWeaverseNextStudioInternalsOptions, type CreateWeaverseNextThemeSettingsStoreOptions, DEFAULT_REVALIDATE_ENDPOINT, type LoadWeaverseNextStudioScriptOptions, type ResolveWeaverseNextStudioScriptSrcOptions, type RevalidateItemRuntimeLike, type RunComponentLoadersArgs, ThemeTextProvider, type ThemeTextProviderProps, type ThemeTextValue, type TranslateFunction, TranslationProvider, type TranslationProviderProps, TranslationStore, type TranslationValue, WeaverseNextClient, WeaverseNextClientConfig, WeaverseNextCommerceContext, WeaverseNextComponentData, WeaverseNextLoaderData, WeaverseNextPageData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, WeaverseNextRequestContext, WeaverseNextRequestInfo, type WeaverseNextRootContextValue, WeaverseNextRootProvider, type WeaverseNextRootProviderProps, type WeaverseNextRouterLike, WeaverseNextRuntime, WeaverseNextRuntimeConfig, WeaverseNextRuntimeInternal, WeaverseNextStudio, WeaverseNextStudioBridge, type WeaverseNextStudioBridgeProps, WeaverseNextStudioConnect, type WeaverseNextStudioConnectProps, type WeaverseNextStudioInternals, type WeaverseNextStudioProps, WeaverseNextThemeSettingsStore, WeaverseNextTranslationChanges, WeaverseNextTranslationMap, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createTranslate, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextStudioInternals, createWeaverseNextThemeSettingsStore, getNestedKey, interpolate, loadWeaverseNextStudioScript, resolveWeaverseNextStudioScriptSrc, revalidateWeaverseNextItem, runWeaverseComponentLoaders, useThemeSettings, useThemeText, useTranslation, useWeaverseCommerce, useWeaverseNextStudioInternals, useWeaversePageData, useWeaverseRootData };