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

package/README.md

@@ -0,0 +1,165 @@
+# @weaverse/next
+
+Next.js App Router integration for building Weaverse-powered storefronts.
+
+This package adapts the Weaverse runtime (component registry, page-tree
+rendering, Studio bridge) to Next.js without depending on React Router or
+Hydrogen. It mirrors the `@weaverse/hydrogen` contract where it makes sense, but
+takes plain, framework-neutral inputs (URL, headers, search params) instead of a
+React Router `Request`/`LoaderFunctionArgs`.
+
+## Entrypoints
+
+| Import | Use in | Purpose |
+| --- | --- | --- |
+| `@weaverse/next` | Client & server | Registry, renderer, provider, hooks, Studio runtime/bridge. |
+| `@weaverse/next/server` | Server only | Server-side Weaverse client that fetches page/theme data from the Weaverse API. |
+
+> The server-side data-loading API lives under **`@weaverse/next/server`** so the
+> root entry stays free of server-only fetch assumptions and safe to import from
+> client components.
+
+## Package structure
+
+```text
+packages/next/src/
+  index.ts              # root (@weaverse/next) public exports
+  server.ts             # server (@weaverse/next/server) public exports
+  client.ts             # createWeaverseNextClient (injected-fetcher client)
+  loader.ts             # runWeaverseComponentLoaders (server-side section loaders)
+  registry.ts           # register components with the Weaverse element registry
+  renderer.tsx          # WeaverseNextRenderer (page-tree → React)
+  provider.tsx          # WeaverseNextProvider (client context for hooks)
+  hooks.ts              # useThemeSettings / useWeaversePageData / ...
+  runtime.ts            # WeaverseNextRuntime + Studio binding
+  studio-bridge.tsx     # Studio script injection / connect
+  request-info.ts       # buildWeaverseNextRequestInfo (Studio-compatible)
+  theme-settings-store.ts
+  types.ts              # shared types (root + server)
+  server/
+    server-client.ts    # createWeaverseNextServerClient
+    configs.ts          # getWeaverseNextConfigs (host/api-base/flags/env)
+    normalize-page-url.ts
+```
+
+## Root API (`@weaverse/next`)
+
+- `createWeaverseNextClient(config)` — request-safe client that delegates network
+  I/O to injected `fetchPage` / `fetchThemeSettings`.
+- `WeaverseNextProvider` / `WeaverseNextRenderer` — client provider + page-tree
+  renderer.
+- `runWeaverseComponentLoaders(args)` — walk a page tree and run each registered
+  component's `loader` server-side.
+- Hooks: `useThemeSettings`, `useWeaversePageData`, `useWeaverseRootData`,
+  `useWeaverseCommerce` (plus re-exported `@weaverse/react` hooks).
+- Studio helpers: `WeaverseNextRuntime`, `createWeaverseNextRuntime`,
+  `bindWeaverseNextStudioRuntime`, `WeaverseNextStudioBridge`,
+  `WeaverseNextStudioConnect`, `resolveWeaverseNextStudioScriptSrc`,
+  `buildWeaverseNextRequestInfo`, `createWeaverseNextThemeSettingsStore`.
+- `createSchema` (re-exported from `@weaverse/schema`).
+
+## Server API (`@weaverse/next/server`)
+
+`createWeaverseNextServerClient(config)` returns a client that performs the real
+Weaverse public API fetch — the equivalent of Hydrogen/Pilot's
+`context.weaverse.loadPage(...)`.
+
+### Next App Router server context model
+
+Hydrogen's classic storefront runtime is built on React Router. Its request
+handler accepts `getLoadContext(request)`, creates a Hydrogen context, and React
+Router injects that object into every route loader. That is why a Pilot route can
+call `context.weaverse.loadPage(...)` directly.
+
+Next App Router does not inject an app-defined global loader context into
+`app/page.tsx`. A page is a Server Component whose framework-provided inputs are
+`params` and `searchParams`; request-scoped data is read with Next functions such
+as `headers()` / `cookies()`. Hydrogen preview follows that framework model for
+Next examples: fetch in `app/page.tsx` or a server helper, then pass the snapshot
+to client components.
+
+So the Next equivalent is explicit server-client creation at the route boundary:
+
+```ts
+import { createWeaverseNextServerClient } from '@weaverse/next/server'
+import { components } from '@/weaverse/components'
+
+export async function loadWeaverse(request: Request, storefront: Storefront) {
+  let url = new URL(request.url)
+  let weaverse = createWeaverseNextServerClient({
+    projectId: process.env.WEAVERSE_PROJECT_ID, // string | (ctx) => string | Promise<string>
+    components,
+    themeSchema,
+    commerce: { storefront },
+    env: process.env,
+    requestContext: {
+      url,
+      headers: request.headers,
+      searchParams: url.searchParams,
+      i18n: storefront.i18n,
+    },
+    cache: { revalidate: 60, tags: ['weaverse'] },
+  })
+
+  let [page, theme] = await Promise.all([
+    weaverse.loadPage({ type: 'INDEX' }),
+    weaverse.loadThemeSettings(),
+  ])
+  return { page, theme, weaverse }
+}
+```
+
+### Returned client
+
+| Member | Description |
+| --- | --- |
+| `loadPage(input?)` | POSTs `{ projectId, url, i18n, params, isDesignMode }` to `/api/public/project`, runs component loaders, returns `WeaverseNextLoaderData` (`page`, `project`, `pageAssignment`, `configs.requestInfo`). In Studio preview mode (`?isPreviewMode=true`) it short-circuits to a synthetic single-section page built from the `sectionType` presets — no fetch, no `projectId` required. A route-level `projectId` override is propagated to `client.projectId`, loaders, and the returned `configs`. |
+| `loadThemeSettings(options?)` | POSTs to `/api/public/project_configs`, merges `themeSchema` defaults under `theme`, includes `staticContent`; falls back to defaults on failure. |
+| `fetchWithCache<T>(url, options?)` | Mode-aware fetch: `cache: 'no-store'` in design/revision, `next: { revalidate, tags }` in published mode. |
+| `projectId` / `resolveProjectId()` | Resolved project id (query → function → string → env). |
+| `components`, `commerce`, `storefront`, `requestContext`, `themeSchema`, `themeSettings`, `data`, `dataContext`, `configs` | Readonly request state. `storefront` aliases `commerce.storefront`. |
+
+### Config resolution
+
+Close to Hydrogen's `getWeaverseConfigs`:
+
+- **projectId** — `?weaverseProjectId=` query → config function → config string →
+  `WEAVERSE_PROJECT_ID` env.
+- **weaverseHost** — trusted request `?weaverseHost=` (only `weaverse.io` /
+  `weaverse.dev` over https) → `WEAVERSE_HOST` env → `https://studio.weaverse.io`.
+- **API base** — trusted request host → `WEAVERSE_PUBLIC_API_BASE` env → custom
+  non-production `WEAVERSE_HOST` → `https://api.weaverse.io`.
+- **publicEnv** — `PUBLIC_STORE_DOMAIN`, `PUBLIC_STOREFRONT_API_TOKEN`.
+
+`WEAVERSE_API_KEY` is read from the request query / env and kept on the internal
+base configs, but the current server client does **not** attach it to the
+page/theme API requests. It is also **never** serialized into client-facing
+`configs` / loader data, so it cannot leak to the browser.
+
+## Studio helpers
+
+Design/preview detection, the Studio bridge script, and the in-page runtime are
+shared with the root entry: `createWeaverseNextRuntime` + `WeaverseNextProvider`
+hydrate Studio, and `bindWeaverseNextStudioRuntime` wires live updates. The
+server client emits `configs.requestInfo` and design-mode flags the bridge
+expects.
+
+> **Mount `WeaverseNextStudioConnect` at your root/client shell.**
+> `WeaverseNextRenderer` mounts the in-page runtime bridge but does **not**
+> inject the Studio bridge script by itself. The script (which lets Studio's
+> `checkWeaversePage()` handshake answer on every route, including content-less
+> ones) is loaded by `WeaverseNextStudioConnect`, so it must be rendered once at
+> the app root/client shell for the Studio editor to connect.
+
+## Current limitations
+
+- Server fetch has a timeout + single attempt; it does not yet replicate
+  Hydrogen's subrequest cache, retry/backoff, or merchant-overrides translation
+  fetch.
+- Next caching is expressed only via `cache: 'no-store'` and
+  `next: { revalidate, tags }`; on-demand `revalidatePath`/`revalidateTag` is left
+  to the host app.
+- `loadCustomPages` (sitemap) and SEO helpers are not ported yet.
+- The Studio bridge currently reuses the Hydrogen bundle until a Next-specific
+  bundle is required.
+- Package is pre-release (`alpha`); the API may still change.

