@shopbb/helium 0.1.0 → 0.3.0-alpha.1

package/dist/components/VariantSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VariantSelector.d.ts","sourceRoot":"","sources":["../../src/components/VariantSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,cAAc;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACpD,QAAQ,EAAE;QAAE,KAAK,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,aAAa,CAAC;IACtB,mCAAmC;IACnC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,WAAW,CAAC;IACrB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,sBAAsB;IACtB,QAAQ,EAAE,CAAC,WAAW,EAAE,0BAA0B,KAAK,KAAK,CAAC,SAAS,CAAC;CACxE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CAsE1D"}

package/dist/components/VariantSelector.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * <VariantSelector> — 商品 variant 选择器
+ *
+ * 对齐 @shopify/hydrogen <VariantSelector>:
+ *   - 自动解析 variants 的 selectedOptions 维度（颜色 / 尺寸 等）
+ *   - 渲染每个维度的选项按钮
+ *   - 不可购买组合 disabled
+ *   - URL 同步（可选）
+ *   - 默认选第一个 availableForSale
+ *
+ * 设计：组件用 render prop，把每个 option 的选项交给商家渲染。
+ *
+ * 用法：
+ *   <VariantSelector
+ *     product={product}
+ *     value={selectedVariantId}
+ *     onChange={setSelectedVariantId}
+ *   >
+ *     {({ option, value, onSelect }) => (
+ *       <div>
+ *         <h4>{option.name}</h4>
+ *         {option.values.map((v) => (
+ *           <button
+ *             key={v.value}
+ *             disabled={!v.available}
+ *             onClick={() => onSelect(v.value)}
+ *             aria-pressed={v.value === value}
+ *           >
+ *             {v.value}
+ *           </button>
+ *         ))}
+ *       </div>
+ *     )}
+ *   </VariantSelector>
+ */
+import * as React from 'react';
+export function VariantSelector(props) {
+    const { product, value, onChange, children } = props;
+    const variants = product.variants.nodes;
+    const currentVariant = variants.find((v) => v.id === value) || variants[0];
+    // 推断 options（如果 product.options 没传，从 variants.selectedOptions 提取）
+    const options = React.useMemo(() => {
+        if (product.options && product.options.length > 0) {
+            return product.options.map((opt) => ({
+                name: opt.name,
+                values: opt.values.map((v) => ({
+                    value: v,
+                    available: variants.some((variant) => variant.availableForSale &&
+                        variant.selectedOptions?.some((so) => so.name === opt.name && so.value === v)),
+                })),
+            }));
+        }
+        // 从 variants.selectedOptions 反推
+        const dimMap = new Map();
+        for (const v of variants) {
+            for (const so of v.selectedOptions ?? []) {
+                if (!dimMap.has(so.name))
+                    dimMap.set(so.name, new Set());
+                dimMap.get(so.name).add(so.value);
+            }
+        }
+        return Array.from(dimMap.entries()).map(([name, values]) => ({
+            name,
+            values: Array.from(values).map((v) => ({
+                value: v,
+                available: variants.some((variant) => variant.availableForSale &&
+                    variant.selectedOptions?.some((so) => so.name === name && so.value === v)),
+            })),
+        }));
+    }, [product, variants]);
+    // 切换某 option 的 value：找一个匹配的 variant
+    const handleSelect = (optionName, optionValue) => {
+        const currentSelected = new Map((currentVariant?.selectedOptions ?? []).map((so) => [so.name, so.value]));
+        currentSelected.set(optionName, optionValue);
+        // 找最匹配 + available 的 variant
+        const target = variants.find((v) => Array.from(currentSelected.entries()).every(([n, val]) => v.selectedOptions?.some((so) => so.name === n && so.value === val)));
+        if (target)
+            onChange?.(target.id);
+    };
+    return (_jsx(_Fragment, { children: options.map((option) => (_jsx(React.Fragment, { children: children({
+                option,
+                value: currentVariant?.selectedOptions?.find((so) => so.name === option.name)?.value,
+                onSelect: (val) => handleSelect(option.name, val),
+            }) }, option.name))) }));
+}
+//# sourceMappingURL=VariantSelector.js.map

