@usethrottle/builder-react 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/next.js CHANGED
@@ -1,16 +1,24 @@
1
1
  import {
2
+ __publicField,
3
+ buildRouteTable,
4
+ canonicalFor,
2
5
  clientOf,
3
6
  getBundle,
7
+ isOwnPath,
4
8
  isRedirect,
5
9
  loadBuilderPage,
6
- metadataOf
7
- } from "./chunk-SYXZO5H2.js";
10
+ loadBuilderPageByPath,
11
+ loadBuilderTemplate,
12
+ metadataOf,
13
+ templateMetadataOf,
14
+ templateRootOf
15
+ } from "./chunk-G6I4RIXU.js";
8
16
 
9
17
  // src/next/index.ts
10
- import { createElement } from "react";
11
- import { notFound, permanentRedirect } from "next/navigation";
12
- import { BuilderNotFoundError, BuilderUnavailableError } from "@usethrottle/builder";
13
- import { BuilderPageView } from "@usethrottle/builder-react";
18
+ import { createElement as createElement2 } from "react";
19
+ import { notFound as notFound2, permanentRedirect as permanentRedirect2 } from "next/navigation";
20
+ import { BuilderNotFoundError as BuilderNotFoundError2, BuilderUnavailableError as BuilderUnavailableError3 } from "@usethrottle/builder";
21
+ import { BuilderPageView as BuilderPageView2 } from "@usethrottle/builder-react";
14
22
 
15
23
  // src/safe-path.ts
16
24
  import { safeUrl } from "@usethrottle/builder-schema";
@@ -31,18 +39,374 @@ function sitePath(to) {
31
39
  return safeUrl(to, "href", { mediaOrigin: "" });
32
40
  }
33
41
 
