@commercebuild/extension 0.0.13 → 0.0.15

package/config/host-libs.json

@@ -0,0 +1,20 @@
+{
+  "//": "AUTO-GENERATED from packages/extension-host-libs — do not edit. Regenerate with `yarn generate-extension-host-types`.",
+  "external": [
+    "react",
+    "react-dom",
+    "react-dom/client",
+    "firebase/app",
+    "firebase/firestore"
+  ],
+  "globals": {
+    "react": "cb.lib.React",
+    "react-dom": "cb.lib.ReactDOM",
+    "react-dom/client": "cb.lib.ReactDOM",
+    "firebase/app": "cb.lib.firebase.app",
+    "firebase/firestore": "cb.lib.firebase.firestore"
+  },
+  "forbidden": [
+    "firebase/firestore/lite"
+  ]
+}

package/config/vite.config.mjs

@@ -3,12 +3,134 @@ import ViteHMRNotifierPlugin from "../scripts/vite-plugin-hmr-notifier.mjs";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 // import dts from "vite-plugin-dts";
-// import { fileURLToPath } from "url";
+import { fileURLToPath } from "url";
 import path from "path";
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import chalk from "chalk";
-// const __filename = fileURLToPath(import.meta.url);
-// const __dirname = dirname(__filename);
+
+// The host contract version this extension targets, declared in the manifest.
+// Injected into the bundle so the storefront host can check compatibility
+// before mounting the extension. See cb-store's docs/extension-host-api.
+function readCbApiVersion() {
+  try {
+    const manifestPath = path.resolve(process.cwd(), "commercebuild.json");
+    if (existsSync(manifestPath)) {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      return manifest.cbApiVersion;
+    }
+  } catch {
+    // fall through — an extension with no declared version loads as legacy
+  }
+  return undefined;
+}
+
+const cbApiVersion = readCbApiVersion();
+const cbMetaBanner = cbApiVersion
+  ? `;(function(){try{if(typeof window!=="undefined"){window.__CBExtensionMeta=Object.assign(window.__CBExtensionMeta||{},{cbApiVersion:${JSON.stringify(
+      cbApiVersion,
+    )}});}}catch(e){}})();`
+  : "";
+
+// Host-provided libraries (import specifier → cb.* global), generated
+// from the cb-store host-lib registry so this build externalizes
+// exactly what the storefront provides. Regenerated by cb-store's
+// `yarn generate-extension-host-types`; do not edit host-libs.json.
+const hostLibs = JSON.parse(
+  readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "host-libs.json"),
+    "utf8",
+  ),
+);
+
+/**
+ * Emit dist/cb-manifest.json alongside the bundle: the host libs this
+ * build actually externalized (the storefront preloads the lazy ones
+ * BEFORE injecting index.js) plus the app's data-connection
+ * declarations copied from config.json. The manifest travels with the
+ * artifact — versioned by uploadId like index.js itself — so nothing
+ * app-side needs to be written to Firestore, and a store pinned to an
+ * old upload gets exactly that upload's declarations.
+ */
+function cbManifestPlugin() {
+  return {
+    name: "cb-emit-manifest",
+    generateBundle(_options, bundle) {
+      // The chunk's own `imports` lists exactly the modules rollup left
+      // external — the ground truth of what the artifact expects the
+      // host to provide (a resolveId hook can't see them: rollup
+      // matches the `external` option before plugins run).
+      const used = new Set();
+      for (const output of Object.values(bundle)) {
+        if (output.type !== "chunk") continue;
+        for (const spec of [...output.imports, ...output.dynamicImports]) {
+          used.add(spec);
+        }
+      }
+      let connections = [];
+      let declaredHostLibs = [];
+      try {
+        const configPath = path.resolve(process.cwd(), "config.json");
+        if (existsSync(configPath)) {
+          const config = JSON.parse(readFileSync(configPath, "utf8"));
+          if (Array.isArray(config.connections)) {
+            connections = config.connections.filter(
+              (c) => c && typeof c === "object" && typeof c.name === "string",
+            );
+          }
+        }
+        const manifestPath = path.resolve(process.cwd(), "commercebuild.json");
+        if (existsSync(manifestPath)) {
+          const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+          // Optional explicit override for anything the resolve hook
+          // can't see (kept for parity with the editor compiler).
+          if (Array.isArray(manifest.hostLibs)) {
+            declaredHostLibs = manifest.hostLibs.filter(
+              (s) => typeof s === "string",
+            );
+          }
+        }
+      } catch {
+        // A broken config fails the type-check/build on its own terms.
+      }
+      this.emitFile({
+        type: "asset",
+        fileName: "cb-manifest.json",
+        source:
+          JSON.stringify(
+            {
+              cbApiVersion,
+              hostLibs: [...new Set([...used, ...declaredHostLibs])].sort(),
+              connections,
+            },
+            null,
+            2,
+          ) + "\n",
+      });
+    },
+  };
+}
+
+// Packages that must never be bundled OR externalized — each would
+// silently conflict with a host lib at runtime (e.g. firestore lite
+// registers the same 'firestore' component as the full SDK, and
+// whichever loads first wins with no error).
+function forbiddenImportsPlugin() {
+  const forbidden = new Set(hostLibs.forbidden ?? []);
+  return {
+    name: "cb-forbidden-imports",
+    enforce: "pre",
+    resolveId(source) {
+      if (forbidden.has(source)) {
+        throw new Error(
+          `"${source}" cannot be used in a commercebuild extension — ` +
+            `the host provides a conflicting implementation. ` +
+            `Import the host-provided module instead (see host-libs.json).`,
+        );
+      }
+      return null;
+    },
+  };
+}
 
 const jsEntry = path.resolve(process.cwd(), "src/index.js");
 const tsEntry = path.resolve(process.cwd(), "src/index.ts");