package/dist/components/VariantSelector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VariantSelector.js","sourceRoot":"","sources":["../../src/components/VariantSelector.tsx"],"names":[],"mappings":"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"}

package/dist/components/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @shopbb/helium/components — 商家用 React 组件
+ *
+ * 用法：
+ *   import { Money, Image, ProductPrice, AddToCartButton } from '@shopbb/helium/components';
+ *
+ * 设计原则：
+ *   - 无样式：组件只管行为 + 语义化 DOM，样式商家自己写
+ *   - data-* 钩子：方便选择器
+ *   - 对齐 Shopify Hydrogen 同名组件的 API，迁移成本低
+ */
+export { Money } from './Money';
+export type { MoneyProps, MoneyData, MoneyMeasurement } from './Money';
+export { Image } from './Image';
+export type { ImageProps, ImageData } from './Image';
+export { ProductPrice } from './ProductPrice';
+export type { ProductPriceProps } from './ProductPrice';
+export { AddToCartButton } from './AddToCartButton';
+export type { AddToCartButtonProps } from './AddToCartButton';
+export { CartLineQuantityAdjustButton } from './CartLineQuantityAdjustButton';
+export type { CartLineQuantityAdjustButtonProps } from './CartLineQuantityAdjustButton';
+export { VariantSelector } from './VariantSelector';
+export type { VariantSelectorProps, VariantSelectorRenderProps, VariantOption, } from './VariantSelector';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEvE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,YAAY,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AAExF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,aAAa,GACd,MAAM,mBAAmB,CAAC"}

package/dist/components/index.js

@@ -0,0 +1,18 @@
+/**
+ * @shopbb/helium/components — 商家用 React 组件
+ *
+ * 用法：
+ *   import { Money, Image, ProductPrice, AddToCartButton } from '@shopbb/helium/components';
+ *
+ * 设计原则：
+ *   - 无样式：组件只管行为 + 语义化 DOM，样式商家自己写
+ *   - data-* 钩子：方便选择器
+ *   - 对齐 Shopify Hydrogen 同名组件的 API，迁移成本低
+ */
+export { Money } from './Money';
+export { Image } from './Image';
+export { ProductPrice } from './ProductPrice';
+export { AddToCartButton } from './AddToCartButton';
+export { CartLineQuantityAdjustButton } from './CartLineQuantityAdjustButton';
+export { VariantSelector } from './VariantSelector';
+//# sourceMappingURL=index.js.map

