@weaverse/next 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/{chunk-SS6QUKYY.mjs → chunk-XXGMPTWH.mjs}

@@ -133,8 +133,22 @@ function toQueryRecord(searchParams) {
   }
   return queries;
 }
+var TRANSIENT_STUDIO_PARAMS = /* @__PURE__ */ new Set([
+  "weaverseDraftItem",
+  // Legacy name from the original design-mode draft-item spike. Keep it out of
+  // runtime requestInfo too, in case an older Builder bundle is in front of a
+  // newer Next storefront.
+  "__weaverseDraftItem"
+]);
+function getRequestInfoSearchParams(context) {
+  let searchParams = new URLSearchParams(getSearchParamsFromContext(context));
+  for (let key of TRANSIENT_STUDIO_PARAMS) {
+    searchParams.delete(key);
+  }
+  return searchParams;
+}
 function buildWeaverseNextRequestInfo(context) {
-  let searchParams = getSearchParamsFromContext(context);
+  let searchParams = getRequestInfoSearchParams(context);
   let search = searchParams.toString();
   return {
     pathname: getPathnameFromContext(context),
@@ -144,6 +158,62 @@ function buildWeaverseNextRequestInfo(context) {
   };
 }
 
-export { buildWeaverseNextRequestInfo, generateDataFromSchema, runWeaverseComponentLoaders };
-//# sourceMappingURL=chunk-SS6QUKYY.mjs.map
-//# sourceMappingURL=chunk-SS6QUKYY.mjs.map
+// src/seo.ts
+function hasOpenGraphContent(seo) {
+  return Boolean(seo?.title || seo?.description || seo?.image || seo?.type);
+}
+function hasTwitterContent(seo) {
+  return Boolean(seo?.title || seo?.description || seo?.image || seo?.cardType);
+}
+function formatWeaverseNextSeoMetadata(seo) {
+  let index = seo?.robots?.index !== false;
+  let follow = seo?.robots?.follow !== false;
+  let metadata = {
+    robots: { index, follow }
+  };
+  if (!seo) {
+    return metadata;
+  }
+  if (seo.title) {
+    metadata.title = seo.title;
+  }
+  if (seo.description) {
+    metadata.description = seo.description;
+  }
+  if (seo.keywords) {
+    metadata.keywords = seo.keywords;
+  }
+  if (seo.canonicalUrl) {
+    metadata.alternates = { canonical: seo.canonicalUrl };
+  }
+  let openGraph = seo.openGraph;
+  if (hasOpenGraphContent(openGraph)) {
+    metadata.openGraph = {
+      title: openGraph?.title,
+      description: openGraph?.description,
+      images: openGraph?.image ? [openGraph.image] : void 0,
+      type: openGraph?.type || "website"
+    };
+  }
+  let twitter = seo.twitter;
+  if (hasTwitterContent(twitter)) {
+    metadata.twitter = {
+      card: twitter?.cardType || "summary",
+      title: twitter?.title,
+      description: twitter?.description,
+      images: twitter?.image ? [twitter.image] : void 0
+    };
+  }
+  return metadata;
+}
+function getWeaverseNextSeoMetadata(data) {
+  if (!data) {
+    return formatWeaverseNextSeoMetadata(null);
+  }
+  let page = "items" in data && "id" in data ? data : data.page ?? null;
+  return formatWeaverseNextSeoMetadata(page?.seo ?? null);
+}
+
+export { buildWeaverseNextRequestInfo, formatWeaverseNextSeoMetadata, generateDataFromSchema, getWeaverseNextSeoMetadata, runWeaverseComponentLoaders };
+//# sourceMappingURL=chunk-XXGMPTWH.mjs.map
+//# sourceMappingURL=chunk-XXGMPTWH.mjs.map

package/dist/chunk-XXGMPTWH.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/loader.ts","../src/request-info.ts","../src/seo.ts"],"names":[],"mappings":"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","file":"chunk-XXGMPTWH.mjs","sourcesContent":["import type { SchemaType } from '@weaverse/schema'\nimport type { WeaverseNextThemeSchema } from './types'\n\n/**\n * Generate default component data from a schema's `settings` inputs.\n *\n * Mirrors Hydrogen's `generateDataFromSchema` (settings → `{ [name]:\n * defaultValue }`) but is kept local so `@weaverse/next` doesn't depend on\n * `@weaverse/hydrogen`. Falls back to the deprecated `inspector` array when a\n * schema predates `settings`.\n */\nexport function generateDataFromSchema(\n  schema: SchemaType | WeaverseNextThemeSchema | undefined\n): Record<string, unknown> {\n  let data: Record<string, unknown> = {}\n  if (!schema) {\n    return data\n  }\n\n  let groups =\n    (schema.settings as {\n      inputs?: { name?: string; defaultValue?: unknown }[]\n    }[]) ??\n    (schema as { inspector?: typeof groups }).inspector ??\n    []\n\n  for (let group of groups) {\n    for (let input of group?.inputs ?? []) {\n      let { name, defaultValue } = input\n      if (name && defaultValue !== null && defaultValue !== undefined) {\n        data[name] = defaultValue\n      }\n    }\n  }\n\n  return data\n}\n","import type {\n  WeaverseNextClient,\n  WeaverseNextCommerceContext,\n  WeaverseNextComponent,\n  WeaverseNextComponentData,\n  WeaverseNextLoaderData,\n  WeaverseNextRequestContext,\n} from './types'\nimport { generateDataFromSchema } from './utils'\n\nexport interface RunComponentLoadersArgs {\n  client: WeaverseNextClient\n  commerce?: WeaverseNextCommerceContext\n  context?: WeaverseNextRequestContext\n  /** Page payload to walk; defaults to `client.data`. */\n  data?: WeaverseNextLoaderData | null\n}\n\nfunction isItemNode(node: unknown): node is WeaverseNextComponentData {\n  return (\n    typeof node === 'object' &&\n    node !== null &&\n    typeof (node as WeaverseNextComponentData).type === 'string'\n  )\n}\n\nfunction cloneItem(item: WeaverseNextComponentData): WeaverseNextComponentData {\n  return {\n    ...item,\n    children: Array.isArray(item.children)\n      ? item.children.map((child) =>\n          isItemNode(child) ? cloneItem(child) : { ...child }\n        )\n      : item.children,\n  }\n}\n\n/**\n * Walk a serialized page tree and run each registered component's `loader`,\n * attaching the result to the item as `loaderData`.\n *\n * Loaders receive explicit `commerce.storefront` (and `weaverse.storefront` as\n * a compatibility alias via the client). Children are walked recursively when\n * they are inline item objects; flat `items` arrays are covered by the\n * top-level walk.\n *\n * @returns a cloned `data` object with `loaderData` attached to cloned items.\n */\nexport async function runWeaverseComponentLoaders(\n  args: RunComponentLoadersArgs\n): Promise<WeaverseNextLoaderData | null> {\n  let { client, context, commerce } = args\n  let sourceData = args.data ?? client.data\n  if (!sourceData) {\n    return null\n  }\n  if (!sourceData.page.items.length) {\n    return sourceData\n  }\n\n  let data: WeaverseNextLoaderData = {\n    ...sourceData,\n    page: {\n      ...sourceData.page,\n      items: sourceData.page.items.map(cloneItem),\n    },\n  }\n  let items = data.page.items\n\n  let componentMap = new Map<string, WeaverseNextComponent>()\n  for (let component of client.components) {\n    if (component?.schema?.type) {\n      componentMap.set(component.schema.type, component)\n    }\n  }\n\n  let visited = new Set<string>()\n  let resolvedContext = context ?? client.requestContext\n  let resolvedCommerce = commerce ?? client.commerce\n\n  // Per-call `weaverse` alias. When a request-scoped `commerce` is passed, the\n  // `weaverse.storefront` compatibility alias must resolve to *that* storefront,\n  // not the client's construction-time commerce. Pilot-style loaders call\n  // `weaverse.storefront.query(...)`, so a stale alias would query the wrong\n  // (or an undefined) storefront. When no override is given we reuse the client\n  // as-is to preserve its prototype getters.\n  let resolvedWeaverse: WeaverseNextClient =\n    resolvedCommerce === client.commerce\n      ? client\n      : {\n          ...client,\n          commerce: resolvedCommerce,\n          storefront: resolvedCommerce?.storefront,\n        }\n\n  async function walk(nodes: WeaverseNextComponentData[]) {\n    for (let item of nodes) {\n      if (!item || visited.has(item.id)) {\n        continue\n      }\n      visited.add(item.id)\n\n      let component = componentMap.get(item.type)\n      if (component?.loader) {\n        try {\n          item.loaderData = await component.loader({\n            data: { ...generateDataFromSchema(component.schema), ...item.data },\n            weaverse: resolvedWeaverse,\n            context: resolvedContext,\n            commerce: resolvedCommerce,\n          })\n        } catch (error) {\n          console.warn('❌ Item loader run failed.', item.type, item.id, error)\n        }\n      }\n\n      let children = item.children\n      if (Array.isArray(children)) {\n        let inlineChildren = children.filter(\n          isItemNode\n        ) as WeaverseNextComponentData[]\n        if (inlineChildren.length) {\n          await walk(inlineChildren)\n        }\n      }\n    }\n  }\n\n  await walk(items)\n  return data\n}\n","import type {\n  WeaverseNextRequestContext,\n  WeaverseNextRequestInfo,\n} from './types'\n\nfunction toUrl(value: string | URL): URL {\n  return typeof value === 'string' ? new URL(value, 'http://localhost') : value\n}\n\nfunction getSearchParamsFromContext(\n  context?: WeaverseNextRequestContext\n): URLSearchParams {\n  if (context?.searchParams) {\n    return new URLSearchParams(context.searchParams)\n  }\n\n  if (context?.url) {\n    let url = toUrl(context.url)\n    return new URLSearchParams(url.searchParams)\n  }\n\n  return new URLSearchParams()\n}\n\nfunction getPathnameFromContext(context?: WeaverseNextRequestContext): string {\n  if (context?.pathname) {\n    return context.pathname\n  }\n\n  if (context?.url) {\n    let url = toUrl(context.url)\n    return url.pathname || '/'\n  }\n\n  return '/'\n}\n\nfunction coerceQueryValue(value: string): string | boolean {\n  if (value === 'true') {\n    return true\n  }\n  if (value === 'false') {\n    return false\n  }\n  return value\n}\n\nfunction toQueryRecord(\n  searchParams: URLSearchParams\n): Record<string, string | boolean> {\n  let queries: Record<string, string | boolean> = {}\n  for (let [key, value] of searchParams.entries()) {\n    queries[key] = coerceQueryValue(value)\n  }\n  return queries\n}\n\nconst TRANSIENT_STUDIO_PARAMS = new Set([\n  'weaverseDraftItem',\n  // Legacy name from the original design-mode draft-item spike. Keep it out of\n  // runtime requestInfo too, in case an older Builder bundle is in front of a\n  // newer Next storefront.\n  '__weaverseDraftItem',\n])\n\nfunction getRequestInfoSearchParams(\n  context?: WeaverseNextRequestContext\n): URLSearchParams {\n  let searchParams = new URLSearchParams(getSearchParamsFromContext(context))\n  for (let key of TRANSIENT_STUDIO_PARAMS) {\n    searchParams.delete(key)\n  }\n  return searchParams\n}\n\n/**\n * Build the Hydrogen-like request info shape consumed by the Studio bridge.\n * Duplicate query keys keep the last value, matching `URLSearchParams` iteration\n * assignment and Hydrogen's practical query-object behavior.\n */\nexport function buildWeaverseNextRequestInfo(\n  context?: WeaverseNextRequestContext\n): WeaverseNextRequestInfo {\n  let searchParams = getRequestInfoSearchParams(context)\n  let search = searchParams.toString()\n\n  return {\n    pathname: getPathnameFromContext(context),\n    search: search ? `?${search}` : '',\n    queries: toQueryRecord(searchParams),\n    ...(context?.i18n ? { i18n: context.i18n } : {}),\n  }\n}\n","import type { PageSEOData } from '@weaverse/schema'\nimport type { WeaverseNextLoaderData, WeaverseNextPageData } from './types'\n\nexport interface WeaverseNextSeoMetadata {\n  alternates?: { canonical?: string }\n  description?: string\n  keywords?: string\n  openGraph?: {\n    description?: string\n    images?: string[]\n    title?: string\n    type?: string\n  }\n  robots: {\n    follow: boolean\n    index: boolean\n  }\n  title?: string\n  twitter?: {\n    card?: string\n    description?: string\n    images?: string[]\n    title?: string\n  }\n}\n\nfunction hasOpenGraphContent(seo: PageSEOData['openGraph']): boolean {\n  return Boolean(seo?.title || seo?.description || seo?.image || seo?.type)\n}\n\nfunction hasTwitterContent(seo: PageSEOData['twitter']): boolean {\n  return Boolean(seo?.title || seo?.description || seo?.image || seo?.cardType)\n}\n\nexport function formatWeaverseNextSeoMetadata(\n  seo: PageSEOData | null | undefined\n): WeaverseNextSeoMetadata {\n  let index = seo?.robots?.index !== false\n  let follow = seo?.robots?.follow !== false\n  let metadata: WeaverseNextSeoMetadata = {\n    robots: { index, follow },\n  }\n\n  if (!seo) {\n    return metadata\n  }\n\n  if (seo.title) {\n    metadata.title = seo.title\n  }\n  if (seo.description) {\n    metadata.description = seo.description\n  }\n  if (seo.keywords) {\n    metadata.keywords = seo.keywords\n  }\n  if (seo.canonicalUrl) {\n    metadata.alternates = { canonical: seo.canonicalUrl }\n  }\n\n  let openGraph = seo.openGraph\n  if (hasOpenGraphContent(openGraph)) {\n    metadata.openGraph = {\n      title: openGraph?.title,\n      description: openGraph?.description,\n      images: openGraph?.image ? [openGraph.image] : undefined,\n      type: openGraph?.type || 'website',\n    }\n  }\n\n  let twitter = seo.twitter\n  if (hasTwitterContent(twitter)) {\n    metadata.twitter = {\n      card: twitter?.cardType || 'summary',\n      title: twitter?.title,\n      description: twitter?.description,\n      images: twitter?.image ? [twitter.image] : undefined,\n    }\n  }\n\n  return metadata\n}\n\nexport function getWeaverseNextSeoMetadata(\n  data:\n    | WeaverseNextLoaderData\n    | WeaverseNextPageData\n    | { page?: WeaverseNextPageData | null }\n    | null\n    | undefined\n): WeaverseNextSeoMetadata {\n  if (!data) {\n    return formatWeaverseNextSeoMetadata(null)\n  }\n  let page =\n    'items' in data && 'id' in data\n      ? (data as WeaverseNextPageData)\n      : ((data as { page?: WeaverseNextPageData | null }).page ?? null)\n  return formatWeaverseNextSeoMetadata(page?.seo ?? null)\n}\n"]}

package/dist/index.d.mts

@@ -1,8 +1,9 @@
-import { Weaverse } from '@weaverse/react';
+import { WeaverseItemStore, Weaverse, ElementData } from '@weaverse/react';
 export { isBrowser, isIframe, useChildInstances, useItemInstance, useParentInstance, useWeaverse } from '@weaverse/react';
-export { InspectorGroup, PageType, SchemaType, createSchema } from '@weaverse/schema';
-import { d as WeaverseNextClientConfig, c as WeaverseNextClient, e as WeaverseNextCommerceContext, q as WeaverseNextRequestContext, n as WeaverseNextLoaderData, r as WeaverseNextRequestInfo, t as WeaverseNextRuntimeInternal, s as WeaverseNextRuntimeConfig, A as WeaverseNextThemeSettingsStore } from './types-DvEeLX6L.mjs';
-export { W as WeaverseCollection, f as WeaverseNextComponent, g as WeaverseNextComponentData, h as WeaverseNextComponentLoaderArgs, i as WeaverseNextComponentProps, l as WeaverseNextI18n, m as WeaverseNextLoadPageInput, o as WeaverseNextPageData, x as WeaverseNextStorefront, B as WeaverseProduct } from './types-DvEeLX6L.mjs';
+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';
 import * as react from 'react';
 import { ReactNode } from 'react';
@@ -61,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>;
 }
@@ -118,6 +261,114 @@ declare const WeaverseNextRenderer: react.MemoExoticComponent<(props: WeaverseNe
  */
 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;
@@ -131,14 +382,76 @@ 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;
+    /**
+     * 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);
-    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;
+    /**
+     * 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;
@@ -146,32 +459,86 @@ declare function bindWeaverseNextStudioRuntime(runtime: WeaverseNextRuntime): bo
 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. */
+/**
+ * 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 {
-    framework?: 'hydrogen' | 'next';
     storefrontHostname?: string;
 }
 /**
- * Resolve the Studio script URL from request/search context. v0 intentionally
- * reuses the existing structural Hydrogen bridge script until a concrete Builder
- * incompatibility requires a dedicated Next bundle.
+ * 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?: unknown;
+    schema?: WeaverseNextThemeSchema;
     settings?: Record<string, unknown>;
 }
 /**
@@ -181,4 +548,44 @@ interface CreateWeaverseNextThemeSettingsStoreOptions {
  */
 declare function createWeaverseNextThemeSettingsStore(options?: CreateWeaverseNextThemeSettingsStoreOptions): WeaverseNextThemeSettingsStore;
 
-export { type CreateWeaverseNextThemeSettingsStoreOptions, type ResolveWeaverseNextStudioScriptSrcOptions, type RunComponentLoadersArgs, WeaverseNextClient, WeaverseNextClientConfig, WeaverseNextCommerceContext, WeaverseNextLoaderData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, WeaverseNextRequestContext, WeaverseNextRequestInfo, WeaverseNextRuntime, WeaverseNextRuntimeConfig, WeaverseNextRuntimeInternal, WeaverseNextStudioBridge, type WeaverseNextStudioBridgeProps, WeaverseNextStudioConnect, type WeaverseNextStudioConnectProps, WeaverseNextThemeSettingsStore, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextThemeSettingsStore, resolveWeaverseNextStudioScriptSrc, runWeaverseComponentLoaders, useThemeSettings, useWeaverseCommerce, useWeaversePageData, useWeaverseRootData };
+/**
+ * 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 };