@kotao/storefront 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kotao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @kotao/storefront
+
+Framework-agnostic theme SDK runtime for Kotao Storefronts (ADR-0003). It mirrors Hydrogen's
+API so a Hydrogen → Kotao migration is largely mechanical, and papers over the four Cloudflare
+Workers-for-Platforms untrusted-mode realities (no `request.cf`, no `caches.default`, no `eval`,
+frozen intra-request clock).
+
+## API mapping
+
+| Hydrogen                                 | Kotao                                                    | Notes                                                             |
+| ---------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------- |
+| `createStorefrontClient`                 | `createStorefrontClient`                                 | typed GraphQL; SWR-cached `query`, uncached `mutate`              |
+| `createWithCache`                        | `createWithCache`                                        | SWR caching for third-party data                                  |
+| `CacheShort` / `CacheLong` / `CacheNone` | `CacheShort` / `CacheLong` / `CacheNone` / `CacheCustom` | plus `StorefrontDefaultCache` (fresh 1s / serve ~1 day)           |
+| `createHydrogenContext`                  | `createKotaoContext`                                     | storefront + geo + cache + locale + session seam                  |
+| Oxygen `request.cf`                      | `context.geo`                                            | backed by signed `x-kotao-*` headers; `null` if unsigned/tampered |
+| (Oxygen-managed)                         | `@kotao/storefront/react-router`                         | RR7 `getKotaoLoadContext`                                         |
+
+The one real migration diff is `request.cf` → `context.geo`.
+
+## Entry points
+
+- `@kotao/storefront` — framework-agnostic core (no React Router import).
+- `@kotao/storefront/react-router` — the React Router 7 binding (`getKotaoLoadContext`).
+
+## Signed geo contract
+
+`signGeo` (used by the Gateway Worker, #81) and `verifyGeo` (used here) live together so the
+`x-kotao-geo` / `x-kotao-geo-signature` HMAC-SHA256 contract can never drift. The signing key is
+`env.STOREFRONT_GEO_SIGNING_KEY`. Any missing/invalid signature yields `null` — unsigned data is
+never trusted.
+
+Status: #79 ships the core runtime. The Storefront API GraphQL schema + typed codegen, cart,
+SEO, analytics, and customer-account surfaces are tracked as separate issues.

package/dist/cart-documents-CwwRTvm8.d.ts

@@ -0,0 +1,21 @@
+import { CartAdapter } from '@kotao/smart-cart';
+
+/**
+ * All fully-resolved cart GraphQL document strings from the react seam adapter.
+ * Exported for schema-validation tests (apps/storefront-api/test/cart-graphql-documents.test.ts)
+ * that submit each document to a real graphql-yoga instance and assert zero validation errors,
+ * catching invalid field selections (e.g. subfields on a scalar) at test time rather than runtime.
+ */
+declare const REACT_SEAM_CART_DOCUMENTS: readonly string[];
+/**
+ * A CartAdapter that drives the storefront-api cart over the same-origin /api/storefront GraphQL proxy
+ * (the proxy injects the read token + resolves the shop server-side). The theme supplies the cart id
+ * (from its loader's cart cookie/session) and renders <CartDrawerOverlay adapter={this} />.
+ */
+declare function createStorefrontApiCartAdapter(opts: {
+    readonly cartId: string;
+    readonly apiPath?: string;
+    readonly fetchImpl?: typeof fetch;
+}): CartAdapter;
+
+export { REACT_SEAM_CART_DOCUMENTS as R, createStorefrontApiCartAdapter as c };

package/dist/cart-documents.d.ts

@@ -0,0 +1,2 @@
+export { R as REACT_SEAM_CART_DOCUMENTS } from './cart-documents-CwwRTvm8.js';
+import '@kotao/smart-cart';

package/dist/cart-documents.js

@@ -0,0 +1,3 @@
+export { REACT_SEAM_CART_DOCUMENTS } from './chunk-2IWNUDSZ.js';
+//# sourceMappingURL=cart-documents.js.map
+//# sourceMappingURL=cart-documents.js.map

package/dist/cart-documents.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"cart-documents.js"}

package/dist/chunk-2IWNUDSZ.js

