@zalify/storefront-kit 0.1.0

package/LICENSE.md

@@ -0,0 +1,49 @@
+# Zalify Source Available License 1.0
+
+Copyright (c) 2026 Zalify, Inc. All rights reserved.
+
+## Grant
+
+Subject to the terms below, Zalify grants you a non-exclusive,
+worldwide, non-transferable, royalty-free license to use, copy, and
+modify this software, and to deploy it as part of storefronts, websites,
+and applications that you build and operate for yourself or for your
+clients.
+
+Code scaffolded into your project by Zalify tooling (for example by
+`create-zalify-theme`) may be modified without restriction and remains
+governed by this license as part of your project.
+
+## Limitations
+
+You may not:
+
+1. Redistribute, sublicense, sell, or publish this software or
+   substantial portions of it — on its own or as part of a template,
+   starter, theme, SDK, or similar developer product;
+2. Use this software to build a product or service that competes with
+   Zalify, including theme marketplaces, storefront builders, or visual
+   editors;
+3. Remove or alter copyright, license, or attribution notices;
+4. Use Zalify's names, logos, or trademarks except to describe your
+   permitted use of the software.
+
+Running the storefronts you build with this software — including
+hosting them commercially for yourself or your clients — is expressly
+permitted and is not "competing with Zalify."
+
+## Termination
+
+This license terminates automatically if you violate its terms. Upon
+termination you must stop distributing the software, but storefronts
+already deployed under a compliant use may continue to operate.
+
+## Disclaimer
+
+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 ZALIFY 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,63 @@
+# @zalify/storefront-kit
+
+The Zalify storefront SDK: everything shared between Zalify storefronts,
+shipped as one versioned package. Scaffold a storefront with
+[`create-zalify-theme`](https://www.npmjs.com/package/create-zalify-theme)
+and upgrade this package to pull in new engine features, sections, and
+blocks — your customizations live in your project, not in a fork
+(the same model as the Shopify Hydrogen SDK).
+
+```sh
+pnpm create zalify-theme@latest
+```
+
+## Subpath exports
+
+| Import | What's inside |
+| --- | --- |
+| `@zalify/storefront-kit/commerce` | Framework-agnostic commerce logic: money & unit-price formatting, the cart event-bus contract, countdown math, the facets URL codec, Storefront-API product helpers. Pure TypeScript — no DOM, no React. |
+| `@zalify/storefront-kit/schemas` | The theme contract: Shopify OS 2.0-aligned theme JSON data types (templates, sections, blocks), section/block schema types, the editor manifest format, the canvas-editor bridge protocol, and validators for all of them. |
+| `@zalify/storefront-kit/editor` | The canvas-editor bridge — postMessage runtime for editing a running storefront across origins. `/editor/frame` mounts inside the storefront preview (selection hit-testing, highlights, optimistic template apply); `/editor/host` drives the preview iframe from the editor. |
+| `@zalify/storefront-kit/react` | The theme engine + shared React components: `installTheme`, `<ThemeTemplate>`/`<SectionGroup>` renderers, the settings→CSS pipeline, built-in section/block registries, and components like `ProductCard`, `Price`, `Facets`. |
+| `@zalify/storefront-kit/react/server` | Server side of the section engine: per-section-type data loaders (`loadSectionData`, `builtinSectionLoaders`) for route loaders / server components. |
+
+React is an **optional** peer dependency — only the `/react` subpaths
+need it (a Liquid theme consuming `/commerce` installs nothing else).
+
+## How an app uses the engine
+
+```tsx
+// 1. Register the theme once at startup, merging the built-in
+//    sections/blocks with your app-local ones:
+import {installTheme, builtinSections, builtinBlocks} from '@zalify/storefront-kit/react';
+installTheme({
+  schema,                                        // your theme's JSON data
+  sections: {...builtinSections, ...appSections}, // extend, don't fork
+  blocks: {...builtinBlocks, ...appBlocks},
+});
+
+// 2. Inject your framework's router/cart primitives through the
+//    adapter seam:
+import {AdapterProvider} from '@zalify/storefront-kit/react';
+<AdapterProvider adapter={myAdapter}>{children}</AdapterProvider>;
+
+// 3. Render pages from theme JSON:
+import {ThemeTemplate} from '@zalify/storefront-kit/react';
+<ThemeTemplate name="product" resources={resources} sectionData={data} />;
+```
+
+Customization happens by registering your own sections/blocks and
+editing your project's theme JSON — not by patching this package. That
+is what keeps `pnpm up @zalify/storefront-kit` a safe operation.
+
+## Versioning
+
+Pre-1.0: minor versions may contain breaking changes; patch versions are
+safe. The package ships compiled ESM + type declarations (`dist/`) with
+the TypeScript source included (`src/`) for reference and sourcemaps.
+
+## License
+
+Source-available under the [Zalify Source Available License](./LICENSE.md):
+build, modify, and operate storefronts freely (including for clients);
+don't redistribute the SDK or use it to build competing theme products.

package/dist/commerce/countdown.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Countdown math shared by the theme's <countdown-timer> island and the
+ * React countdown block. Rendering (digit slots, hidden flips) stays in
+ * each runtime; only the clock logic lives here.
+ */
+/** Tolerant end-time parse — accepts ISO and "2026/08/01 00:00:00+0800". */
+export declare function parseEndTime(raw: string): number;
+/** Whole seconds remaining until `end` (epoch ms), floored at 0. */
+export declare function secondsUntil(end: number, now?: number): number;
+export interface CountdownParts {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+}
+export declare function splitCountdown(remainSeconds: number): CountdownParts;
+/** Two-digit display padding ("07"). */
+export declare function pad2(value: number): string;

package/dist/commerce/countdown.js

@@ -0,0 +1,28 @@
+/**
+ * Countdown math shared by the theme's <countdown-timer> island and the
+ * React countdown block. Rendering (digit slots, hidden flips) stays in
+ * each runtime; only the clock logic lives here.
+ */
+/** Tolerant end-time parse — accepts ISO and "2026/08/01 00:00:00+0800". */
+export function parseEndTime(raw) {
+    const direct = Date.parse(raw);
+    if (!Number.isNaN(direct))
+        return direct;
+    return Date.parse(raw.replaceAll('/', '-').replace(' ', 'T'));
+}
+/** Whole seconds remaining until `end` (epoch ms), floored at 0. */
+export function secondsUntil(end, now = Date.now()) {
+    return Math.max(0, Math.floor((end - now) / 1000));
+}
+export function splitCountdown(remainSeconds) {
+    return {
+        days: Math.floor(remainSeconds / 86400),
+        hours: Math.floor(remainSeconds / 3600) % 24,
+        minutes: Math.floor(remainSeconds / 60) % 60,
+        seconds: remainSeconds % 60,
+    };
+}
+/** Two-digit display padding ("07"). */
+export function pad2(value) {
+    return String(value).padStart(2, '0');
+}

package/dist/commerce/events.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Typed pub/sub bus for cross-component state — THE event contract
+ * every storefront implementation speaks (the Liquid theme's islands
+ * and the React apps use the same names and payloads).
+ *
+ * Add new event names + payload shapes to ThemeEvents; both emit() and
+ * on() are checked against it. Keep payloads small and serializable —
+ * components should re-read the DOM or refetch, not sync big state here.
+ */
+import type { CardProduct } from './product';
+export interface ThemeEvents {
+    'cart:updated': {
+        itemCount: number;
+        sections?: Record<string, string>;
+    };
+    'cart:error': {
+        message: string;
+    };
+    /** React runtimes: open the quick-add dialog for a product.
+        (The Liquid theme reaches its <dialog> directly instead.) */
+    'quick-add:open': {
+        product: CardProduct;
+    };
+}
+export declare function emit<K extends keyof ThemeEvents>(type: K, detail: ThemeEvents[K]): void;
+/** Subscribe. Returns an unsubscribe function; also accepts an AbortSignal. */
+export declare function on<K extends keyof ThemeEvents>(type: K, handler: (detail: ThemeEvents[K]) => void, options?: {
+    signal?: AbortSignal;
+}): () => void;

package/dist/commerce/events.js

@@ -0,0 +1,14 @@
+/* SSR-safe: EventTarget exists in workers/Node 18+/browsers, but guard
+   anyway so importing this module can never throw at load time. */
+const bus = typeof EventTarget === 'undefined' ? null : new EventTarget();
+export function emit(type, detail) {
+    bus?.dispatchEvent(new CustomEvent(type, { detail }));
+}
+/** Subscribe. Returns an unsubscribe function; also accepts an AbortSignal. */
+export function on(type, handler, options) {
+    if (!bus)
+        return () => { };
+    const listener = (event) => handler(event.detail);
+    bus.addEventListener(type, listener, options);
+    return () => bus.removeEventListener(type, listener);
+}

package/dist/commerce/facets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Facets (filter/sort) URL codec shared by every storefront:
+ *
+ * - cleanFormParams: form entries → clean query params (empty values
+ *   dropped) — the theme island's #formUrl and the React Facets form
+ *   both build their navigation URLs with it.
+ * - parseFilters/parseSort/parseSearchSort: URL → Storefront API
+ *   query inputs, used by the React apps' route loaders.
+ *
+ * URL contract (Hydrogen-skeleton style):
+ *   sort_by=<handle>            theme sort handle
+ *   filter.<key>=<json>         one param per applied Storefront filter
+ *     e.g. filter.variantOption={"name":"color","value":"Red"}
+ *          filter.price={"min":10,"max":50}
+ */
+/** Form entries → query params, dropping empty values. */
+export declare function cleanFormParams(entries: Iterable<[string, FormDataEntryValue | string]>): URLSearchParams;
+export type ProductFilterInput = Record<string, unknown>;
+export declare function parseFilters(searchParams: URLSearchParams): ProductFilterInput[];
+export interface SortSelection {
+    sortKey: string;
+    reverse: boolean;
+}
+/** Collection pages: theme sort handle → ProductCollectionSortKeys. */
+export declare function parseSort(searchParams: URLSearchParams): SortSelection;
+/** Search page: theme sort handle → SearchSortKeys. */
+export declare function parseSearchSort(searchParams: URLSearchParams): SortSelection;

package/dist/commerce/facets.js

@@ -0,0 +1,71 @@
+/**
+ * Facets (filter/sort) URL codec shared by every storefront:
+ *
+ * - cleanFormParams: form entries → clean query params (empty values
+ *   dropped) — the theme island's #formUrl and the React Facets form
+ *   both build their navigation URLs with it.
+ * - parseFilters/parseSort/parseSearchSort: URL → Storefront API
+ *   query inputs, used by the React apps' route loaders.
+ *
+ * URL contract (Hydrogen-skeleton style):
+ *   sort_by=<handle>            theme sort handle
+ *   filter.<key>=<json>         one param per applied Storefront filter
+ *     e.g. filter.variantOption={"name":"color","value":"Red"}
+ *          filter.price={"min":10,"max":50}
+ */
+/** Form entries → query params, dropping empty values. */
+export function cleanFormParams(entries) {
+    const params = new URLSearchParams();
+    for (const [name, value] of entries) {
+        if (typeof value === 'string' && value !== '')
+            params.append(name, value);
+    }
+    return params;
+}
+export function parseFilters(searchParams) {
+    const filters = [];
+    for (const [param, raw] of searchParams.entries()) {
+        if (!param.startsWith('filter.'))
+            continue;
+        const key = param.slice('filter.'.length);
+        if (!key)
+            continue;
+        let value = raw;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            // plain-string filter values (e.g. tag) pass through as-is
+        }
+        filters.push({ [key]: value });
+    }
+    return filters;
+}
+const DEFAULT_SORT = { sortKey: 'MANUAL', reverse: false };
+const SORT_MAP = {
+    manual: DEFAULT_SORT,
+    'best-selling': { sortKey: 'BEST_SELLING', reverse: false },
+    'title-ascending': { sortKey: 'TITLE', reverse: false },
+    'title-descending': { sortKey: 'TITLE', reverse: true },
+    'price-ascending': { sortKey: 'PRICE', reverse: false },
+    'price-descending': { sortKey: 'PRICE', reverse: true },
+    'created-ascending': { sortKey: 'CREATED', reverse: false },
+    'created-descending': { sortKey: 'CREATED', reverse: true },
+};
+/** Collection pages: theme sort handle → ProductCollectionSortKeys. */
+export function parseSort(searchParams) {
+    return SORT_MAP[searchParams.get('sort_by') ?? ''] ?? DEFAULT_SORT;
+}
+const DEFAULT_SEARCH_SORT = {
+    sortKey: 'RELEVANCE',
+    reverse: false,
+};
+const SEARCH_SORT_MAP = {
+    relevance: DEFAULT_SEARCH_SORT,
+    'price-ascending': { sortKey: 'PRICE', reverse: false },
+    'price-descending': { sortKey: 'PRICE', reverse: true },
+};
+/** Search page: theme sort handle → SearchSortKeys. */
+export function parseSearchSort(searchParams) {
+    return (SEARCH_SORT_MAP[searchParams.get('sort_by') ?? ''] ?? DEFAULT_SEARCH_SORT);
+}

