@weaverse/next 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/index.d.mts

@@ -1,163 +1,12 @@
-import { WeaverseElement, WeaverseResourcePickerData } from '@weaverse/react';
+import { WeaverseItemStore, Weaverse, ElementData } from '@weaverse/react';
 export { isBrowser, isIframe, useChildInstances, useItemInstance, useParentInstance, useWeaverse } from '@weaverse/react';
-import { PageType, SchemaType } from '@weaverse/schema';
-export { InspectorGroup, PageType, SchemaType, createSchema } from '@weaverse/schema';
-import * as react from 'react';
-import { ReactNode, ComponentType, ForwardRefExoticComponent } from 'react';
+import { SchemaType } from '@weaverse/schema';
+export * from '@weaverse/schema';
+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, J as WeaverseNextThemeSettingsStore, G as WeaverseNextThemeSchema, A as WeaverseNextRuntimeInternal, N as WeaverseNextTranslationMap, v as WeaverseNextPageData, z as WeaverseNextRuntimeConfig, K as WeaverseNextTranslationChanges } from './seo-CgO21rLg.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, L as WeaverseNextTranslationEntry, M as WeaverseNextTranslationItemEntry, O as WeaverseNextTranslationMapEntry, P as WeaverseProduct, Q as formatWeaverseNextSeoMetadata, R as getWeaverseNextSeoMetadata } from './seo-CgO21rLg.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-
-/**
- * Locale/market info passed through to component loaders and the Storefront
- * client. Kept structurally close to Hydrogen's `WeaverseI18n` but without the
- * `@shopify/hydrogen` `I18nBase` dependency so the adapter stays framework
- * neutral.
- */
-interface WeaverseNextI18n {
-    country?: string;
-    label?: string;
-    language?: string;
-    locale?: string;
-    pathPrefix?: string;
-    [key: string]: unknown;
-}
-/**
- * Minimal Storefront client shape required by component loaders. The host app
- * provides this (public or private token mode); Weaverse never owns it.
- */
-interface WeaverseNextStorefront {
-    i18n?: WeaverseNextI18n;
-    query: (query: string, options?: unknown) => Promise<unknown>;
-    [key: string]: unknown;
-}
-/**
- * App-provided commerce context. `storefront` is the only v0 must-have; cart
- * and customer-account stay app-owned and are passed through untouched.
- */
-interface WeaverseNextCommerceContext {
-    cart?: unknown;
-    customerAccount?: unknown;
-    storefront?: WeaverseNextStorefront;
-    [key: string]: unknown;
-}
-/**
- * Explicit, framework-neutral replacement for React Router's
- * `LoaderFunctionArgs`. Built by the Next route/page from params + headers +
- * searchParams instead of an implicit loader context.
- */
-interface WeaverseNextRequestContext {
-    handle?: string;
-    headers?: Headers;
-    i18n?: WeaverseNextI18n;
-    isDesignMode?: boolean;
-    isPreviewMode?: boolean;
-    isRevisionPreview?: boolean;
-    pageType?: PageType;
-    pathname?: string;
-    searchParams?: URLSearchParams;
-    sectionType?: string;
-    url?: URL | string;
-    [key: string]: unknown;
-}
-/** A single serialized item in a Weaverse page tree. */
-interface WeaverseNextComponentData {
-    children?: WeaverseNextComponentData[] | {
-        id: string;
-    }[];
-    data?: Record<string, unknown>;
-    id: string;
-    /** Attached by {@link runWeaverseComponentLoaders} after a loader runs. */
-    loaderData?: unknown;
-    type: string;
-    [key: string]: unknown;
-}
-/** Serialized page tree fetched from Weaverse. */
-interface WeaverseNextPageData {
-    id: string;
-    items: WeaverseNextComponentData[];
-    name?: string;
-    rootId?: string;
-    [key: string]: unknown;
-}
-/**
- * Top-level payload returned by `client.loadPage`. Kept close to Hydrogen's
- * `WeaverseLoaderData` so registered components stay portable.
- */
-interface WeaverseNextLoaderData {
-    configs?: Record<string, unknown>;
-    page: WeaverseNextPageData;
-    pageAssignment?: Record<string, unknown>;
-    project?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-/** Props injected into every registered Weaverse component. */
-interface WeaverseNextComponentProps<L = unknown> extends Partial<WeaverseElement> {
-    children?: ReactNode;
-    className?: string;
-    loaderData?: L;
-    [key: string]: unknown;
-}
-/**
- * Arguments passed to a component `loader`. `commerce.storefront` is the
- * explicit contract; `weaverse.storefront` exists as a compatibility alias for
- * Pilot-style loaders that call `weaverse.storefront.query(...)`.
- */
-interface WeaverseNextComponentLoaderArgs<TData = unknown> {
-    commerce?: WeaverseNextCommerceContext;
-    context?: WeaverseNextRequestContext;
-    data: TData;
-    weaverse: WeaverseNextClient;
-}
-/** Registered component module shape: `default` + `schema` + optional `loader`. */
-interface WeaverseNextComponent<TProps extends WeaverseNextComponentProps = WeaverseNextComponentProps> {
-    default: ComponentType<TProps> | ForwardRefExoticComponent<TProps>;
-    loader?: (args: WeaverseNextComponentLoaderArgs) => Promise<unknown>;
-    schema: SchemaType;
-}
-/** Input for `client.loadPage`. The Next route maps `params` → `type/handle`. */
-interface WeaverseNextLoadPageInput {
-    handle?: string;
-    locale?: string;
-    type?: PageType;
-    [key: string]: unknown;
-}
-interface WeaverseNextClientConfig {
-    commerce?: WeaverseNextCommerceContext;
-    components: WeaverseNextComponent[];
-    /**
-     * Injected page fetcher. v0 delegates network I/O to the host app so the
-     * adapter can be tested without real Weaverse API calls.
-     */
-    fetchPage?: (input: WeaverseNextLoadPageInput) => Promise<WeaverseNextLoaderData | null>;
-    /** Injected theme-settings fetcher. */
-    fetchThemeSettings?: (context?: WeaverseNextRequestContext) => Promise<unknown>;
-    projectId: string;
-    requestContext?: WeaverseNextRequestContext;
-    themeSchema?: unknown;
-    themeSettings?: Record<string, unknown>;
-}
-/**
- * Request-safe client returned by {@link createWeaverseNextClient}. Holds the
- * registry/config plus the currently loaded page data, and is the object passed
- * to component loaders as `weaverse`.
- */
-interface WeaverseNextClient {
-    commerce?: WeaverseNextCommerceContext;
-    components: WeaverseNextComponent[];
-    /** Currently loaded page payload (set by `loadPage`). */
-    data: WeaverseNextLoaderData | null;
-    /** Data-connector context handed to the React renderer. */
-    dataContext: Record<string, unknown>;
-    loadPage: (input?: WeaverseNextLoadPageInput) => Promise<WeaverseNextLoaderData | null>;
-    loadThemeSettings: (context?: WeaverseNextRequestContext) => Promise<unknown>;
-    projectId: string;
-    requestContext?: WeaverseNextRequestContext;
-    /** Compatibility alias for `commerce.storefront`. */
-    storefront?: WeaverseNextStorefront;
-    themeSchema?: unknown;
-    themeSettings: Record<string, unknown>;
-}
-type WeaverseProduct = WeaverseResourcePickerData;
-type WeaverseCollection = WeaverseResourcePickerData;
+import * as react from 'react';
+import { ReactNode } from 'react';
 
 /**
  * Create a {@link WeaverseNextClient} from explicit config.
@@ -187,8 +36,9 @@ declare function useWeaversePageData<T = unknown>(): T;
 /** Read the app-provided commerce context (storefront/cart/customer). */
 declare function useWeaverseCommerce<T = WeaverseNextCommerceContext>(): T;
 /**
- * Read Weaverse theme settings. Next version backed by provider root/theme
- * data (`client.themeSettings`), not the Hydrogen theme-settings store.
+ * Read live Weaverse theme settings. The Studio bridge updates the provider's
+ * external store via `updateThemeSettings`, so components re-render during live
+ * design-mode edits.
  */
 declare function useThemeSettings<T = Record<string, unknown>>(): T;
 
@@ -212,15 +62,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>;
 }