@@ -0,0 +1,104 @@
+// src/react/storefront-cart-adapter.ts
+var toMinorUnits = (m) => Math.round(parseFloat(m.amount) * 100);
+var CART_FIELDS = `
+  checkoutUrl
+  cost { subtotalAmount { amount currencyCode } discountTotal { amount currencyCode } }
+  discountCodes
+  lines(first: 250) { nodes {
+    id quantity
+    attributes { key value }
+    cost { totalAmount { amount currencyCode } }
+    merchandise { ... on ProductVariant { id title image { url } product { title } } }
+  } }`;
+var CART_QUERY = `query KotaoSmartCart($cartId: ID!) { cart(id: $cartId) { ${CART_FIELDS} } }`;
+var LINES_ADD = `mutation KotaoSmartCartAdd($cartId: ID!, $lines: [CartLineInput!]!) { cartLinesAdd(cartId: $cartId, lines: $lines) { cart { ${CART_FIELDS} } } }`;
+var LINES_UPDATE = `mutation KotaoSmartCartUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) { cartLinesUpdate(cartId: $cartId, lines: $lines) { cart { ${CART_FIELDS} } } }`;
+var LINES_REMOVE = `mutation KotaoSmartCartRemove($cartId: ID!, $lineIds: [ID!]!) { cartLinesRemove(cartId: $cartId, lineIds: $lineIds) { cart { ${CART_FIELDS} } } }`;
+var DISCOUNT_CODES_UPDATE = `mutation KotaoSmartCartDiscountCodes($cartId: ID!, $discountCodes: [String!]!) { cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) { cart { ${CART_FIELDS} } } }`;
+var REACT_SEAM_CART_DOCUMENTS = [
+  CART_QUERY,
+  LINES_ADD,
+  LINES_UPDATE,
+  LINES_REMOVE,
+  DISCOUNT_CODES_UPDATE
+];
+function mapCart(c) {
+  const currency = c.cost.subtotalAmount.currencyCode;
+  const lines = c.lines.nodes.map((l) => {
+    const attributes = {};
+    for (const a of l.attributes ?? []) {
+      if (a.value !== null) attributes[a.key] = a.value;
+    }
+    const hasAttributes = Object.keys(attributes).length > 0;
+    return {
+      id: l.id,
+      title: l.merchandise.product.title,
+      variantTitle: l.merchandise.title,
+      variantId: l.merchandise.id ?? null,
+      quantity: l.quantity,
+      imageUrl: l.merchandise.image?.url ?? null,
+      linePrice: { amount: toMinorUnits(l.cost.totalAmount), currency },
+      ...hasAttributes && { attributes }
+    };
+  });
+  const discountMinorUnits = c.cost.discountTotal != null ? toMinorUnits(c.cost.discountTotal) : 0;
+  const appliedCodes = c.discountCodes?.filter((code) => code.length > 0);
+  return {
+    lines,
+    subtotal: { amount: toMinorUnits(c.cost.subtotalAmount), currency },
+    checkoutUrl: c.checkoutUrl,
+    currency,
+    ...discountMinorUnits > 0 && {
+      discountTotal: { amount: discountMinorUnits, currency }
+    },
+    ...appliedCodes != null && appliedCodes.length > 0 && { appliedCodes }
+  };
+}
+function createStorefrontApiCartAdapter(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const apiPath = opts.apiPath ?? "/api/storefront";
+  const run = async (query, variables, key) => {
+    const res = await fetchImpl(apiPath, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ query, variables })
+    });
+    if (!res.ok) {
+      throw new Error(`storefront cart request failed: ${res.status} ${res.statusText}`);
+    }
+    const json = await res.json();
+    const payload = json.data?.[key];
+    const cart = payload && "cart" in payload ? payload.cart : payload;
+    return mapCart(cart);
+  };
+  return {
+    getCart: () => run(CART_QUERY, { cartId: opts.cartId }, "cart"),
+    addLine: (merchandiseId, quantity, attributes) => run(
+      LINES_ADD,
+      {
+        cartId: opts.cartId,
+        lines: [
+          {
+            merchandiseId,
+            quantity,
+            ...attributes !== void 0 && {
+              attributes: Object.entries(attributes).map(([key, value]) => ({ key, value }))
+            }
+          }
+        ]
+      },
+      "cartLinesAdd"
+    ),
+    updateLine: (id, quantity) => run(LINES_UPDATE, { cartId: opts.cartId, lines: [{ id, quantity }] }, "cartLinesUpdate"),
+    removeLine: (id) => run(LINES_REMOVE, { cartId: opts.cartId, lineIds: [id] }, "cartLinesRemove"),
+    updateDiscountCodes: (codes) => run(
+      DISCOUNT_CODES_UPDATE,
+      { cartId: opts.cartId, discountCodes: codes },
+      "cartDiscountCodesUpdate"
+    )
+  };
+}
+
+export { REACT_SEAM_CART_DOCUMENTS, createStorefrontApiCartAdapter };
+//# sourceMappingURL=chunk-2IWNUDSZ.js.map
+//# sourceMappingURL=chunk-2IWNUDSZ.js.map

package/dist/chunk-2IWNUDSZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/storefront-cart-adapter.ts"],"names":[],"mappings":"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","file":"chunk-2IWNUDSZ.js","sourcesContent":["import type { CartAdapter, SmartCartLine, SmartCartState } from '@kotao/smart-cart'\n\ninterface GqlMoney {\n  amount: string\n  currencyCode: string\n}\ninterface GqlCartLine {\n  id: string\n  quantity: number\n  attributes: { key: string; value: string | null }[] | null\n  cost: { totalAmount: GqlMoney }\n  merchandise: {\n    id: string\n    title: string | null\n    image: { url: string } | null\n    product: { title: string }\n  }\n}\ninterface GqlCart {\n  checkoutUrl: string\n  cost: { subtotalAmount: GqlMoney; discountTotal?: GqlMoney }\n  discountCodes?: string[]\n  lines: { nodes: GqlCartLine[] }\n}\n\n// GraphQL Money is a decimal string (\"216.00\"); SmartCartState money is integer minor units.\nconst toMinorUnits = (m: GqlMoney): number => Math.round(parseFloat(m.amount) * 100)\n\nconst CART_FIELDS = `\n  checkoutUrl\n  cost { subtotalAmount { amount currencyCode } discountTotal { amount currencyCode } }\n  discountCodes\n  lines(first: 250) { nodes {\n    id quantity\n    attributes { key value }\n    cost { totalAmount { amount currencyCode } }\n    merchandise { ... on ProductVariant { id title image { url } product { title } } }\n  } }`\nconst CART_QUERY = `query KotaoSmartCart($cartId: ID!) { cart(id: $cartId) { ${CART_FIELDS} } }`\nconst LINES_ADD = `mutation KotaoSmartCartAdd($cartId: ID!, $lines: [CartLineInput!]!) { cartLinesAdd(cartId: $cartId, lines: $lines) { cart { ${CART_FIELDS} } } }`\nconst LINES_UPDATE = `mutation KotaoSmartCartUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) { cartLinesUpdate(cartId: $cartId, lines: $lines) { cart { ${CART_FIELDS} } } }`\nconst LINES_REMOVE = `mutation KotaoSmartCartRemove($cartId: ID!, $lineIds: [ID!]!) { cartLinesRemove(cartId: $cartId, lineIds: $lineIds) { cart { ${CART_FIELDS} } } }`\nconst DISCOUNT_CODES_UPDATE = `mutation KotaoSmartCartDiscountCodes($cartId: ID!, $discountCodes: [String!]!) { cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) { cart { ${CART_FIELDS} } } }`\n\n/**\n * All fully-resolved cart GraphQL document strings from the react seam adapter.\n * Exported for schema-validation tests (apps/storefront-api/test/cart-graphql-documents.test.ts)\n * that submit each document to a real graphql-yoga instance and assert zero validation errors,\n * catching invalid field selections (e.g. subfields on a scalar) at test time rather than runtime.\n */\nexport const REACT_SEAM_CART_DOCUMENTS: readonly string[] = [\n  CART_QUERY,\n  LINES_ADD,\n  LINES_UPDATE,\n  LINES_REMOVE,\n  DISCOUNT_CODES_UPDATE,\n]\n\nfunction mapCart(c: GqlCart): SmartCartState {\n  const currency = c.cost.subtotalAmount.currencyCode\n  const lines: SmartCartLine[] = c.lines.nodes.map((l) => {\n    const attributes: Record<string, string> = {}\n    for (const a of l.attributes ?? []) {\n      if (a.value !== null) attributes[a.key] = a.value\n    }\n    const hasAttributes = Object.keys(attributes).length > 0\n    return {\n      id: l.id,\n      title: l.merchandise.product.title,\n      variantTitle: l.merchandise.title,\n      variantId: l.merchandise.id ?? null,\n      quantity: l.quantity,\n      imageUrl: l.merchandise.image?.url ?? null,\n      linePrice: { amount: toMinorUnits(l.cost.totalAmount), currency },\n      ...(hasAttributes && { attributes }),\n    }\n  })\n  const discountMinorUnits = c.cost.discountTotal != null ? toMinorUnits(c.cost.discountTotal) : 0\n  const appliedCodes = c.discountCodes?.filter((code) => code.length > 0)\n  return {\n    lines,\n    subtotal: { amount: toMinorUnits(c.cost.subtotalAmount), currency },\n    checkoutUrl: c.checkoutUrl,\n    currency,\n    ...(discountMinorUnits > 0 && {\n      discountTotal: { amount: discountMinorUnits, currency },\n    }),\n    ...(appliedCodes != null && appliedCodes.length > 0 && { appliedCodes }),\n  }\n}\n\n/**\n * A CartAdapter that drives the storefront-api cart over the same-origin /api/storefront GraphQL proxy\n * (the proxy injects the read token + resolves the shop server-side). The theme supplies the cart id\n * (from its loader's cart cookie/session) and renders <CartDrawerOverlay adapter={this} />.\n */\nexport function createStorefrontApiCartAdapter(opts: {\n  readonly cartId: string\n  readonly apiPath?: string\n  readonly fetchImpl?: typeof fetch\n}): CartAdapter {\n  const fetchImpl = opts.fetchImpl ?? fetch\n  const apiPath = opts.apiPath ?? '/api/storefront'\n  const run = async (\n    query: string,\n    variables: Record<string, unknown>,\n    key: string,\n  ): Promise<SmartCartState> => {\n    const res = await fetchImpl(apiPath, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', accept: 'application/json' },\n      body: JSON.stringify({ query, variables }),\n    })\n    if (!res.ok) {\n      throw new Error(`storefront cart request failed: ${res.status} ${res.statusText}`)\n    }\n    const json = (await res.json()) as { data?: Record<string, unknown> }\n    const payload = json.data?.[key] as GqlCart | { cart: GqlCart } | undefined\n    const cart = payload && 'cart' in payload ? payload.cart : (payload as GqlCart)\n    return mapCart(cart)\n  }\n  return {\n    getCart: () => run(CART_QUERY, { cartId: opts.cartId }, 'cart'),\n    addLine: (merchandiseId, quantity, attributes) =>\n      run(\n        LINES_ADD,\n        {\n          cartId: opts.cartId,\n          lines: [\n            {\n              merchandiseId,\n              quantity,\n              ...(attributes !== undefined && {\n                attributes: Object.entries(attributes).map(([key, value]) => ({ key, value })),\n              }),\n            },\n          ],\n        },\n        'cartLinesAdd',\n      ),\n    updateLine: (id, quantity) =>\n      run(LINES_UPDATE, { cartId: opts.cartId, lines: [{ id, quantity }] }, 'cartLinesUpdate'),\n    removeLine: (id) =>\n      run(LINES_REMOVE, { cartId: opts.cartId, lineIds: [id] }, 'cartLinesRemove'),\n    updateDiscountCodes: (codes) =>\n      run(\n        DISCOUNT_CODES_UPDATE,\n        { cartId: opts.cartId, discountCodes: codes },\n        'cartDiscountCodesUpdate',\n      ),\n  }\n}\n"]}