package/dist/commerce/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @zalify/storefront-kit/commerce — framework-agnostic commerce logic shared by
+ * every Zalify storefront (Liquid theme islands, Hydrogen, Next.js…).
+ * Pure TypeScript: no DOM assumptions beyond web-standard globals, no
+ * React. Consumers bundle it as source.
+ */
+export * from './money';
+export * from './events';
+export * from './countdown';
+export * from './facets';
+export * from './product';

package/dist/commerce/index.js

@@ -0,0 +1,11 @@
+/**
+ * @zalify/storefront-kit/commerce — framework-agnostic commerce logic shared by
+ * every Zalify storefront (Liquid theme islands, Hydrogen, Next.js…).
+ * Pure TypeScript: no DOM assumptions beyond web-standard globals, no
+ * React. Consumers bundle it as source.
+ */
+export * from './money';
+export * from './events';
+export * from './countdown';
+export * from './facets';
+export * from './product';

package/dist/commerce/money.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Money formatting for both storefront runtimes:
+ *
+ * - The Liquid theme's islands receive integer cents plus the shop's
+ *   money format string (window.Theme.moneyFormat) → formatMoneyCents.
+ * - React apps receive Storefront API Money objects → formatMoney.
+ */
+/** Money shape from the Storefront API. */
+export interface Money {
+    amount: string;
+    currencyCode: string;
+}
+export interface UnitPriceMeasurement {
+    referenceValue?: number | null;
+    referenceUnit?: string | null;
+}
+/**
+ * Format integer cents using a Shopify money format string
+ * (e.g. "${{amount}}") — mirror of Liquid's `| money` for client JS.
+ */
+export declare function formatMoneyCents(cents: number, format: string): string;
+/** Format a Storefront API Money via Intl (drops .00 like the theme). */
+export declare function formatMoney(money: Money | null | undefined): string;
+export declare function isOnSale(price: Money | null | undefined, compareAt: Money | null | undefined): boolean;
+/** A discount allocation as the Storefront API returns it. */
+export interface DiscountAllocation {
+    /** CartCodeDiscountAllocation */
+    code?: string | null;
+    /** CartAutomaticDiscountAllocation / CartCustomDiscountAllocation */
+    title?: string | null;
+    discountedAmount?: Money | null;
+}
+export interface AggregatedDiscount {
+    label: string;
+    amount: Money;
+}
+/**
+ * Group Storefront API discount allocations by code/title and sum
+ * their amounts. The API returns cart-level `discountAllocations` as
+ * one entry per line the discount applies to (an order discount over
+ * four lines yields four allocations of the same code) — Liquid's
+ * `cart_level_discount_applications` comes pre-aggregated, and
+ * checkout shows one summed row per code. This is the React apps'
+ * equivalent for the cart/drawer summary rows.
+ */
+export declare function aggregateDiscountAllocations(allocations: ReadonlyArray<DiscountAllocation> | null | undefined): AggregatedDiscount[];
+/**
+ * Mirror of Liquid's `unit_price_with_measurement` the way the theme's
+ * own JS formats it: "$4.99/100ml".
+ */
+export declare function formatUnitPrice(unitPrice: Money, measurement?: UnitPriceMeasurement | null): string;