@@ -25,12 +147,10 @@ const baseBuildConfig = {
   minify: "esbuild",
   sourcemap: false,
   rollupOptions: {
-    external: ["react", "react-dom"],
+    external: hostLibs.external,
     output: {
-      globals: {
-        react: "cb.React",
-        "react-dom": "cb.ReactDom",
-      },
+      banner: cbMetaBanner,
+      globals: hostLibs.globals,
       assetFileNames: (assetInfo) => {
         if (assetInfo.name.endsWith(".css")) {
           return assetInfo.originalFileName || assetInfo.name || "asset.css";
@@ -43,6 +163,8 @@ const baseBuildConfig = {
 
 const prodConfig = {
   plugins: [
+    forbiddenImportsPlugin(),
+    cbManifestPlugin(),
     react({
       jsxRuntime: "classic",
     }),
@@ -82,6 +204,8 @@ export default defineConfig(({ mode, command }) => {
     return {
       root: ".",
       plugins: [
+        forbiddenImportsPlugin(),
+        cbManifestPlugin(),
         ViteHMRNotifierPlugin(),
         react({
           jsxRuntime: "classic",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercebuild/extension",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "types": "./types/index.d.ts",
   "exports": {
     ".": {
@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@commercebuild/platform-api": "^0.*",
-    "@commercebuild/ui": "^0.0.5",
+    "@commercebuild/ui": "^0.*",
     "@headlessui/react": "^2.2.4",
     "@tailwindcss/postcss": "^4.1.10",
     "@tailwindcss/vite": "^4.1.11",
@@ -22,6 +22,7 @@
     "@vitejs/plugin-react": "^4.5.2",
     "chalk": "^5.4.1",
     "esbuild": "^0.25.6",
+    "firebase": "^12.2.1",
     "lucide-react": "^0.525.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",

package/schemas/config.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "commercebuild extension configuration",
+  "description": "Data-connection declarations (config.json) or development overrides (config.development.json — never deployed, matched to declarations by name).",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "connections": {
+      "type": "array",
+      "description": "Named data connections. In config.json each entry declares a connection; in config.development.json each entry overrides the declaration with the same name (scratch names may be introduced for testing).",
+      "items": {
+        "$ref": "#/$defs/connection"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "connection": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
+          "description": "Connection name the app code passes to cb.utils.useFirebaseApp(name). With exactly one connection configured, useFirebaseApp() with no argument resolves it; otherwise the no-argument form looks for \"default\"."
+        },
+        "provider": {
+          "description": "Backing service. Absent means \"firebase\".",
+          "enum": [
+            "firebase"
+          ]
+        },
+        "scope": {
+          "description": "\"store\" (the default): the merchant supplies the config per store under Installed Apps → Configure data — do not put a config here. \"app\": the config is fixed in this declaration (required below), owned by the app and not merchant-overridable.",
+          "enum": [
+            "store",
+            "app"
+          ],
+          "default": "store"
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown as the connection's title in the merchant's config form."
+        },
+        "description": {
+          "type": "string",
+          "description": "Shown under the label in the merchant's config form."
+        },
+        "config": {
+          "$ref": "#/$defs/firebaseConfig"
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "scope": {
+                "const": "app"
+              }
+            },
+            "required": [
+              "scope"
+            ]
+          },
+          "then": {
+            "required": [
+              "config"
+            ]
+          }
+        }
+      ]
+    },
+    "firebaseConfig": {
+      "type": "object",
+      "description": "Firebase web config (the firebaseConfig snippet from the Firebase console). Public by design — access control lives in the project's Security Rules.",
+      "required": [
+        "apiKey",
+        "projectId"
+      ],
+      "properties": {
+        "apiKey": {
+          "type": "string",
+          "minLength": 1
+        },
+        "projectId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "authDomain": {
+          "type": "string"
+        },
+        "storageBucket": {
+          "type": "string"
+        },
+        "messagingSenderId": {
+          "type": "string"
+        },
+        "appId": {
+          "type": "string"
+        },
+        "measurementId": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/types/global.d.ts

@@ -1,15 +1,392 @@
+// AUTO-GENERATED — DO NOT EDIT.
+// Generated by scripts/generate-extension-host-types.mjs from
+// apps/storefront/src/lib/extension/cb-host-api.types.ts (the CbHostApi
+// contract). Regenerate with `yarn generate-extension-host-types`.
+
+import * as React from "react";
+import React__default, { CSSProperties } from "react";
+import * as ReactDOM from "react-dom";
+import * as FirebaseAppNs from "firebase/app";
+import * as FirebaseFirestoreNs from "firebase/firestore";
+import { cart_v2, catalog_v1, Platform } from "@commercebuild/platform-api";
+import * as icons from "lucide-react";
+import * as uis from "@commercebuild/ui";
 import {
   Disclosure,
   DisclosureButton,
   DisclosurePanel,
 } from "@headlessui/react";
-import * as uis from "@commercebuild/ui";
-import * as icons from "lucide-react";
-import * as React from "react";
-import { Platform } from "@commercebuild/platform-api";
-import type { UrlObject } from "url";
+import { UrlObject } from "url";
+import { ProductTypeInterface } from "@commercebuild/platform-api/type/v1";
+
+declare function useLanagueTranslater(): {
+  _t: (k: string, obj?: any) => string | undefined;
+  t: (k: string) => string;
+  tt: (k: string, obj?: any) => (kk: string) => string;
+  tmsg: (k: string) => any;
+  tlink: (uri: string) => string;
+  talink: (uri: string) => string;
+  trlink: (uri: string) => string;
+  lang: "en-US" | "fr-FR" | "zh";
+  locale: "en-US" | "fr-FR" | "zh";
+};
+
+declare const useTranslater: typeof useLanagueTranslater;
+
+type Category = catalog_v1.VerifiedCategoryMapper;
+type CartRequestItem = Omit<
+  cart_v2.CartUserCartItemInterface,
+  "configuratorCode" | "groupCode"
+> & {
+  imageUrl?: string;
+  description?: string;
+  unitPrice?: number;
+  detailPageUrl?: string;
+};
+type PostItemsSearchItem = catalog_v1.PostItemsSearchItem;
+type PostItemsSearchResponse = catalog_v1.PostItemsSearchResponse;
+type GetItemDetailResponse = catalog_v1.GetItemDetailResponse;
+
+interface AddToCartProps {
+  items: CartRequestItem[];
+  disabled?: boolean;
+  onSuccessCallback?: () => void;
+  className?: string;
+  /** Inline style forwarded to the button (e.g. Product Card button-scheme vars). */
+  style?: CSSProperties;
+  /**
+   * Width control (opt-in). Omit for the default responsive width; `true` = full
+   * width at all breakpoints; `false` = content width (auto).
+   */
+  fullWidth?: boolean;
+}
+declare function AddToCart({
+  items,
+  disabled,
+  onSuccessCallback,
+  className,
+  style,
+  fullWidth,
+}: AddToCartProps): React.JSX.Element;
+
+declare function CategoryProduct({
+  product,
+  imagePriority,
+}: {
+  product: PostItemsSearchItem;
+  imagePriority?: boolean;
+}): React.JSX.Element;
+
+declare function CategoryBreadcrumb({
+  category,
+}: {
+  category: Category;
+}): React.JSX.Element;
+
+declare function CategoryTitle({
+  category,
+}: {
+  category: Category;
+}): React.JSX.Element;
+
+declare function CategorySidebar({
+  category,
+  url,
+  aggregation,
+  currentFilters,
+  isDrawer,
+}: {
+  category: Category;
+  url: string;
+  aggregation?: PostItemsSearchResponse["aggregation"];
+  currentFilters: Record<string, string[]>;
+  isDrawer?: boolean;
+}): React.JSX.Element | null;
+
+declare function CategorySort({
+  url,
+  options,
+  sort,
+}: {
+  url: string;
+  options: {
+    name: string;
+  }[];
+  sort: number;
+}): React.JSX.Element;
+
+declare function CategoryProducts({
+  hasSiderbar,
+  items,
+}: {
+  hasSiderbar?: boolean;
+  items: PostItemsSearchItem[];
+}): React.JSX.Element;
+
+declare function CategoryProductsPageSize({
+  url,
+  options,
+  size,
+}: {
+  url: string;
+  options: {
+    name: string;
+    value: number;
+  }[];
+  size: number;
+}): React.JSX.Element;
+
+declare function ProductTitle({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+type ThumbnailPosition = "top" | "right" | "bottom" | "left";
+declare const ProductImages: ({
+  product,
+  thumbnailPosition,
+}: {
+  product: GetItemDetailResponse;
+  thumbnailPosition?: ThumbnailPosition;
+}) => React.JSX.Element;
+
+declare function ProductPrice({
+  product,
+  items,
+}: {
+  product: GetItemDetailResponse | PostItemsSearchItem;
+  items?: {
+    price?: number;
+  }[];
+}): React.JSX.Element | null;
+
+declare const ProductStockStatus: ({
+  product,
+  displayStatusTitle,
+}: {
+  product: GetItemDetailResponse | PostItemsSearchItem;
+  displayStatusTitle?: boolean;
+}) => React.JSX.Element | null;
+
+declare const ProductStockQuantity: ({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}) => React.JSX.Element | null;
+
+declare function ProductRating({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+declare function ProductDescription({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+interface ProductQuantityInputProps {
+  qty: number;
+  setQty: (qty: number) => void;
+  min?: number;
+  max?: number;
+  disabled?: boolean;
+}
+declare const ProductQuantityInput: React__default.FC<ProductQuantityInputProps>;
+
+declare function StandardProductAddToCart({
+  product,
+  quantityRequested,
+}: {
+  product: GetItemDetailResponse;
+  quantityRequested: number;
+}): React.JSX.Element;
+
+declare function ProductAddToFavorite({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
 
-// === Link and Image from nextjs =============================================
+declare function ProductMakeOffer({
+  product,
+  qty,
+}: {
+  product: GetItemDetailResponse;
+  qty: number;
+}): React.JSX.Element | null;
+
+declare function ProductRelatedProducts({
+  relatedProducts,
+}: {
+  relatedProducts: PostItemsSearchItem[];
+}): React.JSX.Element | null;
+
+declare function VariantProductAddToCart({
+  items,
+}: {
+  items: CartRequestItem[];
+}): React.JSX.Element;
+
+declare function ProductBreadcrumb({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+/**
+ * @deprecated Use convertProductToCartRequestItem instead
+ */
+
+type ProductProps = {
+  type: ProductTypeInterface;
+  itemCode: string;
+  variantCode?: string;
+  defaultUnitOfMeasure: {
+    unitCode: string;
+    conversion: number;
+    default: boolean;
+  } | null;
+  description?: string;
+  detailPageUrl?: string;
+  images: {
+    main: {
+      thumbnailSmall: string;
+    } | null;
+  } | null;
+  quantityRequested?: number;
+};
+declare const convertProductItemToCartRequestItem: (
+  product: ProductProps,
+) => CartRequestItem;
+
+interface Options extends Intl.NumberFormatOptions {
+  locale?: string;
+  forceDecimals?: number;
+}
+declare const displayMoney: (
+  amount: string | number,
+  options?: Options,
+) => string;
+
+declare function revalidateTag(
+  tag: string,
+  profile:
+    | string
+    | {
+        expire?: number;
+      },
+): Promise<void>;
+declare function revalidatePath(
+  path: string,
+  type?: "layout" | "page",
+): Promise<void>;
+declare function revalidate(): Promise<void>;
+
+/**
+ * Per-extension render scope.
+ *
+ * Extension code has no runtime identity of its own — components are
+ * bare functions and `cb` is one page-global object, while a single
+ * React tree can hold components from several different extensions at
+ * once. This context supplies that identity lexically: the host wraps
+ * every extension render site (renderExtensionComponent's boundary and
+ * the extension page route) in a provider carrying the registration id
+ * and the extension's resolved per-store configuration. Contract hooks
+ * like cb.utils.useFirebaseApp() read it, so the same component gets
+ * its own extension's connections wherever it renders — including the
+ * synthetic "preview" / "local" registrations, which just carry their
+ * own scope value.
+ */
+
+/**
+ * Merchant-supplied Firebase web config (the Firebase-console snippet
+ * subset). Not a secret — it ships to every browser by design; access
+ * control lives entirely in the merchant's Firestore Security Rules.
+ */
+interface CbFirebaseConfig {
+  apiKey: string;
+  projectId: string;
+  authDomain?: string;
+  storageBucket?: string;
+  messagingSenderId?: string;
+  appId?: string;
+  measurementId?: string;
+}
+
+/**
+ * The extension host API contract (`window.cb`).
+ *
+ * This file is the SINGLE SOURCE OF TRUTH for the `cb` surface. The runtime
+ * factory `buildCbHostApi()` (./cb-host-api.ts) is typed to return `CbHostApi`,
+ * so `tsc` fails if the runtime values and this contract ever diverge.
+ *
+ * The author-facing type declaration (`global.d.ts`) is GENERATED from this
+ * file by `scripts/generate-extension-host-types.mjs` (`yarn
+ * generate-extension-host-types`). Never hand-edit the generated file.
+ *
+ * Boundary typing is hybrid: most members derive their type straight from the
+ * runtime symbol (`typeof ProductTitle`, `typeof displayMoney`); a member is
+ * only curated by hand when deriving would emit an import an extension author's
+ * project cannot resolve (e.g. `next/link`) or would leak internals.
+ */
+
+type TranslationHelpers = ReturnType<typeof useTranslater>;
+/**
+ * The Next.js App Router surface exposed to extensions. Curated (not derived
+ * from `next`) so the generated declaration does not import a `next/*` path an
+ * extension author's project cannot resolve.
+ */
+interface CbRouter {
+  push(
+    href: string,
+    options?: {
+      scroll?: boolean;
+    },
+  ): void;
+  replace(
+    href: string,
+    options?: {
+      scroll?: boolean;
+    },
+  ): void;
+  back(): void;
+  forward(): void;
+  refresh(): void;
+  prefetch(href: string): void;
+}
+/**
+ * Dynamic values the host supplies to the API at build time (per-request React
+ * context values that cannot be static imports).
+ */
+interface CbHostDeps {
+  platformApi: Platform;
+  router: CbRouter;
+  tmsg: TranslationHelpers["tmsg"];
+  tlink: TranslationHelpers["tlink"];
+}
+type CbClassValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | Record<string, unknown>
+  | CbClassValue[];
+type CbClassNameFn = (...inputs: CbClassValue[]) => string;
+type CbContainerProps = React.PropsWithChildren<
+  React.HTMLAttributes<HTMLDivElement> & {
+    maxWidth?: "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+    padding?: "default";
+    additionalMaxWidth?: "default";
+  }
+>;
+type CbContainer = React.ForwardRefExoticComponent<
+  CbContainerProps & React.RefAttributes<HTMLDivElement>
+>;
 type Url = string | UrlObject;
 type OnNavigateEventHandler = (event: { preventDefault: () => void }) => void;
 type InternalLinkProps = {
@@ -28,15 +405,13 @@ type InternalLinkProps = {
   children?: React.ReactNode | undefined;
   onNavigate?: OnNavigateEventHandler;
 } & React.RefAttributes<HTMLAnchorElement>;
-
-declare const NextLink: React.ForwardRefExoticComponent<
+type CbLink = React.ForwardRefExoticComponent<
   Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof InternalLinkProps> &
     InternalLinkProps & {
       children?: React.ReactNode | undefined;
     } & React.RefAttributes<HTMLAnchorElement>
 >;
-
-export interface StaticImageData {
+interface StaticImageData {
   src: string;
   height: number;
   width: number;
@@ -44,19 +419,19 @@ export interface StaticImageData {
   blurWidth?: number;
   blurHeight?: number;
 }
-export interface StaticRequire {
+interface StaticRequire {
   default: StaticImageData;
 }
-export type StaticImport = StaticRequire | StaticImageData;
-export type ImageLoaderProps = {
+type StaticImport = StaticRequire | StaticImageData;
+type ImageLoaderProps = {
   src: string;
   width: number;
   quality?: number;
 };
-export type ImageLoader = (p: ImageLoaderProps) => string;
-export type PlaceholderValue = "blur" | "empty" | `data:image/${string}`;
-export type OnLoadingComplete = (img: HTMLImageElement) => void;
-declare const NextImage: React.ForwardRefExoticComponent<
+type ImageLoader = (p: ImageLoaderProps) => string;
+type PlaceholderValue = "blur" | "empty" | `data:image/${string}`;
+type OnLoadingComplete = (img: HTMLImageElement) => void;
+type CbImage = React.ForwardRefExoticComponent<
   Omit<
     React.DetailedHTMLProps<
       React.ImgHTMLAttributes<HTMLImageElement>,
@@ -86,70 +461,141 @@ declare const NextImage: React.ForwardRefExoticComponent<
   } & React.RefAttributes<HTMLImageElement | null>
 >;
 
-// ============================================================================
-
-declare global {
-  const cb: {
-    version: string;
+/**
+ * Import specifier → module namespace for every runtime host lib, so
+ * `cb.requireLib("firebase/firestore")` returns the fully typed module.
+ */
+interface CbHostLibs {
+  react: typeof React;
+  "react-dom": typeof ReactDOM;
+  "firebase/app": typeof FirebaseAppNs;
+  "firebase/firestore": typeof FirebaseFirestoreNs;
+}
+interface CbHostApi {
+  /** Host-contract semver — see docs/extension-host-api/versioning.md. */
+  version: string;
+  /**
+   * Shared libraries the host provides as build-time externals, so an extension
+   * shares the host's single instance instead of bundling its own (critical for
+   * React — two instances break hooks). The extension build maps
+   * `import ... from "react"` → `cb.lib.React` and `"react-dom"` →
+   * `cb.lib.ReactDOM`.
+   */
+  lib: {
     React: typeof React;
-    platformApi: Platform;
-    utils: {
-      convertProductItemToCartRequestItem;
-      tlink;
-      tmsg;
-      router;
-      displayMoney;
-      cn;
-      revalidate;
-      revalidateTag;
-      revalidatePath;
+    ReactDOM: typeof ReactDOM;
+    /**
+     * Lazy host libs, bound by the extension build — do not read
+     * directly. The host import()s each one before injecting a bundle
+     * that declared it; until then a member read throws a descriptive
+     * error naming the missing lib. Use `cb.requireLib(...)` for an
+     * explicit, typed lookup.
+     */
+    firebase: {
+      app: typeof FirebaseAppNs;
+      firestore: typeof FirebaseFirestoreNs;
     };
-    com: {
-      Cart: {
-        AddToCart;
-      };
-      Category: {
-        CategoryProducts;
-        CategoryProduct;
-        CategoryBreadcrumb;
-        CategoryTitle;
-        CategorySidebar;
-        CategorySort;
-        CategoryProductsPageSize;
-      };
-      Product: {
-        ProductTitle;
-        ProductImages;
-        ProductPrice;
-        ProductStockStatus;
-        ProductStockQuantity;
-        ProductRating;
-        ProductDescription;
-        ProductTabs;
-        ProductQuantityInput;
-        StandardProductAddToCart;
-        VariantProductAddToCart;
-        ProductAddToFavorite;
-        ProductMakeOffer;
-        ProductRelatedProducts;
-      };
+  };
+  /**
+   * The module namespace for a runtime host lib, throwing a descriptive
+   * error when it is not loaded (the extension didn't declare it).
+   */
+  requireLib: <S extends keyof CbHostLibs>(spec: S) => CbHostLibs[S];
+  /** The platform (commerce backend) API SDK client. */
+  platform: Platform;
+  /**
+   * Feature-detect a member by dotted path, e.g.
+   * `cb.has("com.Product.ProductMakeOffer")`. Lets an extension degrade
+   * gracefully across host versions instead of hard-crashing.
+   */
+  has: (path: string) => boolean;
+  utils: {
+    convertProductItemToCartRequestItem: typeof convertProductItemToCartRequestItem;
+    tlink: TranslationHelpers["tlink"];
+    tmsg: TranslationHelpers["tmsg"];
+    router: CbRouter;
+    displayMoney: typeof displayMoney;
+    cn: CbClassNameFn;
+    revalidate: typeof revalidate;
+    revalidateTag: typeof revalidateTag;
+    revalidatePath: typeof revalidatePath;
+    /**
+     * React hook: connection names the store configured for the current
+     * extension (via storeadmin → Installed Apps → Configure data).
+     * Empty outside an extension subtree.
+     */
+    useFirebaseConnections: () => string[];
+    /**
+     * React hook: the host-initialized FirebaseApp for a named
+     * connection, or undefined when it is not configured — always
+     * render a fallback for that case. With no argument: the store's
+     * only connection when exactly one is configured, else the one
+     * named "default". Never call initializeApp yourself; pass this app
+     * to the product entry points (e.g. getFirestore(app)).
+     */
+    useFirebaseApp: (
+      connection?: string,
+    ) => FirebaseAppNs.FirebaseApp | undefined;
+  };
+  com: {
+    Cart: {
+      AddToCart: typeof AddToCart;
+    };
+    Category: {
+      CategoryProducts: typeof CategoryProducts;
+      CategoryProduct: typeof CategoryProduct;
+      CategoryBreadcrumb: typeof CategoryBreadcrumb;
+      CategoryTitle: typeof CategoryTitle;
+      CategorySidebar: typeof CategorySidebar;
+      CategorySort: typeof CategorySort;
+      CategoryProductsPageSize: typeof CategoryProductsPageSize;
+    };
+    Product: {
+      ProductTitle: typeof ProductTitle;
+      ProductImages: typeof ProductImages;
+      ProductPrice: typeof ProductPrice;
+      ProductStockStatus: typeof ProductStockStatus;
+      ProductStockQuantity: typeof ProductStockQuantity;
+      ProductRating: typeof ProductRating;
+      ProductDescription: typeof ProductDescription;
+      ProductQuantityInput: typeof ProductQuantityInput;
+      StandardProductAddToCart: typeof StandardProductAddToCart;
+      VariantProductAddToCart: typeof VariantProductAddToCart;
+      ProductAddToFavorite: typeof ProductAddToFavorite;
+      ProductMakeOffer: typeof ProductMakeOffer;
+      ProductRelatedProducts: typeof ProductRelatedProducts;
+      ProductBreadcrumb: typeof ProductBreadcrumb;
     };
-    ui: {
-      icons: { [K in keyof typeof icons]: (typeof icons)[K] };
-      Link: typeof NextLink;
-      Image: typeof NextImage;
-      Container: React.FC<
-        React.PropsWithChildren<React.HTMLAttributes<HTMLDivElement>>
-      >;
-      Disclosure: typeof Disclosure;
-      DisclosureButton: typeof DisclosureButton;
-      DisclosurePanel: typeof DisclosurePanel;
-    } & { [K in keyof typeof uis]: (typeof uis)[K] };
   };
-
+  ui: {
+    icons: typeof icons;
+    Link: CbLink;
+    Image: CbImage;
+    Container: CbContainer;
+    Disclosure: typeof Disclosure;
+    DisclosureButton: typeof DisclosureButton;
+    DisclosurePanel: typeof DisclosurePanel;
+  } & typeof uis;
+}
+declare global {
+  const cb: CbHostApi;
   interface Window {
-    cb: typeof cb;
+    cb: CbHostApi;
+  }
+  /**
+   * Storefront domain types made ambient for extension authors, so
+   * component/page code (and editor scaffolds) can reference them bare
+   * without importing from the SDK.
+   */
+  type Category = catalog_v1.VerifiedCategoryMapper;
+  interface Product extends catalog_v1.CatalogProductSearchProduct {
+    image: Required<
+      Pick<catalog_v1.CatalogProductSearchProduct["details"]["images"], "main">
+    >["main"];
+    originalPrice?: catalog_v1.CatalogPriceItemDto;
+    formattedPrice: string;
+    href: string;
   }
 }
 
-export {};
+export type { CbFirebaseConfig, CbHostApi, CbHostDeps, CbHostLibs, CbRouter };