42
+ // src/next/route.tsx
43
+ import * as React from "react";
44
+ import { notFound, permanentRedirect, redirect } from "next/navigation";
45
+ import { BuilderNotFoundError, BuilderUnavailableError } from "@usethrottle/builder";
46
+ import { CATALOG_TEMPLATES, PAGE_PATH_RE, matchRedirect } from "@usethrottle/builder-schema";
47
+ import {
48
+ BuilderPageView,
49
+ BuilderRouteScope,
50
+ BuilderTemplateView
51
+ } from "@usethrottle/builder-react";
52
+ import { jsx, jsxs } from "react/jsx-runtime";
53
+ var DEFAULT_CATALOG_TEMPLATE_PATHS = {
54
+ shop: "/shop",
55
+ collection: "/collections/{handle}",
56
+ category: "/c/{handle}",
57
+ tag: "/tags/{tag}",
58
+ search: "/search",
59
+ product: "/p/{handle}"
60
+ };
61
+ var DEFAULT_STORE_TEMPLATE_PATHS = {
62
+ cart: "/cart",
63
+ account: "/account",
64
+ "account-verify": "/account/verify",
65
+ "sign-in": "/sign-in",
66
+ "sign-up": "/sign-up",
67
+ "order-complete": "/order/complete"
68
+ };
69
+ var BuilderUnavailablePageError = class extends Error {
70
+ constructor(template) {
71
+ super(`The ${template} template cannot be served: its data source is unavailable`);
72
+ this.template = template;
73
+ __publicField(this, "name", "BuilderUnavailablePageError");
74
+ }
75
+ };
76
+ var isRec = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
77
+ var isNamed = (error, name) => typeof error === "object" && error !== null && error.name === name;
78
+ var isNotFound = (error) => error instanceof BuilderNotFoundError || isNamed(error, "BuilderNotFoundError");
79
+ var isUnavailable = (error) => error instanceof BuilderUnavailableError || isNamed(error, "BuilderUnavailableError");
80
+ var isNavigation = (error) => {
81
+ const digest = isRec(error) ? error.digest : void 0;
82
+ return typeof digest === "string" && /^NEXT_(HTTP_ERROR_FALLBACK|NOT_FOUND|REDIRECT)/.test(digest);
83
+ };
84
+ var cache2 = React.cache ?? ((fn) => fn);
85
+ function pathOf(options, params) {
86
+ const value = params[options.pathParam ?? "path"];
87
+ const segments = value === void 0 ? [] : Array.isArray(value) ? value : [value];
88
+ try {
89
+ const path = `/${segments.map((segment) => decodeURIComponent(segment)).join("/")}`;
90
+ return path.includes("\0") ? null : path;
91
+ } catch {
92
+ return null;
93
+ }
94
+ }
95
+ function matchTemplate(template, path) {
96
+ if (!template.startsWith("/")) return null;
97
+ const names = [];
98
+ const pattern = template.split(/(\{[A-Za-z][A-Za-z0-9]*\})/).map((part) => {
99
+ const named = /^\{([A-Za-z][A-Za-z0-9]*)\}$/.exec(part);
100
+ if (named === null) return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
101
+ names.push(named[1]);
102
+ return "([^/]+)";
103
+ }).join("").replace(/\/+$/, "");
104
+ const match = new RegExp(`^${pattern === "" ? "/" : pattern}$`).exec(
105
+ path.length > 1 ? path.replace(/\/+$/, "") : path
106
+ );
107
+ return match === null ? null : Object.fromEntries(names.map((name, i) => [name, match[i + 1]]));
108
+ }
109
+ function redirectRows(settings) {
110
+ const seo = isRec(settings.seo) ? settings.seo : {};
111
+ if (!Array.isArray(seo.redirects)) return [];
112
+ return seo.redirects.flatMap((row) => {
113
+ if (!isRec(row) || typeof row.from !== "string" || typeof row.to !== "string") return [];
114
+ return [
115
+ { from: row.from, to: row.to, status: typeof row.status === "number" ? row.status : 308 }
116
+ ];
117
+ });
118
+ }
119
+ function redirectFor(settings, path) {
120
+ const row = matchRedirect(path, redirectRows(settings));
121
+ if (row === null) return null;
122
+ const to = sitePath(row.to) ?? (/^https?:\/\/[^\s\\]+$/iu.test(row.to) ? row.to : null);
123
+ if (to === null) return null;
124
+ return { kind: "redirect", to, permanent: row.status === 301 || row.status === 308 };
125
+ }
126
+ function storeRoutesOf(settings, config) {
127
+ const routes = isRec(settings.routes) ? settings.routes : {};
128
+ const store = isRec(routes.store) ? routes.store : {};
129
+ const own = Object.fromEntries(
130
+ Object.entries(store).filter(([, value]) => typeof value === "string")
131
+ );
132
+ return { ...DEFAULT_STORE_TEMPLATE_PATHS, ...config.storeRoutes, ...own };
133
+ }
134
+ function createBuilderRoute(options) {
135
+ const packs = options.packs;
136
+ function loaderFor(name) {
137
+ const own = options.loaders?.[name];
138
+ if (own !== void 0) return own;
139
+ for (const pack of packs) {
140
+ const found = pack.templates?.find((template) => template.name === name);
141
+ if (found !== void 0) return found.loader;
142
+ }
143
+ return void 0;
144
+ }
145
+ async function localeOf2(params) {
146
+ if (typeof options.locale === "function") return options.locale(params);
147
+ if (options.locale !== void 0) return options.locale;
148
+ return typeof params.locale === "string" ? params.locale : "en";
149
+ }
150
+ async function resolve(path, locale, currency) {
151
+ const client = clientOf(options);
152
+ const bundle = await getBundle({ client, locale, slots: options.slots });
153
+ const settings = bundle.site.settings;
154
+ const read = {
155
+ client: options.client,
156
+ builderKey: options.builderKey,
157
+ locale,
158
+ packs,
159
+ slots: options.slots,
160
+ ...currency === void 0 ? {} : { currency }
161
+ };
162
+ const moved = redirectFor(settings, path);
163
+ if (moved !== null) return moved;
164
+ const catalogOn = bundle.site.catalogInstalled !== false;
165
+ const catalog = { ...DEFAULT_CATALOG_TEMPLATE_PATHS, ...options.catalogRoutes };
166
+ const store = storeRoutesOf(settings, options);
167
+ const all = { ...catalog, ...store };
168
+ const served = Object.entries(all).filter(
169
+ ([name]) => catalogOn || !CATALOG_TEMPLATES.includes(name)
170
+ );
171
+ const matched = served.flatMap(([name, template]) => {
172
+ const params = matchTemplate(template, path);
173
+ return params === null ? [] : [{ name, params }];
174
+ })[0];
175
+ const routeTable = buildRouteTable(store, catalog);
176
+ if (path === "/") {
177
+ try {
178
+ const home = await loadBuilderPage({ ...read, slug: "home" });
179
+ if (home.kind === "redirect") return redirectTo(home.redirectTo);
180
+ return { kind: "page", slug: "home", page: home, path, own: false };
181
+ } catch (error) {
182
+ if (!isNotFound(error)) throw error;
183
+ }
184
+ }
185
+ const pageRoute = isRec(settings.routes) && typeof settings.routes.page === "string" ? settings.routes.page : "/pages/{handle}";
186
+ const handle = matchTemplate(pageRoute, path)?.handle;
187
+ if (matched === void 0 && handle === void 0 && path !== "/" && PAGE_PATH_RE.test(path)) {
188
+ try {
189
+ const found = await loadBuilderPageByPath({ ...read, path });
190
+ if (found.kind === "redirect") return redirectTo(found.redirectTo);
191
+ return { kind: "page", slug: found.slug, page: found, path, own: true };
192
+ } catch (error) {
193
+ if (!isNotFound(error)) throw error;
194
+ }
195
+ }
196
+ if (handle !== void 0) {
197
+ try {
198
+ const found = await loadBuilderPage({ ...read, slug: handle });
199
+ if (found.kind === "redirect") return redirectTo(found.redirectTo);
200
+ if (isOwnPath(found.path)) return { kind: "redirect", to: found.path, permanent: true };
201
+ return { kind: "page", slug: handle, page: found, path, own: false };
202
+ } catch (error) {
203
+ if (!isNotFound(error)) throw error;
204
+ }
205
+ }
206
+ if (matched === void 0) return { kind: "notFound" };
207
+ return { kind: "matched", name: matched.name, params: matched.params, routeTable, path };
208
+ }
209
+ async function finish(matched, queryJson, locale, currency) {
210
+ const { name, path, routeTable } = matched;
211
+ const query = JSON.parse(queryJson);
212
+ const bundle = await getBundle({ client: clientOf(options), locale, slots: options.slots });
213
+ const read = {
214
+ client: options.client,
215
+ builderKey: options.builderKey,
216
+ locale,
217
+ packs,
218
+ slots: options.slots,
219
+ ...currency === void 0 ? {} : { currency }
220
+ };
221
+ const route = { path, params: matched.params, query };
222
+ const loader = loaderFor(name);
223
+ if (loader === void 0 && CATALOG_TEMPLATES.includes(name))
224
+ return { kind: "notFound" };
225
+ const loaded = await runLoader(loader, { ...matched.params }, query, route);
226
+ if (loaded.status === "not-found") return { kind: "notFound" };
227
+ if (loaded.status === "redirect") return redirectTo(loaded.to);
228
+ const unavailable = loaded.status === "unavailable";
229
+ const context = unavailable ? { route, unavailable: true } : loaded.context;
230
+ const shared = {
231
+ ...bundle.savedSections === void 0 ? {} : { savedSections: bundle.savedSections },
232
+ ...bundle.code === void 0 ? {} : { code: bundle.code }
233
+ };
234
+ try {
235
+ const { part, meta } = await loadBuilderTemplate({ ...read, name, shared });
236
+ return { kind: "template", name, part, context, meta, routeTable, path, unavailable };
237
+ } catch (error) {
238
+ const contribution = packs.flatMap((pack) => pack.templates ?? []).find((entry) => entry.name === name);
239
+ if (!isUnavailable(error) || contribution === void 0) throw error;
240
+ const sections = contribution.defaultComposition();
241
+ const part = {
242
+ document: { schemaVersion: 1, sections },
243
+ assets: {},
244
+ initialData: {}
245
+ };
246
+ return {
247
+ kind: "template",
248
+ name,
249
+ part,
250
+ context,
251
+ meta: void 0,
252
+ routeTable,
253
+ path,
254
+ unavailable
255
+ };
256
+ }
257
+ }
258
+ function redirectTo(to) {
259
+ const path = sitePath(to) ?? (/^https?:\/\/[^\s\\]+$/iu.test(to) ? to : null);
260
+ return path === null ? { kind: "notFound" } : { kind: "redirect", to: path, permanent: true };
261
+ }
262
+ async function runLoader(loader, params, query, route) {
263
+ if (loader === void 0) return { status: "ok", context: { route } };
264
+ try {
265
+ return await loader({ params, searchParams: query, route });
266
+ } catch (error) {
267
+ if (isUnavailable(error)) return { status: "unavailable" };
268
+ throw error;
269
+ }
270
+ }
271
+ const resolveCached = cache2(resolve);
272
+ const finishCached = cache2(finish);
273
+ async function request(props) {
274
+ const params = await props.params;
275
+ const path = pathOf(options, params);
276
+ const locale = await localeOf2(params);
277
+ const currency = typeof options.currency === "function" ? await options.currency(params) : options.currency;
278
+ const first = path === null ? { kind: "notFound" } : await resolveCached(path, locale, currency);
279
+ let query = {};
280
+ let resolved;
281
+ if (first.kind === "matched") {
282
+ const searchParams = await props.searchParams ?? {};
283
+ query = Object.fromEntries(
284
+ Object.entries(searchParams).filter(([, value]) => value !== void 0)
285
+ );
286
+ resolved = await finishCached(first, JSON.stringify(query), locale, currency);
287
+ } else resolved = first;
288
+ const search = new URLSearchParams(
289
+ Object.entries(query).flatMap(
290
+ ([key, value]) => (Array.isArray(value) ? value : [value]).map((v) => [key, v])
291
+ )
292
+ ).toString();
293
+ return { resolved, params, locale, search: search === "" ? "" : `?${search}` };
294
+ }
295
+ function templateBody(resolved) {
296
+ const view = /* @__PURE__ */ jsx(BuilderTemplateView, { name: resolved.name, part: resolved.part, context: resolved.context });
297
+ const Root = templateRootOf(packs, resolved.name);
298
+ if (Root === void 0) return view;
299
+ return /* @__PURE__ */ jsx(Root, { context: resolved.context, document: resolved.part.document, children: view });
300
+ }
301
+ async function Page(props) {
302
+ const { resolved } = await request(props);
303
+ switch (resolved.kind) {
304
+ case "redirect":
305
+ return resolved.permanent ? permanentRedirect(resolved.to) : redirect(resolved.to);
306
+ case "notFound":
307
+ return notFound();
308
+ case "page":
309
+ return /* @__PURE__ */ jsx(BuilderRouteScope, { ...resolved.own ? { allowPath: resolved.path } : {}, children: /* @__PURE__ */ jsx(BuilderPageView, { page: resolved.page }) });
310
+ case "template":
311
+ if (resolved.unavailable) {
312
+ if (options.unavailable === "error") throw new BuilderUnavailablePageError(resolved.name);
313
+ options.onUnavailable?.({
314
+ status: 503,
315
+ headers: { "Retry-After": String(options.retryAfterSeconds ?? 30) }
316
+ });
317
+ return /* @__PURE__ */ jsxs(BuilderRouteScope, { templateName: resolved.name, routeTable: resolved.routeTable, children: [
318
+ /* @__PURE__ */ jsx("meta", { name: "robots", content: "noindex" }),
319
+ templateBody(resolved)
320
+ ] });
321
+ }
322
+ return /* @__PURE__ */ jsx(BuilderRouteScope, { templateName: resolved.name, routeTable: resolved.routeTable, children: templateBody(resolved) });
323
+ }
324
+ }
325
+ async function generateMetadata(props) {
326
+ const client = clientOf(options);
327
+ try {
328
+ const { resolved, params, locale, search } = await request(props);
329
+ if (resolved.kind === "redirect" || resolved.kind === "notFound") return {};
330
+ const bundle = await getBundle({ client, locale, slots: options.slots });
331
+ const settings = bundle.site.settings;
332
+ if (resolved.kind === "page") {
333
+ const shared = await getBundle({
334
+ client,
335
+ locale,
336
+ page: resolved.slug,
337
+ slots: options.slots
338
+ });
339
+ const page = shared.page;
340
+ if (page === void 0 || "redirectTo" in page) return {};
341
+ return metadataOf(page, {
342
+ settings: shared.site.settings,
343
+ mediaOrigin: options.mediaOrigin ?? "",
344
+ storeUrl: options.storeUrl,
345
+ pagePath: options.pagePath ?? ((entry) => entry.pageType === "home" ? "/" : entry.path),
346
+ routeLocale: options.locale === void 0 && typeof params.locale === "string" ? params.locale : void 0
347
+ });
348
+ }
349
+ return templateMetadataOf(resolved.name, {
350
+ settings,
351
+ storeUrl: options.storeUrl,
352
+ mediaOrigin: options.mediaOrigin ?? "",
353
+ path: resolved.path,
354
+ search,
355
+ // An unavailable answer has no product or listing to name: the store's own title, `noindex`.
356
+ context: resolved.unavailable ? void 0 : resolved.context,
357
+ meta: resolved.meta,
358
+ ...resolved.unavailable ? { noindex: true } : {}
359
+ });
360
+ } catch (error) {
361
+ if (isNavigation(error) || isNotFound(error)) return {};
362
+ if (isUnavailable(error) && client.mode !== "build") return {};
363
+ throw error;
364
+ }
365
+ }
366
+ return { Page, generateMetadata };
367
+ }
368
+
369
+ // src/next/template.tsx
370
+ import { createElement } from "react";
371
+ import { BuilderUnavailableError as BuilderUnavailableError2 } from "@usethrottle/builder";
372
+ import { BuilderTemplateView as BuilderTemplateView2 } from "@usethrottle/builder-react";
373
+ async function BuilderTemplate({
374
+ name,
375
+ packs,
376
+ locale = "en",
377
+ context,
378
+ ...client
379
+ }) {
380
+ try {
381
+ const { part } = await loadBuilderTemplate({
382
+ ...client,
383
+ name,
384
+ locale,
385
+ ...packs === void 0 ? {} : { packs }
386
+ });
387
+ const templateContext = context ?? { route: { path: "", params: {}, query: {} } };
388
+ const view = createElement(BuilderTemplateView2, { name, part, context: templateContext });
389
+ const Root = templateRootOf(packs, name);
390
+ return Root === void 0 ? view : createElement(Root, { context: templateContext, document: part.document, children: view });
391
+ } catch (error) {
392
+ if (error instanceof BuilderUnavailableError2 || error?.name === "BuilderUnavailableError")
393
+ return null;
394
+ throw error;
395
+ }
396
+ }
397
+
34
398
  // src/next/index.ts