package/dist/commerce/money.js

@@ -0,0 +1,83 @@
+/**
+ * Money formatting for both storefront runtimes:
+ *
+ * - The Liquid theme's islands receive integer cents plus the shop's
+ *   money format string (window.Theme.moneyFormat) → formatMoneyCents.
+ * - React apps receive Storefront API Money objects → formatMoney.
+ */
+/**
+ * Format integer cents using a Shopify money format string
+ * (e.g. "${{amount}}") — mirror of Liquid's `| money` for client JS.
+ */
+export function formatMoneyCents(cents, format) {
+    const amount = cents / 100;
+    return format.replace(/\{\{\s*(\w+)\s*\}\}/, (_, key) => {
+        switch (key) {
+            case 'amount_no_decimals':
+                return String(Math.round(amount));
+            case 'amount_with_comma_separator':
+                return amount.toFixed(2).replace('.', ',');
+            case 'amount_no_decimals_with_comma_separator':
+                return String(Math.round(amount));
+            default:
+                return amount.toFixed(2);
+        }
+    });
+}
+/** Format a Storefront API Money via Intl (drops .00 like the theme). */
+export function formatMoney(money) {
+    if (!money)
+        return '';
+    const amount = Number(money.amount);
+    try {
+        return new Intl.NumberFormat('en', {
+            style: 'currency',
+            currency: money.currencyCode,
+            minimumFractionDigits: amount % 1 === 0 ? 0 : 2,
+        }).format(amount);
+    }
+    catch {
+        return `${money.currencyCode} ${money.amount}`;
+    }
+}
+export function isOnSale(price, compareAt) {
+    if (!price || !compareAt)
+        return false;
+    return Number(compareAt.amount) > Number(price.amount);
+}
+/**
+ * Group Storefront API discount allocations by code/title and sum
+ * their amounts. The API returns cart-level `discountAllocations` as
+ * one entry per line the discount applies to (an order discount over
+ * four lines yields four allocations of the same code) — Liquid's
+ * `cart_level_discount_applications` comes pre-aggregated, and
+ * checkout shows one summed row per code. This is the React apps'
+ * equivalent for the cart/drawer summary rows.
+ */
+export function aggregateDiscountAllocations(allocations) {
+    const byLabel = new Map();
+    for (const allocation of allocations ?? []) {
+        const label = allocation.code ?? allocation.title ?? '';
+        const amount = Number(allocation.discountedAmount?.amount ?? 0);
+        const currencyCode = allocation.discountedAmount?.currencyCode ?? '';
+        const entry = byLabel.get(label);
+        if (entry)
+            entry.total += amount;
+        else
+            byLabel.set(label, { label, total: amount, currencyCode });
+    }
+    return [...byLabel.values()].map(({ label, total, currencyCode }) => ({
+        label,
+        amount: { amount: total.toFixed(2), currencyCode },
+    }));
+}
+/**
+ * Mirror of Liquid's `unit_price_with_measurement` the way the theme's
+ * own JS formats it: "$4.99/100ml".
+ */
+export function formatUnitPrice(unitPrice, measurement) {
+    const referenceValue = measurement?.referenceValue ?? 1;
+    const referenceUnit = (measurement?.referenceUnit ?? '').toLowerCase();
+    const reference = (referenceValue !== 1 ? String(referenceValue) : '') + referenceUnit;
+    return `${formatMoney(unitPrice)}/${reference}`;
+}