package/dist/chunk-SS6QUKYY.mjs

@@ -0,0 +1,149 @@
+// src/utils.ts
+function generateDataFromSchema(schema) {
+  let data = {};
+  if (!schema) {
+    return data;
+  }
+  let groups = schema.settings ?? schema.inspector ?? [];
+  for (let group of groups) {
+    for (let input of group?.inputs ?? []) {
+      let { name, defaultValue } = input;
+      if (name && defaultValue !== null && defaultValue !== void 0) {
+        data[name] = defaultValue;
+      }
+    }
+  }
+  return data;
+}
+
+// src/loader.ts
+function isItemNode(node) {
+  return typeof node === "object" && node !== null && typeof node.type === "string";
+}
+function cloneItem(item) {
+  return {
+    ...item,
+    children: Array.isArray(item.children) ? item.children.map(
+      (child) => isItemNode(child) ? cloneItem(child) : { ...child }
+    ) : item.children
+  };
+}
+async function runWeaverseComponentLoaders(args) {
+  let { client, context, commerce } = args;
+  let sourceData = args.data ?? client.data;
+  if (!sourceData) {
+    return null;
+  }
+  if (!sourceData.page.items.length) {
+    return sourceData;
+  }
+  let data = {
+    ...sourceData,
+    page: {
+      ...sourceData.page,
+      items: sourceData.page.items.map(cloneItem)
+    }
+  };
+  let items = data.page.items;
+  let componentMap = /* @__PURE__ */ new Map();
+  for (let component of client.components) {
+    if (component?.schema?.type) {
+      componentMap.set(component.schema.type, component);
+    }
+  }
+  let visited = /* @__PURE__ */ new Set();
+  let resolvedContext = context ?? client.requestContext;
+  let resolvedCommerce = commerce ?? client.commerce;
+  let resolvedWeaverse = resolvedCommerce === client.commerce ? client : {
+    ...client,
+    commerce: resolvedCommerce,
+    storefront: resolvedCommerce?.storefront
+  };
+  async function walk(nodes) {
+    for (let item of nodes) {
+      if (!item || visited.has(item.id)) {
+        continue;
+      }
+      visited.add(item.id);
+      let component = componentMap.get(item.type);
+      if (component?.loader) {
+        try {
+          item.loaderData = await component.loader({
+            data: { ...generateDataFromSchema(component.schema), ...item.data },
+            weaverse: resolvedWeaverse,
+            context: resolvedContext,
+            commerce: resolvedCommerce
+          });
+        } catch (error) {
+          console.warn("\u274C Item loader run failed.", item.type, item.id, error);
+        }
+      }
+      let children = item.children;
+      if (Array.isArray(children)) {
+        let inlineChildren = children.filter(
+          isItemNode
+        );
+        if (inlineChildren.length) {
+          await walk(inlineChildren);
+        }
+      }
+    }
+  }
+  await walk(items);
+  return data;
+}
+
+// src/request-info.ts
+function toUrl(value) {
+  return typeof value === "string" ? new URL(value, "http://localhost") : value;
+}
+function getSearchParamsFromContext(context) {
+  if (context?.searchParams) {
+    return new URLSearchParams(context.searchParams);
+  }
+  if (context?.url) {
+    let url = toUrl(context.url);
+    return new URLSearchParams(url.searchParams);
+  }
+  return new URLSearchParams();
+}
+function getPathnameFromContext(context) {
+  if (context?.pathname) {
+    return context.pathname;
+  }
+  if (context?.url) {
+    let url = toUrl(context.url);
+    return url.pathname || "/";
+  }
+  return "/";
+}
+function coerceQueryValue(value) {
+  if (value === "true") {
+    return true;
+  }
+  if (value === "false") {
+    return false;
+  }
+  return value;
+}
+function toQueryRecord(searchParams) {
+  let queries = {};
+  for (let [key, value] of searchParams.entries()) {
+    queries[key] = coerceQueryValue(value);
+  }
+  return queries;
+}
+function buildWeaverseNextRequestInfo(context) {
+  let searchParams = getSearchParamsFromContext(context);
+  let search = searchParams.toString();
+  return {
+    pathname: getPathnameFromContext(context),
+    search: search ? `?${search}` : "",
+    queries: toQueryRecord(searchParams),
+    ...context?.i18n ? { i18n: context.i18n } : {}
+  };
+}
+
+export { buildWeaverseNextRequestInfo, generateDataFromSchema, runWeaverseComponentLoaders };
+//# sourceMappingURL=chunk-SS6QUKYY.mjs.map
+//# sourceMappingURL=chunk-SS6QUKYY.mjs.map