package/dist/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAG9E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @shopbb/helium/react — React SSR renderer for Helium storefronts
+ *
+ * 用法（server worker entry）：
+ *
+ *   import { createReactRenderer, HeliumContextProvider } from '@shopbb/helium/react';
+ *   import { App } from './app';
+ *
+ *   export default {
+ *     fetch: createReactRenderer({
+ *       clientBundle: '/assets/client.js',
+ *       title: '我的店铺',
+ *       app: ({ ctx, url }) => (
+ *         <HeliumContextProvider value={ctx}>
+ *           <App url={url} />
+ *         </HeliumContextProvider>
+ *       ),
+ *     }),
+ *   };
+ *
+ * 行为：
+ *   - 每个请求 createHeliumContext()
+ *   - 拿 React 树调 react-dom/server.edge renderToReadableStream
+ *   - 包一层 <!doctype html><html>...<body><div id="root">[SSR]</div><script src="clientBundle"></script>
+ *   - 把 helium context 序列化嵌入 window.__HELIUM__ 给客户端 hydrate
+ *
+ * 客户端配套：见 ./client.ts
+ */
+import * as React from 'react';
+import type { HeliumContext } from './types';
+export declare function HeliumContextProvider({ value, children, }: {
+    value: HeliumContext;
+    children: React.ReactNode;
+}): React.FunctionComponentElement<React.ProviderProps<HeliumContext | null>>;
+/**
+ * Server-side hook: 拿当前请求的 HeliumContext。
+ * 只能在 React 组件树内调用。
+ */
+export declare function useHeliumContext(): HeliumContext;
+export interface ReactRendererOptions {
+    /**
+     * 返回 React 元素的工厂函数。
+     * 每个请求会调用一次。
+     * 内部应该用 <HeliumContextProvider value={ctx}> 包裹应用根。
+     */
+    app: (input: {
+        ctx: HeliumContext;
+        url: URL;
+        request: Request;
+    }) => React.ReactElement | Promise<React.ReactElement>;
+    /**
+     * 浏览器加载的客户端 JS bundle URL，
+     * 例如 '/assets/client.js'。Vite 构建后通常会带 hash。
+     *
+     * 不传则只 SSR、不 hydrate（适合纯 SEO 场景）。
+     */
+    clientBundle?: string;
+    /**
+     * 注入到 <head> 的 CSS bundle URL。
+     */
+    cssBundle?: string;
+    /**
+     * <title>
+     */
+    title?: string;
+    /**
+     * <head> 里额外的 HTML（meta、link、script）。
+     */
+    headHtml?: string;
+    /**
+     * Storefront 配置（覆盖默认 header 解析行为）。
+     * 如不传，会自动从 Gateway 注入的 header 读：
+     *   X-Public-Storefront-Token / X-Private-Storefront-Token / X-Store-Id
+     */
+    storefront?: {
+        apiUrl?: string;
+        publicAccessToken?: string;
+        privateAccessToken?: string;
+        storeId?: string;
+    };
+    /**
+     * Cart 配置（默认走 cookie）。
+     */
+    cart?: {
+        maxAgeSeconds?: number;
+    };
+    /**
+     * 是否启用 streaming SSR（默认 false，等全部渲染完）。
+     * 启用后首字节更快，但要求所有数据加载都用 Suspense。
+     */
+    streaming?: boolean;
+    /**
+     * 处理错误的兜底（异常时返回的响应）。
+     */
+    onError?: (err: unknown, request: Request) => Response | Promise<Response>;
+}
+export declare function createReactRenderer(opts: ReactRendererOptions): (request: Request, env: any, executionContext: ExecutionContext) => Promise<Response>;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ7C,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,6EAMA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAQhD;AAMD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE;QACX,GAAG,EAAE,aAAa,CAAC;QACnB,GAAG,EAAE,GAAG,CAAC;QACT,OAAO,EAAE,OAAO,CAAC;KAClB,KAAK,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,IAE1D,SAAS,OAAO,EAChB,KAAK,GAAG,EACR,kBAAkB,gBAAgB,KACjC,OAAO,CAAC,QAAQ,CAAC,CAkHrB"}

package/dist/react.js