package/dist/commerce/product.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Canonical product data model (Storefront API camelCase shape) and the
+ * pure helpers the React storefronts share. The Liquid theme does this
+ * work in Liquid itself — these mirror those template rules 1:1, so a
+ * behavior fix lands here and every React target inherits it.
+ */
+import type { Money, UnitPriceMeasurement } from './money';
+export interface CardImage {
+    id?: string | null;
+    url: string;
+    altText?: string | null;
+    width?: number | null;
+    height?: number | null;
+}
+export interface CardVariant {
+    id: string;
+    availableForSale?: boolean;
+    image?: CardImage | null;
+    price?: Money;
+    compareAtPrice?: Money | null;
+    unitPrice?: Money | null;
+    unitPriceMeasurement?: UnitPriceMeasurement | null;
+    selectedOptions?: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export interface CardSwatch {
+    color?: string | null;
+    image?: {
+        previewImage?: {
+            url?: string | null;
+        } | null;
+    } | null;
+}
+export interface CardOptionValue {
+    name: string;
+    swatch?: CardSwatch | null;
+    firstSelectableVariant?: CardVariant | null;
+}
+/** `metafield(...) { value }` node — null when the metafield is unset. */
+export interface CardMetafield {
+    value?: string | null;
+}
+export interface CardProduct {
+    id: string;
+    handle: string;
+    title: string;
+    vendor?: string;
+    tags?: string[];
+    availableForSale?: boolean;
+    featuredImage?: CardImage | null;
+    images?: {
+        nodes: CardImage[];
+    };
+    priceRange: {
+        minVariantPrice: Money;
+        maxVariantPrice: Money;
+    };
+    compareAtPriceRange?: {
+        minVariantPrice: Money;
+        maxVariantPrice: Money;
+    };
+    options?: Array<{
+        name: string;
+        optionValues: CardOptionValue[];
+    }>;
+    selectedOrFirstAvailableVariant?: CardVariant | null;
+    /** Full variant list — mirror of Liquid's `product.variants`. */
+    variants?: {
+        nodes: CardVariant[];
+    };
+    /** reviews.rating / reviews.rating_count standardized metafields. */
+    rating?: CardMetafield | null;
+    ratingCount?: CardMetafield | null;
+    [key: string]: unknown;
+}
+export type CardOption = NonNullable<CardProduct['options']>[number];
+/** Product URL the way every card/quick-add link builds it. */
+export declare function productUrl(product: Pick<CardProduct, 'handle'>): string;
+/** Numeric tail of a Storefront GID (mirror of Liquid's numeric ids). */
+export declare function numericId(gid: string): string;
+/**
+ * Mirror of Liquid's product.has_only_default_variant: a single
+ * variant whose only option value is Shopify's "Default Title".
+ */
+export declare function hasOnlyDefaultVariant(product: CardProduct): boolean;
+/** The option value a variant carries for a given option name. */
+export declare function optionValueOf(variant: CardVariant, optionName: string): string | undefined;
+/**
+ * Which option a product card's variant picker should display — mirror
+ * of the picker_option resolution in snippets/product-card.liquid.
+ *
+ * @param colorNames localized names that mark an option as a color
+ *   (the theme's `products.color_option_match` locale value, split).
+ */
+export declare function resolvePickerOption(product: CardProduct, swatchStyleSetting: string, colorNames: string[]): CardOption | null;
+/**
+ * Prefer the first variant of this value that has an image — mirror of
+ * the target_variant loop in the Liquid card.
+ */
+export declare function targetVariantFor(product: CardProduct, option: CardOption, valueName: string): CardVariant | null;

package/dist/commerce/product.js

@@ -0,0 +1,93 @@
+/** Product URL the way every card/quick-add link builds it. */
+export function productUrl(product) {
+    return `/products/${product.handle}`;
+}
+/** Numeric tail of a Storefront GID (mirror of Liquid's numeric ids). */
+export function numericId(gid) {
+    return gid.split('/').pop()?.split('?')[0] ?? gid;
+}
+/**
+ * Mirror of Liquid's product.has_only_default_variant: a single
+ * variant whose only option value is Shopify's "Default Title".
+ */
+export function hasOnlyDefaultVariant(product) {
+    const options = product.options ?? [];
+    const first = options[0];
+    if (!first)
+        return true;
+    return (options.length === 1 &&
+        first.optionValues.length === 1 &&
+        first.optionValues[0]?.name === 'Default Title');
+}
+/** The option value a variant carries for a given option name. */
+export function optionValueOf(variant, optionName) {
+    return variant.selectedOptions?.find((o) => o.name === optionName)?.value;
+}
+/**
+ * Which option a product card's variant picker should display — mirror
+ * of the picker_option resolution in snippets/product-card.liquid.
+ *
+ * @param colorNames localized names that mark an option as a color
+ *   (the theme's `products.color_option_match` locale value, split).
+ */
+export function resolvePickerOption(product, swatchStyleSetting, colorNames) {
+    const options = product.options ?? [];
+    const variants = product.variants?.nodes ?? [];
+    if (swatchStyleSetting === 'swatch') {
+        // First option carrying swatch data, or named like a color
+        for (const option of options) {
+            // A single value is nothing to pick — matches the PDP picker
+            if (option.optionValues.length < 2)
+                continue;
+            if (option.optionValues[0]?.swatch)
+                return option;
+            const optionNameDown = option.name.toLowerCase();
+            if (colorNames.some((name) => optionNameDown.includes(name))) {
+                return option;
+            }
+        }
+        return null;
+    }
+    if (swatchStyleSetting === 'variant_image') {
+        // First option whose first two values map to distinct variant
+        // images (same rule as the PDP image picker, probed cheaply)
+        for (const option of options) {
+            const probeIds = [];
+            for (const value of option.optionValues.slice(0, 2)) {
+                for (const variant of variants) {
+                    if (optionValueOf(variant, option.name) === value.name &&
+                        variant.image) {
+                        probeIds.push(variant.image.id ?? variant.image.url);
+                        break;
+                    }
+                }
+            }
+            if (new Set(probeIds).size > 1)
+                return option;
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Prefer the first variant of this value that has an image — mirror of
+ * the target_variant loop in the Liquid card.
+ */
+export function targetVariantFor(product, option, valueName) {
+    const variants = product.variants?.nodes ?? [];
+    let target = null;
+    for (const variant of variants) {
+        if (optionValueOf(variant, option.name) === valueName) {
+            if (!target)
+                target = variant;
+            if (variant.image)
+                return variant;
+        }
+    }
+    if (target)
+        return target;
+    // Fragment without the variants list: fall back to the option
+    // value's own first selectable variant.
+    return (option.optionValues.find((value) => value.name === valueName)
+        ?.firstSelectableVariant ?? null);
+}