package/dist/chunk-3YQXJNR7.js

@@ -0,0 +1,70 @@
+// src/image/image-url.ts
+var CDN_CGI = "/cdn-cgi/image/";
+var isCdnUrl = (url) => /^https?:\/\/cdn\.kotao\./.test(url);
+function splitCdnCgi(url) {
+  const u = new URL(url);
+  if (!u.pathname.startsWith(CDN_CGI)) return { bare: url, opts: new URLSearchParams() };
+  const rest = u.pathname.slice(CDN_CGI.length);
+  const slash = rest.indexOf("/");
+  const optStr = slash === -1 ? rest : rest.slice(0, slash);
+  const path = slash === -1 ? "" : rest.slice(slash);
+  const opts = new URLSearchParams();
+  for (const pair of optStr.split(",")) {
+    const [k, v] = pair.split("=");
+    if (k && v) opts.set(k, v);
+  }
+  return { bare: `${u.origin}${path}`, opts };
+}
+var OPT_ORDER = ["width", "height", "fit", "format", "quality"];
+function imageUrl(url, options = {}) {
+  if (!isCdnUrl(url)) return url;
+  const { bare, opts } = splitCdnCgi(url);
+  if (options.width != null) opts.set("width", String(options.width));
+  if (options.height != null) opts.set("height", String(options.height));
+  if (options.fit != null) opts.set("fit", options.fit);
+  if (options.format != null) opts.set("format", options.format);
+  if (options.quality != null) opts.set("quality", String(options.quality));
+  const ordered = OPT_ORDER.filter((k) => opts.has(k)).map((k) => `${k}=${opts.get(k)}`);
+  if (ordered.length === 0) return bare;
+  const u = new URL(bare);
+  return `${u.origin}${CDN_CGI}${ordered.join(",")}${u.pathname}`;
+}
+function imageSrcSet(url, options) {
+  const { widths, ...rest } = options;
+  return widths.map((width) => `${imageUrl(url, { ...rest, width })} ${width}w`).join(", ");
+}
+
+// src/image/image-attrs.ts
+var DEFAULT_WIDTHS = [320, 640, 768, 1024, 1280, 1536];
+var FALLBACK_WIDTH = 1280;
+function buildImageAttrs(options) {
+  const url = options.src ?? options.data.url;
+  const widths = options.srcSetWidths ?? (options.width ? [options.width, options.width * 2, options.width * 3] : DEFAULT_WIDTHS);
+  const aspectRatio = options.aspectRatio ?? (options.data.width != null && options.data.height != null ? `${options.data.width}/${options.data.height}` : void 0);
+  const transform = {};
+  if (options.crop) transform.fit = "cover";
+  if (options.format != null) transform.format = options.format;
+  if (options.quality != null) transform.quality = options.quality;
+  const heightPerWidth = options.width != null && options.height != null ? options.height / options.width : null;
+  const candidate = (w) => {
+    const opts = { ...transform, width: w };
+    if (heightPerWidth != null) opts.height = Math.round(w * heightPerWidth);
+    return opts;
+  };
+  const srcOptions = { ...transform, width: options.width ?? FALLBACK_WIDTH };
+  if (options.height != null) srcOptions.height = options.height;
+  return {
+    src: imageUrl(url, srcOptions),
+    srcSet: widths.map((w) => `${imageUrl(url, candidate(w))} ${w}w`).join(", "),
+    ...options.sizes != null ? { sizes: options.sizes } : {},
+    ...options.width != null ? { width: options.width } : {},
+    ...options.height != null ? { height: options.height } : {},
+    alt: options.data.altText ?? "",
+    loading: options.loading ?? "lazy",
+    ...aspectRatio != null ? { style: { aspectRatio } } : {}
+  };
+}
+
+export { buildImageAttrs, imageSrcSet, imageUrl };
+//# sourceMappingURL=chunk-3YQXJNR7.js.map
+//# sourceMappingURL=chunk-3YQXJNR7.js.map