@@ -0,0 +1,168 @@
+/**
+ * @shopbb/helium/react — React SSR renderer for Helium storefronts
+ *
+ * 用法（server worker entry）：
+ *
+ *   import { createReactRenderer, HeliumContextProvider } from '@shopbb/helium/react';
+ *   import { App } from './app';
+ *
+ *   export default {
+ *     fetch: createReactRenderer({
+ *       clientBundle: '/assets/client.js',
+ *       title: '我的店铺',
+ *       app: ({ ctx, url }) => (
+ *         <HeliumContextProvider value={ctx}>
+ *           <App url={url} />
+ *         </HeliumContextProvider>
+ *       ),
+ *     }),
+ *   };
+ *
+ * 行为：
+ *   - 每个请求 createHeliumContext()
+ *   - 拿 React 树调 react-dom/server.edge renderToReadableStream
+ *   - 包一层 <!doctype html><html>...<body><div id="root">[SSR]</div><script src="clientBundle"></script>
+ *   - 把 helium context 序列化嵌入 window.__HELIUM__ 给客户端 hydrate
+ *
+ * 客户端配套：见 ./client.ts
+ */
+import * as React from 'react';
+import { renderToReadableStream } from 'react-dom/server';
+import { createHeliumContext, cartGetIdDefault, cartSetIdDefault, } from './index';
+// ============================================================
+// React Context for HeliumContext
+// ============================================================
+const HeliumReactContext = React.createContext(null);
+export function HeliumContextProvider({ value, children, }) {
+    return React.createElement(HeliumReactContext.Provider, { value }, children);
+}
+/**
+ * Server-side hook: 拿当前请求的 HeliumContext。
+ * 只能在 React 组件树内调用。
+ */
+export function useHeliumContext() {
+    const ctx = React.useContext(HeliumReactContext);
+    if (!ctx) {
+        throw new Error('useHeliumContext() must be called within <HeliumContextProvider>');
+    }
+    return ctx;
+}
+export function createReactRenderer(opts) {
+    return async function fetch(request, env, executionContext) {
+        try {
+            // 1. 装配 HeliumContext
+            const storefrontApiUrl = opts.storefront?.apiUrl ||
+                env?.PUBLIC_STOREFRONT_API_URL ||
+                'https://api.oxygen-demo.cloudc.top/api/2026-04/graphql.json';
+            const publicToken = opts.storefront?.publicAccessToken ||
+                request.headers.get('X-Public-Storefront-Token') ||
+                '';
+            const privateToken = opts.storefront?.privateAccessToken ||
+                request.headers.get('X-Private-Storefront-Token') ||
+                undefined;
+            const storeId = opts.storefront?.storeId ||
+                request.headers.get('X-Store-Id') ||
+                '';
+            const ctx = createHeliumContext({
+                request,
+                env,
+                executionContext,
+                storefront: {
+                    apiUrl: storefrontApiUrl,
+                    publicAccessToken: publicToken,
+                    privateAccessToken: privateToken,
+                    storeId,
+                    cache: typeof caches !== 'undefined'
+                        ? await caches.open('helium-storefront').catch(() => undefined)
+                        : undefined,
+                },
+                cart: {
+                    getId: cartGetIdDefault(request.headers),
+                    setId: cartSetIdDefault({
+                        maxage: opts.cart?.maxAgeSeconds ?? 60 * 60 * 24 * 365,
+                    }),
+                },
+            });
+            // 2. 拿 React 元素
+            const url = new URL(request.url);
+            const element = await opts.app({ ctx, url, request });
+            // 3. SSR Boot data：把店铺标识 + cart-id 提前传给客户端
+            const boot = {
+                storefront: {
+                    apiUrl: storefrontApiUrl,
+                    // 仅 public token 暴露到客户端
+                    publicAccessToken: publicToken,
+                    storeId,
+                },
+                url: request.url,
+                // 不传 token 等敏感字段
+            };
+            const bootScript = `<script>window.__HELIUM__=${JSON.stringify(boot).replace(/</g, '\\u003c')}</script>`;
+            // 4. Render React 树
+            const wrappedApp = React.createElement(HeliumReactContext.Provider, { value: ctx }, element);
+            const stream = await renderToReadableStream(wrappedApp, {
+                onError(err) {
+                    console.error('[helium SSR error]', err);
+                },
+            });
+            // 等所有数据加载完成（除非启用 streaming）
+            if (!opts.streaming) {
+                await stream.allReady;
+            }
+            // 5. 拼接最终响应
+            const head = `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+${opts.title ? `<title>${escapeHtml(opts.title)}</title>` : ''}
+${opts.cssBundle ? `<link rel="stylesheet" href="${opts.cssBundle}" />` : ''}
+${opts.headHtml ?? ''}
+</head>
+<body>
+<div id="root">`;
+            const tail = `</div>${bootScript}${opts.clientBundle
+                ? `<script type="module" src="${opts.clientBundle}"></script>`
+                : ''}</body></html>`;
+            // 合并 stream
+            const body = composeStream(head, stream, tail);
+            const headers = new Headers(ctx.responseHeaders);
+            headers.set('Content-Type', 'text/html; charset=utf-8');
+            headers.set('X-Powered-By', '@shopbb/helium');
+            return new Response(body, { headers });
+        }
+        catch (err) {
+            if (opts.onError)
+                return opts.onError(err, request);
+            console.error('[helium] unhandled', err);
+            return new Response('Internal Error', { status: 500 });
+        }
+    };
+}
+// ============================================================
+// helpers
+// ============================================================
+function escapeHtml(s) {
+    return s.replace(/[<>&"']/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+/**
+ * 把 head + react stream + tail 拼成一个 ReadableStream<Uint8Array>
+ */
+function composeStream(head, body, tail) {
+    const encoder = new TextEncoder();
+    return new ReadableStream({
+        async start(controller) {
+            controller.enqueue(encoder.encode(head));
+            const reader = body.getReader();
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                controller.enqueue(value);
+            }
+            controller.enqueue(encoder.encode(tail));
+            controller.close();
+        },
+    });
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopbb/helium",
-  "version": "0.1.0",
-  "description": "shopbb storefront framework — GraphQL client, cart handler, and cache helpers for Cloudflare Workers",
+  "version": "0.3.0-alpha.1",
+  "description": "shopbb storefront framework — components, React SSR, GraphQL client, cart handler, cache for Cloudflare Workers",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -12,6 +12,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
     }
   },
   "files": [
@@ -30,11 +42,29 @@
     "ecommerce",
     "cloudflare",
     "workers",
-    "graphql"
+    "graphql",
+    "react",
+    "ssr"
   ],
   "repository": "https://github.com/shopbb/shopbb",
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20240117.0",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
     "typescript": "^5.3.3"
   },
   "engines": {

package/src/client.tsx

@@ -0,0 +1,103 @@
+/**
+ * @shopbb/helium/client — Browser-side hydration helpers
+ *
+ * 商家的客户端 entry：
+ *
+ *   import { hydrate } from '@shopbb/helium/client';
+ *   import { App } from './app';
+ *
+ *   hydrate(<App />);
+ *
+ * 行为：
+ *   - 从 window.__HELIUM__ 拿 SSR 时塞进去的 boot data
+ *   - 包一层 BrowserHeliumContextProvider（含 storefront.query helper，纯客户端 fetch）
+ *   - 调 hydrateRoot
+ */
+
+import * as React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+
+// ============================================================
+// Browser-side context shape
+// 与 server 端 HeliumContext 不完全一致：cart 操作要通过 form action 或专门客户端 mutation
+// 这里先暴露最常用的 storefront.query
+// ============================================================
+
+interface ClientStorefrontClient {
+  query<T = any>(graphql: string, options?: { variables?: any }): Promise<T>;
+  mutate<T = any>(graphql: string, options?: { variables?: any }): Promise<T>;
+}
+
+interface ClientHeliumContext {
+  storefront: ClientStorefrontClient;
+  url: string;
+}
+
+declare global {
+  interface Window {
+    __HELIUM__?: {
+      storefront: { apiUrl: string; publicAccessToken: string; storeId: string };
+      url: string;
+    };
+  }
+}
+
+const ClientHeliumReactContext = React.createContext<ClientHeliumContext | null>(null);
+
+export function useHeliumClient(): ClientHeliumContext {
+  const ctx = React.useContext(ClientHeliumReactContext);
+  if (!ctx) {
+    throw new Error(
+      'useHeliumClient() must be called within HeliumClientProvider (use hydrate())',
+    );
+  }
+  return ctx;
+}
+
+function makeClientStorefront(boot: {
+  apiUrl: string;
+  publicAccessToken: string;
+  storeId: string;
+}): ClientStorefrontClient {
+  async function call<T>(graphql: string, variables?: any): Promise<T> {
+    const res = await fetch(boot.apiUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Storefront-Access-Token': boot.publicAccessToken,
+      },
+      body: JSON.stringify({ query: graphql, variables }),
+    });
+    const json = (await res.json()) as { data?: T; errors?: Array<{ message: string }> };
+    if (json.errors) {
+      throw new Error(json.errors[0]?.message || 'GraphQL error');
+    }
+    return json.data as T;
+  }
+  return {
+    query: (q, opts) => call(q, opts?.variables),
+    mutate: (q, opts) => call(q, opts?.variables),
+  };
+}
+
+/**
+ * 客户端 hydrate 入口。
+ * 通常调用一次即可。
+ */
+export function hydrate(app: React.ReactElement) {
+  const boot = window.__HELIUM__;
+  if (!boot) {
+    console.warn('[helium] window.__HELIUM__ missing, hydrate skipped');
+    return;
+  }
+  const ctx: ClientHeliumContext = {
+    storefront: makeClientStorefront(boot.storefront),
+    url: boot.url,
+  };
+  const wrapped = React.createElement(
+    ClientHeliumReactContext.Provider,
+    { value: ctx },
+    app,
+  );
+  hydrateRoot(document.getElementById('root')!, wrapped);
+}