35
399
  function slugOf(options, params) {
36
400
  if ("slug" in options) return options.slug;
37
401
  const value = params[options.fromParams];
38
402
  const slug = Array.isArray(value) ? value.join("/") : value;
39
- if (slug === void 0 || slug === "") notFound();
403
+ if (slug === void 0 || slug === "") notFound2();
40
404
  return slug;
41
405
  }
42
406
  async function currencyOf(options, params) {
43
407
  return typeof options.currency === "function" ? options.currency(params) : options.currency;
44
408
  }
45
- var isNamed = (error, name) => typeof error === "object" && error !== null && error.name === name;
409
+ var isNamed2 = (error, name) => typeof error === "object" && error !== null && error.name === name;
46
410
  async function localeOf(options, params) {
47
411
  if (typeof options.locale === "function") return options.locale(params);
48
412
  if (options.locale !== void 0) return options.locale;
@@ -61,15 +425,15 @@ function createBuilderPage(options) {
61
425
  locale: await localeOf(options, params),
62
426
  ...currency === void 0 ? {} : { currency }
63
427
  }).catch((error) => {
64
- if (error instanceof BuilderNotFoundError || isNamed(error, "BuilderNotFoundError")) notFound();
428
+ if (error instanceof BuilderNotFoundError2 || isNamed2(error, "BuilderNotFoundError")) notFound2();
65
429
  throw error;
66
430
  });