package/dist/chunk-SS6QUKYY.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/loader.ts","../src/request-info.ts"],"names":[],"mappings":"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","file":"chunk-SS6QUKYY.mjs","sourcesContent":["import type { SchemaType } from '@weaverse/schema'\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 | 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\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 = getSearchParamsFromContext(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"]}

package/dist/index.d.mts

@@ -1,163 +1,11 @@
-import { WeaverseElement, WeaverseResourcePickerData } from '@weaverse/react';
+import { Weaverse } 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 { 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 * 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 +35,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;
 
@@ -262,4 +111,140 @@ 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 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;
+    translationMap: Record<string, unknown>;
+    translationLocale: string;
+    translationLanguageId: string;
+    constructor(config: WeaverseNextRuntimeConfig);
+    extractTranslationSidecar: () => undefined;
+    setTranslationSidecar: (map?: Record<string, unknown>, locale?: string, languageId?: string) => void;
+    updateTranslation: () => undefined;
+    getTranslationChanges: () => undefined;
+}
+declare function createWeaverseNextRuntime(config: WeaverseNextRuntimeConfig): WeaverseNextRuntime;
+declare function bindWeaverseNextStudioRuntime(runtime: WeaverseNextRuntime): boolean;
+
+interface WeaverseNextStudioBridgeProps {
+    navigate?: WeaverseNextRuntimeInternal['navigate'];
+    revalidate?: WeaverseNextRuntimeInternal['revalidate'];
+    runtime: WeaverseNextRuntime;
+}
+/** Page-level Studio runtime binder. */
+declare function WeaverseNextStudioBridge(props: WeaverseNextStudioBridgeProps): null;
+
+interface WeaverseNextStudioConnectProps {
+    context?: WeaverseNextRequestContext;
+    storefrontHostname?: string;
+}
+/** Root-level Studio script connector for Next client boundaries. */
+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.
+ */
+declare function resolveWeaverseNextStudioScriptSrc(context?: WeaverseNextRequestContext, options?: ResolveWeaverseNextStudioScriptSrcOptions): string | null;
+
+interface CreateWeaverseNextThemeSettingsStoreOptions {
+    publicEnv?: Record<string, string | undefined>;
+    schema?: unknown;
+    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 {
+    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;
+
+export { type CreateWeaverseNextStudioInternalsOptions, type CreateWeaverseNextThemeSettingsStoreOptions, type ResolveWeaverseNextStudioScriptSrcOptions, type RunComponentLoadersArgs, WeaverseNextClient, WeaverseNextClientConfig, WeaverseNextCommerceContext, WeaverseNextLoaderData, WeaverseNextProvider, type WeaverseNextProviderProps, WeaverseNextRenderer, type WeaverseNextRendererProps, WeaverseNextRequestContext, WeaverseNextRequestInfo, type WeaverseNextRouterLike, WeaverseNextRuntime, WeaverseNextRuntimeConfig, WeaverseNextRuntimeInternal, WeaverseNextStudio, WeaverseNextStudioBridge, type WeaverseNextStudioBridgeProps, WeaverseNextStudioConnect, type WeaverseNextStudioConnectProps, type WeaverseNextStudioInternals, type WeaverseNextStudioProps, WeaverseNextThemeSettingsStore, bindWeaverseNextStudioRuntime, buildWeaverseNextRequestInfo, createWeaverseNextClient, createWeaverseNextRuntime, createWeaverseNextStudioInternals, createWeaverseNextThemeSettingsStore, resolveWeaverseNextStudioScriptSrc, runWeaverseComponentLoaders, useThemeSettings, useWeaverseCommerce, useWeaverseNextStudioInternals, useWeaversePageData, useWeaverseRootData };