@@ -262,4 +254,338 @@ interface WeaverseNextRendererProps {
  */
 declare const WeaverseNextRenderer: react.MemoExoticComponent<(props: WeaverseNextRendererProps) => react_jsx_runtime.JSX.Element | null>;
 
-export { type RunComponentLoadersArgs, type WeaverseCollection, type WeaverseNextClient, type WeaverseNextClientConfig, type WeaverseNextCommerceContext, type WeaverseNextComponent, type WeaverseNextComponentData, type WeaverseNextComponentLoaderArgs, type WeaverseNextComponentProps, type WeaverseNextI18n, type WeaverseNextLoadPageInput, type WeaverseNextLoaderData, type WeaverseNextPageData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, type WeaverseNextRequestContext, type WeaverseNextStorefront, type WeaverseProduct, createWeaverseNextClient, runWeaverseComponentLoaders, useThemeSettings, useWeaverseCommerce, useWeaversePageData, useWeaverseRootData };
+/**
+ * Build the Hydrogen-like request info shape consumed by the Studio bridge.
+ * Duplicate query keys keep the last value, matching `URLSearchParams` iteration
+ * assignment and Hydrogen's practical query-object behavior.
+ */
+declare function buildWeaverseNextRequestInfo(context?: WeaverseNextRequestContext): WeaverseNextRequestInfo;
+
+declare const DEFAULT_REVALIDATE_ENDPOINT = "/api/weaverse/revalidate";
+/**
+ * Minimal runtime surface the in-place apply needs. Structural (not the
+ * concrete `WeaverseNextRuntime` class) so unit tests can drive it with a
+ * plain mock.
+ */
+interface RevalidateItemRuntimeLike {
+    itemInstances: Map<string, {
+        setData: (update: Record<string, unknown>) => unknown;
+    }>;
+}
+/**
+ * Studio per-item loader revalidation: POST the unsaved draft item to the
+ * app's revalidate route (see `createWeaverseNextRevalidateHandler`) and apply
+ * the returned `loaderData` to the live item instance in place.
+ *
+ * No `router.refresh()` is involved, so the RSC tree is never re-applied — no
+ * page remount, no scroll reset, and the draft payload never touches the URL.
+ *
+ * Throws on any failure (missing route, non-OK response, unknown item) so the
+ * Builder Studio bridge can detect the miss and fall back to its legacy
+ * refresh-based revalidation for this window.
+ */
+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?: WeaverseNextThemeSchema;
+}
+/**
+ * Root-scoped client boundary that owns the single `WeaverseNextThemeSettingsStore`
+ * for the whole app session, matching Hydrogen's `withWeaverse()` root store.
+ * Mount once in `app/layout.tsx`, above `Header`/`Footer`/global modules and any
+ * route-level `WeaverseNextProvider`.
+ *
+ * Also renders `WeaverseNextContext` with a minimal value so `useThemeSettings()`
+ * works for components mounted directly under this provider, even without a
+ * route-level `WeaverseNextProvider` above them.
+ *
+ * @example
+ * ```tsx
+ * <WeaverseNextRootProvider initialThemeSettings={theme.theme} themeSchema={theme.schema}>
+ *   <Header />
+ *   {children}
+ *   <Footer />
+ * </WeaverseNextRootProvider>
+ * ```
+ */
+declare function WeaverseNextRootProvider(props: WeaverseNextRootProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Item store that flattens the serialized item's nested `data` field onto the
+ * store and seeds schema defaults — same shape Hydrogen produces, so the
+ * shared `@weaverse/react` renderer can spread props at the top level.
+ */
+declare class WeaverseNextItem extends WeaverseItemStore {
+    weaverse: WeaverseNextRuntime;
+    /**
+     * Cached merged snapshot (base `_store` + translations). Reset whenever the
+     * `_store` ref or the item's translation entry ref changes, so
+     * `useSyncExternalStore` sees a stable object between unrelated re-renders.
+     */
+    private _cachedSnapshot;
+    private _snapshotStoreRef;
+    private _snapshotTranslationRef;
+    constructor(initialData: WeaverseNextComponentData, weaverse: Weaverse);
+    /**
+     * Flatten nested `data` on updates exactly like the constructor does. Core's
+     * `initProject()` calls `setData(item)` when a new runtime serves a page
+     * whose item instances already exist (e.g. locale/client navigation), and
+     * the inherited shallow merge would leave stale top-level props behind.
+     * Assigning through the inherited `data` setter swaps the `_store` ref,
+     * which invalidates the memoized snapshot below. The subscriber emit is
+     * queued instead of fired when a render-phase deferral is active (see
+     * `collectDeferredItemUpdates`).
+     */
+    setData: (update: Omit<ElementData, "id" | "type">) => ElementData;
+    /**
+     * Overlay item-level translations onto the base store when the runtime is in
+     * translation mode. Mirrors Hydrogen's `WeaverseHydrogenItem.getSnapShot()`:
+     * memoized by `_store` ref + translation entry ref so the returned object is
+     * referentially stable, and a fast path that returns the base store untouched
+     * when the item has no translations.
+     */
+    getSnapShot: () => ElementData;
+}
+
+declare global {
+    interface Window {
+        __weaverse?: WeaverseNextRuntime;
+        __weaverses?: Record<string, WeaverseNextRuntime>;
+    }
+}
+declare class WeaverseNextRuntime extends Weaverse {
+    pageId: string;
+    internal: WeaverseNextRuntimeInternal;
+    requestInfo: WeaverseNextRequestInfo;
+    isPreviewMode: boolean;
+    isRevisionPreview: boolean;
+    sectionType?: string;
+    /**
+     * 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;
+    /**
+     * Fresh page data captured while React was rendering. Runtime reuse happens
+     * inside the renderer's render phase (`useMemo`), where applying it through
+     * `setProjectData()` would emit item updates to `useSyncExternalStore`
+     * subscribers mid-render. The renderer applies it post-commit via
+     * `flushRenderPhaseUpdates()`. Never set on design-mode runtimes — the live
+     * Studio tree owns the page data there.
+     */
+    pendingProjectData?: WeaverseNextPageData & {
+        rootId: string;
+    };
+    /**
+     * Reused item instances whose data was refreshed while this runtime was
+     * constructed during render (core `initProject()` calls `setData()` on
+     * them). Their data is already fresh; only the subscriber notification was
+     * deferred to `flushRenderPhaseUpdates()`.
+     */
+    pendingItemUpdates: WeaverseNextItem[];
+    constructor(config: WeaverseNextRuntimeConfig);
+    /**
+     * 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;
+    /**
+     * Apply updates deferred off the render phase: swap in any pending page data
+     * captured on runtime reuse, then notify items whose data was refreshed
+     * during construction. The renderer calls this from a layout effect right
+     * after commit, so subscribers re-render before paint (no content flash) and
+     * without React's setState-in-render warning.
+     */
+    flushRenderPhaseUpdates: () => void;
+}
+declare function createWeaverseNextRuntime(config: WeaverseNextRuntimeConfig): WeaverseNextRuntime;
+declare function bindWeaverseNextStudioRuntime(runtime: WeaverseNextRuntime): boolean;
+
+interface WeaverseNextStudioBridgeProps {
+    navigate?: WeaverseNextRuntimeInternal['navigate'];
+    revalidate?: WeaverseNextRuntimeInternal['revalidate'];
+    revalidateItem?: WeaverseNextRuntimeInternal['revalidateItem'];
+    runtime: WeaverseNextRuntime;
+}
+/** Page-level Studio runtime binder. */
+declare function WeaverseNextStudioBridge(props: WeaverseNextStudioBridgeProps): null;
+
+interface LoadWeaverseNextStudioScriptOptions {
+    storefrontHostname?: string;
+}
+/**
+ * Resolve and append the Next Studio bridge script for the given request
+ * context, deduping by src. SSR-safe (no-op without `document`) so it can run
+ * unconditionally from a root layout/error boundary before any page tree or
+ * runtime exists — e.g. App Router `not-found.tsx` / `error.tsx` routes.
+ */
+declare function loadWeaverseNextStudioScript(context?: WeaverseNextRequestContext, options?: LoadWeaverseNextStudioScriptOptions): void;
+interface WeaverseNextStudioConnectProps {
+    context?: WeaverseNextRequestContext;
+    storefrontHostname?: string;
+}
+/**
+ * Root-level Studio script connector for Next client boundaries. Mount once
+ * near the app root (e.g. root layout) so it also covers routes that never
+ * render `WeaverseNextRenderer`, such as `not-found.tsx` / `error.tsx`.
+ */
+declare function WeaverseNextStudioConnect(props: WeaverseNextStudioConnectProps): null;
+
+/**
+ * Minimal structural shape of the Next App Router returned by `useRouter()`
+ * (`next/navigation`) that the Studio bridge needs. Declared locally — rather
+ * than importing `AppRouterInstance` from `next` — so the adapter stays a pure
+ * function that unit tests can drive with a plain mock and never pulls
+ * `next/navigation` into the test graph.
+ */
+interface WeaverseNextRouterLike {
+    push: (href: string, options?: {
+        scroll?: boolean;
+    }) => void;
+    refresh: () => void;
+    replace: (href: string, options?: {
+        scroll?: boolean;
+    }) => void;
+}
+/** Resolved Studio navigation/revalidation callbacks for a Next runtime. */
+interface WeaverseNextStudioInternals {
+    navigate: NonNullable<WeaverseNextRuntimeInternal['navigate']>;
+    revalidate: NonNullable<WeaverseNextRuntimeInternal['revalidate']>;
+}
+interface CreateWeaverseNextStudioInternalsOptions {
+    /** Use `router.replace` instead of `router.push` for navigation. */
+    replace?: boolean;
+}
+/**
+ * Build Studio `navigate` / `revalidate` callbacks from a Next App Router.
+ *
+ * Maps Hydrogen's React Router semantics onto Next App Router:
+ * - `navigate(to, { preventScrollReset })` → `router.push(to, { scroll })`,
+ *   where `scroll` is the inverse of `preventScrollReset`. Studio passes
+ *   `preventScrollReset` for in-place edits so the preview viewport is kept,
+ *   matching React Router's `navigate({ preventScrollReset })`.
+ * - `revalidate()` → `router.refresh()`, the App Router's loader-backed refresh
+ *   and the closest equivalent to React Router's `useRevalidator`.
+ *
+ * Pure (no React, no `next/navigation`) so it is unit-testable with a mock
+ * router; the {@link WeaverseNextRouterLike} contract is the only coupling.
+ */
+declare function createWeaverseNextStudioInternals(router: WeaverseNextRouterLike, options?: CreateWeaverseNextStudioInternalsOptions): WeaverseNextStudioInternals;
+
+interface ResolveWeaverseNextStudioScriptSrcOptions {
+    storefrontHostname?: string;
+}
+/**
+ * Resolve the Studio script URL from request/search context. `@weaverse/next`
+ * uses the dedicated Next bridge path served by Builder.
+ */
+declare function resolveWeaverseNextStudioScriptSrc(context?: WeaverseNextRequestContext, options?: ResolveWeaverseNextStudioScriptSrcOptions): string | null;
+
+interface CreateWeaverseNextThemeSettingsStoreOptions {
+    publicEnv?: Record<string, string | undefined>;
+    schema?: WeaverseNextThemeSchema;
+    settings?: Record<string, unknown>;
+}
+/**
+ * Small external store shape compatible with the Studio bridge and React's
+ * `useSyncExternalStore` contract. The bridge calls `updateThemeSettings` during
+ * live theme edits, so keep that method name stable.
+ */
+declare function createWeaverseNextThemeSettingsStore(options?: CreateWeaverseNextThemeSettingsStoreOptions): WeaverseNextThemeSettingsStore;
+
+/**
+ * Resolve stable Studio `navigate` / `revalidate` callbacks from the Next App
+ * Router. `useRouter()` is stable across renders, but the derived callbacks are
+ * cached in a ref keyed on the router instance so the bridge's bind effect
+ * (which depends on `navigate` / `revalidate` identity) doesn't re-run — and
+ * re-`refreshStudio` — on every render.
+ */
+declare function useWeaverseNextStudioInternals(options?: CreateWeaverseNextStudioInternalsOptions): WeaverseNextStudioInternals;
+interface WeaverseNextStudioProps extends CreateWeaverseNextStudioInternalsOptions {
+    /**
+     * Route the app mounted with `createWeaverseNextRevalidateHandler`.
+     * Defaults to `/api/weaverse/revalidate`.
+     */
+    revalidateEndpoint?: string;
+    runtime: WeaverseNextRuntime;
+}
+/**
+ * Page-level Studio binder wired to the Next App Router. Mirrors Hydrogen's
+ * `useStudio` (which binds the runtime and feeds it React Router's `navigate` /
+ * `revalidate`): it resolves the App Router callbacks via
+ * {@link useWeaverseNextStudioInternals} and hands them to
+ * {@link WeaverseNextStudioBridge}, so consuming apps get Studio navigation and
+ * revalidation without manually wiring `next/navigation`.
+ *
+ * Client-only — it is the single place `@weaverse/next` touches
+ * `next/navigation`, keeping the runtime/renderer and `@weaverse/next/server`
+ * free of router imports.
+ */
+declare function WeaverseNextStudio(props: WeaverseNextStudioProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Generate default component data from a schema's `settings` inputs.
+ *
+ * Mirrors Hydrogen's `generateDataFromSchema` (settings → `{ [name]:
+ * defaultValue }`) but is kept local so `@weaverse/next` doesn't depend on
+ * `@weaverse/hydrogen`. Falls back to the deprecated `inspector` array when a
+ * schema predates `settings`.
+ */
+declare function generateDataFromSchema(schema: SchemaType | WeaverseNextThemeSchema | undefined): Record<string, unknown>;
+
+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, WeaverseNextThemeSchema, WeaverseNextThemeSettingsStore, WeaverseNextTranslationChanges, WeaverseNextTranslationMap, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createTranslate, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextStudioInternals, createWeaverseNextThemeSettingsStore, generateDataFromSchema, getNestedKey, interpolate, loadWeaverseNextStudioScript, resolveWeaverseNextStudioScriptSrc, revalidateWeaverseNextItem, runWeaverseComponentLoaders, useThemeSettings, useThemeText, useTranslation, useWeaverseCommerce, useWeaverseNextStudioInternals, useWeaversePageData, useWeaverseRootData };