67
431
  if (loaded.kind === "redirect") {
68
432
  const path = sitePath(loaded.redirectTo);
69
- if (path === null) notFound();
70
- permanentRedirect(path);
433
+ if (path === null) notFound2();
434
+ permanentRedirect2(path);
71
435
  }
72
- return createElement(BuilderPageView, { page: loaded });
436
+ return createElement2(BuilderPageView2, { page: loaded });
73
437
  }
74
438
  async function generateMetadata(props) {
75
439
  const params = await props.params;
@@ -88,13 +452,19 @@ function createBuilderPage(options) {
88
452
  routeLocale: options.locale === void 0 && typeof params.locale === "string" ? params.locale : void 0
89
453
  });
90
454
  } catch (error) {
91
- if (error instanceof BuilderNotFoundError || isNamed(error, "BuilderNotFoundError")) return {};
92
- if ((error instanceof BuilderUnavailableError || isNamed(error, "BuilderUnavailableError")) && client.mode !== "build") return {};
455
+ if (error instanceof BuilderNotFoundError2 || isNamed2(error, "BuilderNotFoundError")) return {};
456
+ if ((error instanceof BuilderUnavailableError3 || isNamed2(error, "BuilderUnavailableError")) && client.mode !== "build") return {};
93
457
  throw error;
94
458
  }