package/dist/chunk-3YQXJNR7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/image/image-url.ts","../src/image/image-attrs.ts"],"names":[],"mappings":"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","file":"chunk-3YQXJNR7.js","sourcesContent":["/**\n * Framework-agnostic image-URL builders for the storefront SDK (ADR-0003 §SDK image-URL contract).\n * They build Cloudflare `/cdn-cgi/image/<opts>/<path>` path-form transform URLs for `https://cdn.kotao.*`\n * bases, allowing the CDN to serve optimized renderings. Non-CDN URLs (external, data:, theme `/assets/...`)\n * pass through unchanged. Wire-native params — `width`/`height`/`fit`/`format`/`quality` — matching\n * Cloudflare's native image resizing; a Hydrogen-shaped React `<Image>` (with `crop`, `srcSet`/`sizes`\n * props) layers on top in the framework presets (#92). Pure string building, no framework imports, so it\n * stays in the SDK core.\n */\n\n/** Cloudflare-native resize mode (the Gateway's `fit` param). */\nexport type ImageFit = 'scale-down' | 'contain' | 'pad' | 'squeeze' | 'cover' | 'crop'\n/** Output format query value (the Gateway maps it to a content-type). */\nexport type ImageFormat = 'webp' | 'avif' | 'jpeg' | 'png'\n\nexport interface ImageUrlOptions {\n  width?: number\n  height?: number\n  fit?: ImageFit\n  format?: ImageFormat\n  /** 1–100. */\n  quality?: number\n}\n\nconst CDN_CGI = '/cdn-cgi/image/'\nconst isCdnUrl = (url: string): boolean => /^https?:\\/\\/cdn\\.kotao\\./.test(url)\n\n/** Strip a `/cdn-cgi/image/<opts>/` segment back to `{origin}{path}`, returning [bareUrl, existingOpts]. */\nfunction splitCdnCgi(url: string): { bare: string; opts: URLSearchParams } {\n  const u = new URL(url)\n  if (!u.pathname.startsWith(CDN_CGI)) return { bare: url, opts: new URLSearchParams() }\n  const rest = u.pathname.slice(CDN_CGI.length)\n  const slash = rest.indexOf('/')\n  const optStr = slash === -1 ? rest : rest.slice(0, slash)\n  const path = slash === -1 ? '' : rest.slice(slash) // includes leading '/'\n  const opts = new URLSearchParams()\n  for (const pair of optStr.split(',')) {\n    const [k, v] = pair.split('=')\n    if (k && v) opts.set(k, v)\n  }\n  return { bare: `${u.origin}${path}`, opts }\n}\n\nconst OPT_ORDER = ['width', 'height', 'fit', 'format', 'quality'] as const\n\n/**\n * Build a Cloudflare `/cdn-cgi/image/` path-form transform URL for a CDN image. For transformable\n * URLs (absolute `https://cdn.kotao.*`), emits `/cdn-cgi/image/{opts}/{path}` where `{opts}` is\n * the comma-joined key=value list (in stable order: width,height,fit,format,quality) and `{path}`\n * is the original pathname. Chaining replaces any existing `/cdn-cgi/image/` segment.\n * Non-CDN URLs pass through unchanged.\n */\nexport function imageUrl(url: string, options: ImageUrlOptions = {}): string {\n  if (!isCdnUrl(url)) return url\n  const { bare, opts } = splitCdnCgi(url)\n  if (options.width != null) opts.set('width', String(options.width))\n  if (options.height != null) opts.set('height', String(options.height))\n  if (options.fit != null) opts.set('fit', options.fit)\n  if (options.format != null) opts.set('format', options.format)\n  if (options.quality != null) opts.set('quality', String(options.quality))\n  const ordered = OPT_ORDER.filter((k) => opts.has(k)).map((k) => `${k}=${opts.get(k)}`)\n  if (ordered.length === 0) return bare\n  const u = new URL(bare)\n  return `${u.origin}${CDN_CGI}${ordered.join(',')}${u.pathname}`\n}\n\nexport interface ImageSrcSetOptions extends Omit<ImageUrlOptions, 'width'> {\n  /** Candidate widths (px) for the `srcset` descriptors. */\n  widths: number[]\n}\n\n/**\n * Build a `srcset` string — one `url width` candidate per width — for responsive `<img srcset>` /\n * `<source srcset>`. Pair with a `sizes` attribute the theme controls.\n */\nexport function imageSrcSet(url: string, options: ImageSrcSetOptions): string {\n  const { widths, ...rest } = options\n  return widths.map((width) => `${imageUrl(url, { ...rest, width })} ${width}w`).join(', ')\n}\n","/**\n * Framework-agnostic `<img>` attribute builder (ADR-0003 §SDK image-URL contract). Turns the\n * Hydrogen-shaped `<Image>` surface (data/aspectRatio/crop/sizes/width/height) into concrete img\n * attributes (src, srcSet, sizes, width, height, style) over the `cdn.kotao.*` R2-native transform\n * contract, via the pure `imageUrl`/`imageSrcSet` builders. The React `<Image>` is a thin wrapper\n * that spreads these — so all logic lives here, in the core, unit-tested without a DOM.\n */\nimport { imageUrl, type ImageFormat, type ImageUrlOptions } from './image-url'\n\nexport interface ImageData {\n  url: string\n  altText?: string | null\n  width?: number | null\n  height?: number | null\n}\n\n/** Hydrogen crop region. v1 maps any crop to a fill+crop (Cloudflare `fit=cover`); positional gravity\n * (top/bottom/left/right) is not on the wire yet, so all values currently centre-crop. */\nexport type ImageCrop = 'center' | 'top' | 'bottom' | 'left' | 'right'\n\n// Optionals are `| undefined` on purpose: the React <Image> feeds them straight from optional props,\n// so explicit `undefined` must be assignable under exactOptionalPropertyTypes.\nexport interface ImageAttrsOptions {\n  data: ImageData\n  /** Override `data.url`. */\n  src?: string | undefined\n  /** \"width/height\" (e.g. \"4/5\") — sets the intrinsic box for CLS-free layout. */\n  aspectRatio?: string | undefined\n  crop?: ImageCrop | undefined\n  /** The responsive `sizes` attribute; the theme owns it. */\n  sizes?: string | undefined\n  /** Fixed render width (px). With it, the srcSet becomes 1x/2x/3x instead of the responsive set. */\n  width?: number | undefined\n  height?: number | undefined\n  loading?: ('eager' | 'lazy') | undefined\n  /** srcSet candidate widths; defaults to a responsive set (or 1x/2x/3x when `width` is fixed). */\n  srcSetWidths?: number[] | undefined\n  format?: ImageFormat | undefined\n  quality?: number | undefined\n}\n\nexport interface ImageAttrs {\n  src: string\n  srcSet: string\n  sizes?: string\n  width?: number\n  height?: number\n  alt: string\n  loading: 'eager' | 'lazy'\n  style?: { aspectRatio: string }\n}\n\n/** Responsive widths when no fixed `width` is given (mirrors Hydrogen's default interval set). */\nconst DEFAULT_WIDTHS = [320, 640, 768, 1024, 1280, 1536]\n/** The `src` fallback width for browsers that ignore srcSet. */\nconst FALLBACK_WIDTH = 1280\n\nexport function buildImageAttrs(options: ImageAttrsOptions): ImageAttrs {\n  const url = options.src ?? options.data.url\n\n  const widths =\n    options.srcSetWidths ??\n    (options.width ? [options.width, options.width * 2, options.width * 3] : DEFAULT_WIDTHS)\n\n  const aspectRatio =\n    options.aspectRatio ??\n    (options.data.width != null && options.data.height != null\n      ? `${options.data.width}/${options.data.height}`\n      : undefined)\n\n  // Shared transform params — set only when present (exactOptionalPropertyTypes forbids explicit\n  // `undefined`). A crop maps to Cloudflare `fit=cover` (fill+crop).\n  const transform: ImageUrlOptions = {}\n  if (options.crop) transform.fit = 'cover'\n  if (options.format != null) transform.format = options.format\n  if (options.quality != null) transform.quality = options.quality\n\n  // For a fixed box (width+height), the srcSet candidates must scale BOTH dimensions so every DPR\n  // variant keeps the same crop aspect (a uniform height would distort the 2x/3x candidates).\n  const heightPerWidth =\n    options.width != null && options.height != null ? options.height / options.width : null\n  const candidate = (w: number): ImageUrlOptions => {\n    const opts: ImageUrlOptions = { ...transform, width: w }\n    if (heightPerWidth != null) opts.height = Math.round(w * heightPerWidth)\n    return opts\n  }\n\n  const srcOptions: ImageUrlOptions = { ...transform, width: options.width ?? FALLBACK_WIDTH }\n  if (options.height != null) srcOptions.height = options.height\n\n  return {\n    src: imageUrl(url, srcOptions),\n    srcSet: widths.map((w) => `${imageUrl(url, candidate(w))} ${w}w`).join(', '),\n    ...(options.sizes != null ? { sizes: options.sizes } : {}),\n    ...(options.width != null ? { width: options.width } : {}),\n    ...(options.height != null ? { height: options.height } : {}),\n    alt: options.data.altText ?? '',\n    loading: options.loading ?? 'lazy',\n    ...(aspectRatio != null ? { style: { aspectRatio } } : {}),\n  }\n}\n"]}

package/dist/chunk-5QOFKGKD.js

@@ -0,0 +1,51 @@
+// src/pagination/pagination.ts
+function flattenConnection(connection) {
+  if (connection == null) return [];
+  if (connection.nodes != null) return [...connection.nodes];
+  return (connection.edges ?? []).flatMap((edge) => {
+    const node = edge?.node;
+    return node == null ? [] : [node];
+  });
+}
+var paramNames = (namespace) => {
+  const prefix = namespace ? `${namespace}_` : "";
+  return { direction: `${prefix}direction`, cursor: `${prefix}cursor` };
+};
+var toSearchParams = (input) => {
+  if (input instanceof URLSearchParams) return input;
+  if (input instanceof URL) return input.searchParams;
+  if (typeof input === "string") return new URL(input).searchParams;
+  return new URL(input.url).searchParams;
+};
+function getPaginationVariables(input, options) {
+  const pageSize = options.pageSize ?? options.pageBy ?? 20;
+  const params = toSearchParams(input);
+  const names = paramNames(options.namespace);
+  const direction = params.get(names.direction);
+  const cursor = params.get(names.cursor);
+  if (cursor && direction === "previous") return { last: pageSize, startCursor: cursor };
+  if (cursor && direction === "next") return { first: pageSize, endCursor: cursor };
+  return { first: pageSize };
+}
+var pageUrl = (current, names, direction, cursor) => {
+  const url = new URL(current.toString());
+  url.searchParams.set(names.direction, direction);
+  url.searchParams.set(names.cursor, cursor);
+  return url.toString();
+};
+function getPaginationInfo(connection, currentUrl, options = {}) {
+  const url = typeof currentUrl === "string" ? new URL(currentUrl) : currentUrl;
+  const names = paramNames(options.namespace);
+  const { pageInfo } = connection;
+  return {
+    nodes: connection.nodes,
+    hasNextPage: pageInfo.hasNextPage,
+    hasPreviousPage: pageInfo.hasPreviousPage,
+    ...pageInfo.hasNextPage && pageInfo.endCursor ? { nextPageUrl: pageUrl(url, names, "next", pageInfo.endCursor) } : {},
+    ...pageInfo.hasPreviousPage && pageInfo.startCursor ? { prevPageUrl: pageUrl(url, names, "previous", pageInfo.startCursor) } : {}
+  };
+}
+
+export { flattenConnection, getPaginationInfo, getPaginationVariables };
+//# sourceMappingURL=chunk-5QOFKGKD.js.map
+//# sourceMappingURL=chunk-5QOFKGKD.js.map

package/dist/chunk-5QOFKGKD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pagination/pagination.ts"],"names":[],"mappings":";AAuDO,SAAS,kBACd,UAAA,EACW;AACX,EAAA,IAAI,UAAA,IAAc,IAAA,EAAM,OAAO,EAAC;AAChC,EAAA,IAAI,WAAW,KAAA,IAAS,IAAA,SAAa,CAAC,GAAG,WAAW,KAAK,CAAA;AACzD,EAAA,OAAA,CAAQ,WAAW,KAAA,IAAS,EAAC,EAAG,OAAA,CAAQ,CAAC,IAAA,KAAS;AAChD,IAAA,MAAM,OAAO,IAAA,EAAM,IAAA;AACnB,IAAA,OAAO,IAAA,IAAQ,IAAA,GAAO,EAAC,GAAI,CAAC,IAAI,CAAA;AAAA,EAClC,CAAC,CAAA;AACH;AAiBA,IAAM,UAAA,GAAa,CAAC,SAAA,KAA8D;AAChF,EAAA,MAAM,MAAA,GAAS,SAAA,GAAY,CAAA,EAAG,SAAS,CAAA,CAAA,CAAA,GAAM,EAAA;AAC7C,EAAA,OAAO,EAAE,WAAW,CAAA,EAAG,MAAM,aAAa,MAAA,EAAQ,CAAA,EAAG,MAAM,CAAA,MAAA,CAAA,EAAS;AACtE,CAAA;AAEA,IAAM,cAAA,GAAiB,CAAC,KAAA,KAAqE;AAC3F,EAAA,IAAI,KAAA,YAAiB,iBAAiB,OAAO,KAAA;AAC7C,EAAA,IAAI,KAAA,YAAiB,GAAA,EAAK,OAAO,KAAA,CAAM,YAAA;AACvC,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,SAAiB,IAAI,GAAA,CAAI,KAAK,CAAA,CAAE,YAAA;AACrD,EAAA,OAAO,IAAI,GAAA,CAAI,KAAA,CAAM,GAAG,CAAA,CAAE,YAAA;AAC5B,CAAA;AAMO,SAAS,sBAAA,CACd,OACA,OAAA,EACqB;AACrB,EAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,QAAA,IAAY,OAAA,CAAQ,MAAA,IAAU,EAAA;AACvD,EAAA,MAAM,MAAA,GAAS,eAAe,KAAK,CAAA;AACnC,EAAA,MAAM,KAAA,GAAQ,UAAA,CAAW,OAAA,CAAQ,SAAS,CAAA;AAC1C,EAAA,MAAM,SAAA,GAAY,MAAA,CAAO,GAAA,CAAI,KAAA,CAAM,SAAS,CAAA;AAC5C,EAAA,MAAM,MAAA,GAAS,MAAA,CAAO,GAAA,CAAI,KAAA,CAAM,MAAM,CAAA;AACtC,EAAA,IAAI,MAAA,IAAU,cAAc,UAAA,EAAY,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,aAAa,MAAA,EAAO;AACrF,EAAA,IAAI,MAAA,IAAU,cAAc,MAAA,EAAQ,OAAO,EAAE,KAAA,EAAO,QAAA,EAAU,WAAW,MAAA,EAAO;AAChF,EAAA,OAAO,EAAE,OAAO,QAAA,EAAS;AAC3B;AAYA,IAAM,OAAA,GAAU,CACd,OAAA,EACA,KAAA,EACA,WACA,MAAA,KACW;AACX,EAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,OAAA,CAAQ,UAAU,CAAA;AACtC,EAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,KAAA,CAAM,SAAA,EAAW,SAAS,CAAA;AAC/C,EAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,KAAA,CAAM,MAAA,EAAQ,MAAM,CAAA;AACzC,EAAA,OAAO,IAAI,QAAA,EAAS;AACtB,CAAA;AAMO,SAAS,iBAAA,CACd,UAAA,EACA,UAAA,EACA,OAAA,GAAkC,EAAC,EAChB;AACnB,EAAA,MAAM,MAAM,OAAO,UAAA,KAAe,WAAW,IAAI,GAAA,CAAI,UAAU,CAAA,GAAI,UAAA;AACnE,EAAA,MAAM,KAAA,GAAQ,UAAA,CAAW,OAAA,CAAQ,SAAS,CAAA;AAC1C,EAAA,MAAM,EAAE,UAAS,GAAI,UAAA;AACrB,EAAA,OAAO;AAAA,IACL,OAAO,UAAA,CAAW,KAAA;AAAA,IAClB,aAAa,QAAA,CAAS,WAAA;AAAA,IACtB,iBAAiB,QAAA,CAAS,eAAA;AAAA,IAC1B,GAAI,QAAA,CAAS,WAAA,IAAe,QAAA,CAAS,YACjC,EAAE,WAAA,EAAa,OAAA,CAAQ,GAAA,EAAK,OAAO,MAAA,EAAQ,QAAA,CAAS,SAAS,CAAA,KAC7D,EAAC;AAAA,IACL,GAAI,QAAA,CAAS,eAAA,IAAmB,QAAA,CAAS,cACrC,EAAE,WAAA,EAAa,OAAA,CAAQ,GAAA,EAAK,OAAO,UAAA,EAAY,QAAA,CAAS,WAAW,CAAA,KACnE;AAAC,GACP;AACF","file":"chunk-5QOFKGKD.js","sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/**\n * Framework-agnostic cursor pagination (ADR-0003 §SDK). Mirrors Shopify Hydrogen's\n * `getPaginationVariables` + `<Pagination>` over a relay-style connection\n * (`{ nodes, pageInfo { hasNextPage, hasPreviousPage, startCursor, endCursor } }`). Generic over the\n * connection's node type, so it works with any Storefront API connection (today: `Cart.lines`).\n *\n * Pure logic, no React — the React `<Pagination>` render-props component is a thin wrapper.\n */\n\n/** Relay PageInfo as the Storefront API emits it. */\nexport interface PageInfo {\n  readonly hasNextPage: boolean\n  readonly hasPreviousPage: boolean\n  readonly startCursor?: string | null\n  readonly endCursor?: string | null\n}\n\nexport interface Connection<T> {\n  readonly nodes: readonly T[]\n  readonly pageInfo: PageInfo\n}\n\nexport interface ConnectionEdge<T> {\n  readonly node?: T | null\n}\n\nexport interface FlattenableConnection<T> {\n  readonly nodes?: T[] | readonly T[] | null\n  readonly edges?: readonly (ConnectionEdge<T> | null)[] | null\n}\n\ntype IsAny<T> = 0 extends 1 & T ? true : false\n\ntype NodeFromConnection<C> =\n  IsAny<C> extends true\n    ? any\n    : C extends { readonly nodes?: readonly (infer Node)[] | null }\n      ? Node\n      : C extends { readonly edges?: readonly (infer Edge | null)[] | null }\n        ? Edge extends { readonly node?: infer Node | null }\n          ? NonNullable<Node>\n          : unknown\n        : unknown\n\n/**\n * Hydrogen-compatible connection flattener. Shopify code often accepts either Storefront API\n * `nodes` connections or Relay `edges[].node` connections; migrated routes can keep that shape.\n */\nexport function flattenConnection(connection: null | undefined): []\nexport function flattenConnection<T>(connection: FlattenableConnection<T>): T[]\nexport function flattenConnection<C extends FlattenableConnection<unknown>>(\n  connection: C | null | undefined,\n): NodeFromConnection<C>[]\nexport function flattenConnection(\n  connection: FlattenableConnection<unknown> | null | undefined,\n): unknown[] {\n  if (connection == null) return []\n  if (connection.nodes != null) return [...connection.nodes]\n  return (connection.edges ?? []).flatMap((edge) => {\n    const node = edge?.node\n    return node == null ? [] : [node]\n  })\n}\n\n/** The query variables a connection field takes for forward/backward paging. */\nexport interface PaginationVariables {\n  first?: number\n  last?: number\n  startCursor?: string\n  endCursor?: string\n}\n\nexport interface PaginationOptions {\n  pageSize?: number\n  pageBy?: number\n  /** Isolates the URL params when multiple paginations share a page (`{ns}_direction`/`{ns}_cursor`). */\n  namespace?: string\n}\n\nconst paramNames = (namespace?: string): { direction: string; cursor: string } => {\n  const prefix = namespace ? `${namespace}_` : ''\n  return { direction: `${prefix}direction`, cursor: `${prefix}cursor` }\n}\n\nconst toSearchParams = (input: URL | Request | URLSearchParams | string): URLSearchParams => {\n  if (input instanceof URLSearchParams) return input\n  if (input instanceof URL) return input.searchParams\n  if (typeof input === 'string') return new URL(input).searchParams\n  return new URL(input.url).searchParams\n}\n\n/**\n * Read `direction`/`cursor` from the request URL and return the connection variables for the page:\n * forward → `{ first, endCursor }`, backward → `{ last, startCursor }`, no params → `{ first }`.\n */\nexport function getPaginationVariables(\n  input: URL | Request | URLSearchParams | string,\n  options: PaginationOptions,\n): PaginationVariables {\n  const pageSize = options.pageSize ?? options.pageBy ?? 20\n  const params = toSearchParams(input)\n  const names = paramNames(options.namespace)\n  const direction = params.get(names.direction)\n  const cursor = params.get(names.cursor)\n  if (cursor && direction === 'previous') return { last: pageSize, startCursor: cursor }\n  if (cursor && direction === 'next') return { first: pageSize, endCursor: cursor }\n  return { first: pageSize }\n}\n\nexport interface PaginationInfo<T> {\n  readonly nodes: readonly T[]\n  readonly hasNextPage: boolean\n  readonly hasPreviousPage: boolean\n  /** Same-page URL with `direction=next` + the end cursor; absent when there is no next page. */\n  readonly nextPageUrl: string\n  /** Same-page URL with `direction=previous` + the start cursor; absent when there is no previous page. */\n  readonly prevPageUrl: string\n}\n\nconst pageUrl = (\n  current: URL,\n  names: { direction: string; cursor: string },\n  direction: 'next' | 'previous',\n  cursor: string,\n): string => {\n  const url = new URL(current.toString())\n  url.searchParams.set(names.direction, direction)\n  url.searchParams.set(names.cursor, cursor)\n  return url.toString()\n}\n\n/**\n * Decorate a connection with the current page's nodes + the next/previous page URLs (built from the\n * current URL + the connection's cursors). A theme renders links to `nextPageUrl`/`prevPageUrl`.\n */\nexport function getPaginationInfo<T>(\n  connection: Connection<T>,\n  currentUrl: URL | string,\n  options: { namespace?: string } = {},\n): PaginationInfo<T> {\n  const url = typeof currentUrl === 'string' ? new URL(currentUrl) : currentUrl\n  const names = paramNames(options.namespace)\n  const { pageInfo } = connection\n  return {\n    nodes: connection.nodes,\n    hasNextPage: pageInfo.hasNextPage,\n    hasPreviousPage: pageInfo.hasPreviousPage,\n    ...(pageInfo.hasNextPage && pageInfo.endCursor\n      ? { nextPageUrl: pageUrl(url, names, 'next', pageInfo.endCursor) }\n      : {}),\n    ...(pageInfo.hasPreviousPage && pageInfo.startCursor\n      ? { prevPageUrl: pageUrl(url, names, 'previous', pageInfo.startCursor) }\n      : {}),\n  } as PaginationInfo<T>\n}\n"]}

package/dist/chunk-GCQI6OKH.js

@@ -0,0 +1,239 @@
+// src/settings/merge.ts
+function mergeSettings(inputs, stored, preset) {
+  const out = {};
+  for (const input of inputs) {
+    const storedValue = stored?.[input.name];
+    const presetValue = preset?.[input.name];
+    out[input.name] = storedValue !== void 0 ? storedValue : presetValue !== void 0 ? presetValue : input.defaultValue;
+  }
+  return out;
+}
+function mergeSection(args) {
+  const settings = mergeSettings(
+    args.schema.settings,
+    args.instance?.settings,
+    args.preset?.settings
+  );
+  if (args.instance?.settings.disabled === true) settings.disabled = true;
+  const blockDefs = new Map((args.schema.blocks ?? []).map((b) => [b.type, b]));
+  const blocks = (args.instance?.blocks ?? []).map((b) => ({
+    ...b.id !== void 0 ? { id: b.id } : {},
+    type: b.type,
+    settings: mergeSettings(blockDefs.get(b.type)?.settings ?? [], b.settings, void 0)
+  }));
+  return { id: args.instance?.id ?? "", type: args.schema.type, settings, blocks };
+}
+function resolveValuesDocument(args, values) {
+  const sections = values.sections.map((instance) => {
+    const schema = args.schemas[instance.type];
+    if (schema === void 0) {
+      return {
+        id: instance.id,
+        type: instance.type,
+        settings: instance.settings,
+        blocks: instance.blocks.map((b) => ({
+          ...b.id !== void 0 ? { id: b.id } : {},
+          type: b.type,
+          settings: b.settings
+        }))
+      };
+    }
+    const preset = args.presets?.[instance.type];
+    return mergeSection({ schema, instance, ...preset !== void 0 ? { preset } : {} });
+  });
+  return { shopId: values.shopId, sections };
+}
+function resolveDocumentRecord(args, documents) {
+  if (documents === void 0) return void 0;
+  const resolved = {};
+  for (const [handle, document] of Object.entries(documents)) {
+    if (document !== void 0) resolved[handle] = resolveValuesDocument(args, document);
+  }
+  return resolved;
+}
+function resolveThemeSettings(args) {
+  const root = resolveValuesDocument(args, args.values);
+  const global = mergeSettings(args.globalInputs ?? [], args.globalStored, args.globalPreset);
+  const templates = resolveDocumentRecord(args, args.templates);
+  const sectionGroups = resolveDocumentRecord(args, args.sectionGroups);
+  return {
+    sections: root.sections,
+    global,
+    ...templates !== void 0 ? { templates } : {},
+    ...sectionGroups !== void 0 ? { sectionGroups } : {}
+  };
+}
+
+// src/settings/store.ts
+function createThemeSettingsStore(initial) {
+  let snapshot = initial;
+  const listeners = /* @__PURE__ */ new Set();
+  const clampIndex = (index, length) => {
+    if (index === void 0 || Number.isNaN(index)) return length;
+    return Math.max(0, Math.min(Math.trunc(index), length));
+  };
+  const emit = () => {
+    for (const listener of listeners) listener();
+  };
+  const updateSection = (sectionId, update) => {
+    if (sectionId.startsWith("theme:")) return false;
+    let changed = false;
+    const sections = snapshot.sections.map((section) => {
+      if (section.id !== sectionId) return section;
+      const next = update(section);
+      if (next === null || next === section) return section;
+      changed = true;
+      return next;
+    });
+    if (!changed) return false;
+    snapshot = { ...snapshot, sections };
+    emit();
+    return true;
+  };
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    patchSection: (instanceId, settings) => {
+      if (instanceId.startsWith("theme:")) return;
+      let changed = false;
+      const sections = snapshot.sections.map((section) => {
+        if (section.id !== instanceId) return section;
+        changed = true;
+        return { ...section, settings };
+      });
+      if (!changed) return;
+      snapshot = { ...snapshot, sections };
+      emit();
+    },
+    insertSection: (section, index) => {
+      if (section.id.startsWith("theme:")) return;
+      if (snapshot.sections.some((existing) => existing.id === section.id)) return;
+      const next = [...snapshot.sections];
+      next.splice(clampIndex(index, next.length), 0, section);
+      snapshot = { ...snapshot, sections: next };
+      emit();
+    },
+    removeSection: (instanceId) => {
+      if (instanceId.startsWith("theme:")) return;
+      const sections = snapshot.sections.filter((section) => section.id !== instanceId);
+      if (sections.length === snapshot.sections.length) return;
+      snapshot = { ...snapshot, sections };
+      emit();
+    },
+    moveSection: (instanceId, index) => {
+      if (instanceId.startsWith("theme:")) return;
+      const fromIndex = snapshot.sections.findIndex((section2) => section2.id === instanceId);
+      if (fromIndex === -1) return;
+      const next = [...snapshot.sections];
+      const [section] = next.splice(fromIndex, 1);
+      if (section === void 0) return;
+      const toIndex = clampIndex(index, next.length);
+      if (fromIndex === toIndex) return;
+      next.splice(toIndex, 0, section);
+      snapshot = { ...snapshot, sections: next };
+      emit();
+    },
+    patchGlobal: (settings) => {
+      if (settings === snapshot.global) return;
+      snapshot = { ...snapshot, global: settings };
+      emit();
+    },
+    patchBlock: (sectionId, blockId, settings) => {
+      updateSection(sectionId, (section) => {
+        let changed = false;
+        const blocks = section.blocks.map((block) => {
+          if (block.id !== blockId) return block;
+          changed = true;
+          return { ...block, settings };
+        });
+        return changed ? { ...section, blocks } : null;
+      });
+    },
+    insertBlock: (sectionId, block, index) => {
+      updateSection(sectionId, (section) => {
+        if (block.id !== void 0 && section.blocks.some((existing) => existing.id === block.id)) {
+          return null;
+        }
+        const blocks = [...section.blocks];
+        blocks.splice(clampIndex(index, blocks.length), 0, block);
+        return { ...section, blocks };
+      });
+    },
+    removeBlock: (sectionId, blockId) => {
+      updateSection(sectionId, (section) => {
+        const blocks = section.blocks.filter((block) => block.id !== blockId);
+        return blocks.length === section.blocks.length ? null : { ...section, blocks };
+      });
+    },
+    moveBlock: (sectionId, blockId, index) => {
+      updateSection(sectionId, (section) => {
+        const fromIndex = section.blocks.findIndex((block2) => block2.id === blockId);
+        if (fromIndex === -1) return null;
+        const blocks = [...section.blocks];
+        const [block] = blocks.splice(fromIndex, 1);
+        if (block === void 0) return null;
+        const toIndex = clampIndex(index, blocks.length);
+        if (fromIndex === toIndex) return null;
+        blocks.splice(toIndex, 0, block);
+        return { ...section, blocks };
+      });
+    },
+    replaceSections: (sections) => {
+      const next = sections.filter((section) => !section.id.startsWith("theme:"));
+      if (next.length === snapshot.sections.length && next.every((section, index) => section === snapshot.sections[index])) {
+        return;
+      }
+      snapshot = { ...snapshot, sections: next };
+      emit();
+    },
+    replaceSectionGroup: (handle, document) => {
+      if (handle.trim() === "") return;
+      const sectionGroups = snapshot.sectionGroups ?? {};
+      const nextDocument = {
+        ...document,
+        sections: document.sections.filter((section) => !section.id.startsWith("theme:"))
+      };
+      if (sectionGroups[handle] === nextDocument) return;
+      snapshot = {
+        ...snapshot,
+        sectionGroups: {
+          ...sectionGroups,
+          [handle]: nextDocument
+        }
+      };
+      emit();
+    }
+  };
+}
+
+// src/settings/fetch.ts
+var SAME_ORIGIN_PATH = /^\/(?![/\\])/;
+var HTTPS_ENDPOINT = /^https:\/\//;
+var DEFAULT_ENDPOINT = "/api/storefront/settings";
+async function fetchThemeSettings(options = {}) {
+  const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+  if (!SAME_ORIGIN_PATH.test(endpoint) && !(options.allowCrossOrigin === true && HTTPS_ENDPOINT.test(endpoint))) {
+    throw new Error(`theme-settings endpoint must be a same-origin path, got '${endpoint}'`);
+  }
+  const doFetch = options.fetch ?? fetch;
+  const headers = {};
+  if (options.auth !== void 0) {
+    headers[options.auth.tokenHeader ?? "x-kotao-storefront-token"] = options.auth.token;
+    if (options.auth.siteId !== void 0 && options.auth.siteId.trim().length > 0) {
+      headers["x-kotao-site-id"] = options.auth.siteId;
+    }
+  }
+  const init = Object.keys(headers).length > 0 ? { headers } : void 0;
+  const res = await doFetch(endpoint, init);
+  if (!res.ok) throw new Error(`theme settings fetch failed: HTTP ${res.status}`);
+  return await res.json();
+}
+
+export { createThemeSettingsStore, fetchThemeSettings, mergeSection, mergeSettings, resolveThemeSettings };
+//# sourceMappingURL=chunk-GCQI6OKH.js.map
+//# sourceMappingURL=chunk-GCQI6OKH.js.map