95
459
  }
96
460
  return { Page, generateMetadata };
97
461
  }
98
462
  export {
99
- createBuilderPage
463
+ BuilderTemplate,
464
+ BuilderUnavailablePageError,
465
+ DEFAULT_CATALOG_TEMPLATE_PATHS,
466
+ DEFAULT_STORE_TEMPLATE_PATHS,
467
+ canonicalFor,
468
+ createBuilderPage,
469
+ createBuilderRoute
100
470
  };
@@ -1,5 +1,5 @@
1
1
  import { ComponentType, ReactNode } from 'react';
2
- import { WidgetDefinition, WidgetNode, SettingValue, DataSourceDescriptor, PageDocument, FrozenAsset, SavedSectionsAnswer, CodeRuntimeAnswer } from '@usethrottle/builder-schema';
2
+ import { TemplateName, RootNode, StoreRoutes, WidgetDefinition, WidgetNode, SettingValue, DataSourceDescriptor, PageDocument, FrozenAsset, SavedSectionsAnswer, CodeRuntimeAnswer } from '@usethrottle/builder-schema';
3
3
  import { BuilderClient, BuilderBundle } from '@usethrottle/builder';
4
4
 
5
5
  /** A count of rendered nodes with a ceiling. One per custom widget render. */
@@ -19,6 +19,74 @@ declare class RenderBudget {
19
19
  */
20
20
  type Budget = Pick<RenderBudget, 'limit' | 'used' | 'exhausted' | 'take'>;
21
21
 
22
+ /** The route a template loader serves: the matched path, its dynamic params and the query string. */
23
+ type TemplateRoute = {
24
+ path: string;
25
+ params: Record<string, string>;
26
+ query: Record<string, string | string[]>;
27
+ };
28
+ /**
29
+ * What a template's widgets read (spec §5.1): the loaded catalog or shopper data of the route. Each field
30
+ * is plain data a loader resolved on the server; the owning stream (T-P, T-L, T-A) narrows its own field.
31
+ */
32
+ type TemplateContext = {
33
+ product?: unknown;
34
+ listing?: unknown;
35
+ cart?: unknown;
36
+ customer?: unknown;
37
+ route: TemplateRoute;
38
+ };
39
+ /** The answer of a template loader. */
40
+ type TemplateLoadResult = {
41
+ status: 'ok';
42
+ context: TemplateContext;
43
+ } | {
44
+ status: 'not-found';
45
+ } | {
46
+ status: 'redirect';
47
+ to: string;
48
+ } | {
49
+ status: 'unavailable';
50
+ };
51
+ /** Reads what one template needs for one request. */
52
+ type TemplateLoader = (args: {
53
+ params: Record<string, string | string[] | undefined>;
54
+ searchParams: Record<string, string | string[] | undefined>;
55
+ route: TemplateRoute;
56
+ }) => Promise<TemplateLoadResult>;
57
+ /** The sections of a document: what `PageDocument.sections` holds. */
58
+ type DocumentNodes = RootNode[];
59
+ /** What a widget pack contributes for one template: its loader and its default composition. */
60
+ type PackTemplateContribution = {
61
+ name: TemplateName;
62
+ loader: TemplateLoader;
63
+ /** The pack's default composition of the template, optionally one of its `variants`. */
64
+ defaultComposition: (variant?: string) => DocumentNodes;
65
+ variants?: string[];
66
+ /**
67
+ * A component the template body is rendered inside, once, for state its widgets share (the product page's selected
68
+ * variant, a listing's filters): `createBuilderRoute` and `BuilderTemplate` draw
69
+ * `<Root context document>{template body}</Root>`, on the server, for the loaded template, its unavailable state
70
+ * and the pack's default composition. `document` is the template's `PageDocument`. A client component reference
71
+ * is fine; it receives plain data only. Without it the body is drawn as it is.
72
+ */
73
+ Root?: ComponentType<{
74
+ context: TemplateContext;
75
+ document: unknown;
76
+ children: ReactNode;
77
+ }>;
78
+ };
79
+ /** What the store hands the template route (spec §5.1). */
80
+ type BuilderRouteConfig = {
81
+ site: LoadedSite;
82
+ packs: readonly WidgetPack[];
83
+ /** Catalog route prefixes the store serves (`shop`, `collection`, ...), by template name. */
84
+ catalogRoutes?: Partial<Record<TemplateName, string>>;
85
+ /** Paths of the store templates the merchant renamed (`routes.store`). */
86
+ storeRoutes?: Partial<StoreRoutes>;
87
+ loaders: Partial<Record<TemplateName, TemplateLoader>>;
88
+ };
89
+
22
90
  /** Resolved data by binding key (`bindingKey`), plus `context.*` entries a slot supplies. */
23
91
  type DataMap = Record<string, unknown>;
24
92
  type WidgetRenderProps = {
@@ -85,6 +153,8 @@ type WidgetPack = {
85
153
  dataSources: PackDataSource[];
86
154
  linkTargets?: LinkTargetProvider;
87
155
  slots?: SlotPoint[];
156
+ /** The templates the pack contributes: loaders and default compositions (spec §5.1). */
157
+ templates?: PackTemplateContribution[];
88
158
  };
89
159
  /** A page document as the store reads it (a published snapshot). */
90
160
  type PageAssets = Record<string, FrozenAsset>;
@@ -129,10 +199,19 @@ type LoadedSite = {
129
199
  locale: string;
130
200
  generation: number;
131
201
  siteVersion: number;
202
+ /**
203
+ * The instant `loadSite` read the site (ISO 8601, stamped on the server). Time rules (announcement schedules)
204
+ * are evaluated at this instant while rendering, so server HTML and the first client render agree.
205
+ */
206
+ loadedAt?: string;
132
207
  /** The origin media files must be on (https). Images from anywhere else are refused. */
133
208
  mediaOrigin: string;
134
209
  /** Site settings resolved for the locale (localized values are strings). */
135
210
  settings: Record<string, unknown>;
211
+ /** The site answer's `theme` (beside `settings`): `customCssHref` is the Builder's stylesheet for CSS over 4 KB. */
212
+ theme?: {
213
+ customCssHref?: string;
214
+ };
136
215
  header: LoadedPart;
137
216
  footer: LoadedPart;
138
217
  slots: Record<string, LoadedPart>;
@@ -154,6 +233,12 @@ type ClientOptions = {
154
233
  builderKey?: string | undefined;
155
234
  };
156
235
 
236
+ type CanonicalKind = 'page' | 'listing' | 'product' | 'search';
237
+ /**
238
+ * The canonical form of a URL the store is serving: no fragment, and no query except `?page` on a listing, so sort,
239
+ * filter and tracking parameters all canonicalize to the listing itself (spec §11.4: listing pages keep `?page=`).
240
+ */
241
+ declare function canonicalFor(url: string | URL, kind: CanonicalKind): string;
157
242
  /** A store's own answer for where a page lives: it gets the default and returns a site path (or null for the default). */
158
243
  type PagePathResolver = (page: {
159
244
  slug: string;
@@ -161,4 +246,4 @@ type PagePathResolver = (page: {
161
246
  path: string;
162
247
  }) => string | null | undefined;
163
248
 
164
- export { type BundleAsk as B, type ClientOptions as C, type LoadedPage as L, type PagePathResolver as P, type WidgetPack as W, type LoadedRedirect as a, type LoadedSite as b, getBundle as g };
249
+ export { type BuilderRouteConfig as B, type CanonicalKind as C, type LoadedPage as L, type PagePathResolver as P, type TemplateContext as T, type WidgetPack as W, type BundleAsk as a, type ClientOptions as b, type LoadedPart as c, type LoadedRedirect as d, type LoadedSite as e, canonicalFor as f, getBundle as g };