@commercebuild/extension 0.0.17 → 0.0.19

package/config/host-libs.json

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

package/config/tsconfig.extension.json

@@ -5,7 +5,7 @@
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "module": "ESNext",
     "skipLibCheck": true,
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
     "resolveJsonModule": true,
     "isolatedModules": true,

package/config/vite.config.mjs

@@ -66,6 +66,32 @@ function cbManifestPlugin() {
           used.add(spec);
         }
       }
+
+      // The admin invocation MERGES its per-bundle hostLibs into the
+      // manifest the storefront build just emitted — never a union
+      // list (a union would make every shopper preload admin-only host
+      // libs). The `admin` key's presence doubles as the "this upload
+      // has an admin bundle" signal for the store admin's loader.
+      if (buildTarget === "admin") {
+        const manifestPath = path.resolve(
+          process.cwd(),
+          "dist/cb-manifest.json",
+        );
+        if (!existsSync(manifestPath)) {
+          throw new Error(
+            "dist/cb-manifest.json is missing — the storefront build must run before the admin build",
+          );
+        }
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        manifest.admin = { hostLibs: [...used].sort() };
+        this.emitFile({
+          type: "asset",
+          fileName: "cb-manifest.json",
+          source: JSON.stringify(manifest, null, 2) + "\n",
+        });
+        return;
+      }
+
       let connections = [];
       let declaredHostLibs = [];
       try {
@@ -132,20 +158,114 @@ function forbiddenImportsPlugin() {
   };
 }
 
-const jsEntry = path.resolve(process.cwd(), "src/index.js");
-const tsEntry = path.resolve(process.cwd(), "src/index.ts");
-const entryFile = existsSync(tsEntry) ? tsEntry : jsEntry;
+// UN-3206: the OPTIONAL admin area (src/admin/) compiles to a second,
+// self-contained bundle — dist/admin.js + admin.css — rendered inside
+// the store admin. CB_BUILD_TARGET=admin selects it; the CLI always
+// runs the storefront build first and the admin one only when the
+// admin entry exists (see scripts/cli.js). Both bundles share the
+// CBExtension global/banner protocol: they execute in different
+// documents and never collide.
+const buildTarget =
+  process.env.CB_BUILD_TARGET === "admin" ? "admin" : "storefront";
+
+function resolveEntry(dir) {
+  const ts = path.resolve(process.cwd(), dir, "index.ts");
+  const js = path.resolve(process.cwd(), dir, "index.js");
+  return existsSync(ts) ? ts : existsSync(js) ? js : null;
+}
+
+const storefrontEntry =
+  resolveEntry("src") ?? path.resolve(process.cwd(), "src/index.js");
+const adminEntry = resolveEntry("src/admin");
+
+if (buildTarget === "admin") {
+  if (!adminEntry) {
+    throw new Error(
+      "CB_BUILD_TARGET=admin but src/admin/index.ts does not exist",
+    );
+  }
+  if (!existsSync(path.resolve(process.cwd(), "src/admin/styles/index.css"))) {
+    throw new Error(
+      "src/admin/index.ts requires src/admin/styles/index.css (the admin stylesheet entry)",
+    );
+  }
+}
+
+const entryFile = buildTarget === "admin" ? adminEntry : storefrontEntry;
+
+// Import boundary rules, mirroring the in-browser editor compiler in
+// cb-store (apps/storeadmin extension-editor esbuild plugin) — the two
+// pipelines MUST agree, or code that fails in editor preview would
+// still publish:
+//   - src/admin/** may import only src/admin/** and src/shared/**;
+//   - src/shared/** may import only src/shared/**;
+//   - nothing outside src/admin/** may import src/admin/**.
+// These keep each bundle's module set structurally clean, which is what
+// makes the per-target Tailwind source scopes exact.
+function projectRelative(file) {
+  const abs = path.resolve(file.split("?")[0]);
+  const rel = path.relative(process.cwd(), abs).split(path.sep).join("/");
+  return rel.startsWith("..") ? null : rel;
+}
+
+export function importBoundaryViolation(importer, resolved) {
+  const fromAdmin = importer.startsWith("src/admin/");
+  const fromShared = importer.startsWith("src/shared/");
+  const toAdmin = resolved.startsWith("src/admin/");
+  const toShared = resolved.startsWith("src/shared/");
+  if (fromAdmin && !toAdmin && !toShared) {
+    return "files under src/admin/ may only import src/admin/ or src/shared/ (the admin bundle must stay independent of storefront code)";
+  }
+  if (fromShared && !toShared) {
+    return "files under src/shared/ may only import src/shared/ (shared code is part of both bundles)";
+  }
+  if (!fromAdmin && toAdmin) {
+    return "only files under src/admin/ may import src/admin/ (admin code never ships in the storefront bundle)";
+  }
+  return null;
+}
+
+function importBoundaryPlugin() {
+  return {
+    name: "cb-import-boundaries",
+    enforce: "pre",
+    resolveId(source, importer) {
+      if (!importer || !source.startsWith(".")) return null;
+      const from = projectRelative(importer);
+      // Directory prefixes are all the rules need — a missing extension
+      // or /index resolution never changes which subtree a path is in.
+      const to = projectRelative(
+        path.resolve(path.dirname(importer.split("?")[0]), source),
+      );
+      if (!from || !to) return null;
+      const violation = importBoundaryViolation(from, to);
+      if (violation) {
+        throw new Error(
+          `Forbidden import of "${source}" from "${from}": ${violation}`,
+        );
+      }
+      return null;
+    },
+  };
+}
 
 const baseBuildConfig = {
   lib: {
     entry: entryFile,
     name: "CBExtension",
     formats: ["umd"],
-    fileName: (format, entryName) =>
-      `${entryName}.${format === "es" ? "mjs" : "js"}`,
+    // Both entries are index.ts, so the entry name can't distinguish
+    // the bundles — name the artifacts by target explicitly.
+    fileName: () => (buildTarget === "admin" ? "admin.js" : "index.js"),
+    cssFileName: buildTarget === "admin" ? "admin" : "style",
   },
   minify: "esbuild",
   sourcemap: false,
+  // The admin invocation writes into the dist/ the storefront build
+  // just produced — vite's default would empty it and delete
+  // index.js/style.css/cb-manifest.json (which the manifest merge
+  // below depends on).
+  emptyOutDir: buildTarget !== "admin",
   rollupOptions: {
     external: hostLibs.external,
     output: {
@@ -153,7 +273,9 @@ const baseBuildConfig = {
       globals: hostLibs.globals,
       assetFileNames: (assetInfo) => {
         if (assetInfo.name.endsWith(".css")) {
-          return assetInfo.originalFileName || assetInfo.name || "asset.css";
+          // The lib css asset is named per target here — both entries
+          // are index.ts, so nothing upstream distinguishes them.
+          return buildTarget === "admin" ? "admin.css" : "style.css";
         }
         return assetInfo.name;
       },
@@ -164,6 +286,7 @@ const baseBuildConfig = {
 const prodConfig = {
   plugins: [
     forbiddenImportsPlugin(),
+    importBoundaryPlugin(),
     cbManifestPlugin(),
     react({
       jsxRuntime: "classic",
@@ -205,6 +328,7 @@ export default defineConfig(({ mode, command }) => {
       root: ".",
       plugins: [
         forbiddenImportsPlugin(),
+        importBoundaryPlugin(),
         cbManifestPlugin(),
         ViteHMRNotifierPlugin(),
         react({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercebuild/extension",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "types": "./types/index.d.ts",
   "exports": {
     ".": {
@@ -34,5 +34,9 @@
   },
   "bin": {
     "commercebuild-extension": "./scripts/cli.js"
+  },
+  "scripts": {
+    "test": "node scripts/test-build.mjs",
+    "release": "npm whoami || npm login && pnpm publish --no-git-checks"
   }
-}
+}

package/schemas/config.schema.json

@@ -19,9 +19,7 @@
   "$defs": {
     "connection": {
       "type": "object",
-      "required": [
-        "name"
-      ],
+      "required": ["name"],
       "properties": {
         "name": {
           "type": "string",
@@ -30,17 +28,11 @@
         },
         "provider": {
           "description": "Backing service. Absent means \"firebase\".",
-          "enum": [
-            "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"
+          "description": "\"store\": 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. Omitted: inferred — a declaration with a \"config\" is app-scoped, one without is store-scoped.",
+          "enum": ["store", "app"]
         },
         "label": {
           "type": "string",
@@ -52,6 +44,10 @@
         },
         "config": {
           "$ref": "#/$defs/firebaseConfig"
+        },
+        "oidcEnabled": {
+          "type": "boolean",
+          "description": "Federate the signed-in shopper's CB Store identity into this connection's Firebase Auth (Firestore Rules then read the cb_* claims). App-scoped declarations only — the merchant accepts an identity-sharing notice once at install/first configuration. On a store-scoped connection the merchant controls this from Installed Apps → Configure data instead, and a flag here is ignored."
         }
       },
       "additionalProperties": false,
@@ -63,14 +59,10 @@
                 "const": "app"
               }
             },
-            "required": [
-              "scope"
-            ]
+            "required": ["scope"]
           },
           "then": {
-            "required": [
-              "config"
-            ]
+            "required": ["config"]
           }
         }
       ]
@@ -78,18 +70,13 @@
     "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"
-      ],
+      "required": ["apiKey", "projectId"],
       "properties": {
         "apiKey": {
-          "type": "string",
-          "minLength": 1
+          "type": "string"
         },
         "projectId": {
-          "type": "string",
-          "minLength": 1
+          "type": "string"
         },
         "authDomain": {
           "type": "string"
@@ -105,6 +92,9 @@
         },
         "measurementId": {
           "type": "string"
+        },
+        "databaseId": {
+          "type": "string"
         }
       },
       "additionalProperties": true

package/scripts/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { execSync } from "child_process";
+import { existsSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { displayError } from "./utils.mjs";
@@ -8,18 +9,40 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const args = process.argv.slice(2);
 
+const viteConfigPath = path.resolve(__dirname, "../config/vite.config.mjs");
+
+// Two independent bundles from one project: the storefront build always
+// runs; the admin build runs only when the OPTIONAL admin area exists,
+// and always AFTER the storefront one — its cb-manifest plugin merges
+// an `admin` section into the manifest the storefront build emitted,
+// and it keeps dist/ intact (emptyOutDir: false in the vite config).
+function hasAdminEntry() {
+  return (
+    existsSync(path.resolve(process.cwd(), "src/admin/index.ts")) ||
+    existsSync(path.resolve(process.cwd(), "src/admin/index.js"))
+  );
+}
+
+function build() {
+  execSync(`vite build --config ${viteConfigPath}`, { stdio: "inherit" });
+  if (hasAdminEntry()) {
+    execSync(`vite build --config ${viteConfigPath}`, {
+      stdio: "inherit",
+      env: { ...process.env, CB_BUILD_TARGET: "admin" },
+    });
+  }
+}
+
 if (args.includes("dev")) {
   try {
-    const viteConfigPath = path.resolve(__dirname, "../config/vite.config.mjs");
-    execSync(`vite build --config ${viteConfigPath}`, { stdio: "inherit" });
+    build();
     execSync(`vite --config ${viteConfigPath}`, { stdio: "inherit" });
   } catch (error) {
     displayError("Failed to start commercebuild extension server:", error);
   }
 } else if (args.includes("build")) {
   try {
-    const viteConfigPath = path.resolve(__dirname, "../config/vite.config.mjs");
-    execSync(`vite build --config ${viteConfigPath}`, { stdio: "inherit" });
+    build();
   } catch (error) {
     displayError("Failed to build with commercebuild extension:", error);
   }

package/scripts/test-build.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Integration test for the dual-bundle build (UN-3206): builds a scratch
+ * fixture project with the real vite pipeline and asserts the artifact
+ * contract the hosts depend on — storefront trio untouched by the admin
+ * invocation, per-target CSS scan scopes, cb-manifest merge semantics,
+ * and the import boundary rules. Run with `node scripts/test-build.mjs`.
+ *
+ * These scopes/rules MUST stay in lockstep with the in-browser editor
+ * compiler in cb-store (apps/storeadmin extension-editor) — this test is
+ * the canonical side of that parity contract.
+ */
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const viteBin = path.join(pkgRoot, "node_modules", ".bin", "vite");
+const viteConfig = path.join(pkgRoot, "config", "vite.config.mjs");
+
+const fixture = mkdtempSync(path.join(tmpdir(), "cb-ext-build-"));
+
+function write(rel, content) {
+  const target = path.join(fixture, rel);
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, content);
+}
+
+const STOREFRONT_CSS = `@reference "tailwindcss/theme.css";
+@import "tailwindcss/utilities.css" layer(utilities) source(none);
+@config "@commercebuild/extension/config/tailwind.config.js";
+@source "../";
+@source not "../admin";
+`;
+
+const ADMIN_CSS = `@reference "tailwindcss/theme.css";
+@import "tailwindcss/utilities.css" layer(utilities) source(none);
+@config "@commercebuild/extension/config/tailwind.config.js";
+@source "../";
+@source "../../shared";
+`;
+
+function scaffold() {
+  write(
+    "commercebuild.json",
+    JSON.stringify({
+      id: "fixture",
+      name: "Fixture",
+      type: "extension",
+      description: "",
+      version: "0.0.1",
+      cbApiVersion: "^0.6",
+    }),
+  );
+  write(
+    "src/index.ts",
+    'import "./styles/index.css";\nexport * as components from "./cms";\nexport * as pages from "./pages";\n',
+  );
+  write("src/cms/index.ts", "export {};\n");
+  write("src/pages/index.ts", 'export * as Shop from "./shop";\n');
+  write(
+    "src/pages/shop.tsx",
+    'import React from "react";\nimport { shared } from "../shared/util";\nexport default function Shop() {\n  const [n] = React.useState(0);\n  return <div className="p-1">{shared()}{n}</div>;\n}\n',
+  );
+  write(
+    "src/shared/util.tsx",
+    'import React from "react";\nexport function shared() {\n  return <span className="p-2">shared</span>;\n}\n',
+  );
+  write("src/styles/index.css", STOREFRONT_CSS);
+  write(
+    "src/admin/index.ts",
+    'import "./styles/index.css";\nexport * as adminPages from "./pages";\n',
+  );
+  write("src/admin/pages/index.ts", 'export * as Dashboard from "./dashboard";\n');
+  write(
+    "src/admin/pages/dashboard.tsx",
+    'import React from "react";\nimport { getFirestore } from "firebase/firestore";\nimport { shared } from "../../shared/util";\nexport default function Dashboard() {\n  const [n] = React.useState(0);\n  return <div className="p-3">{String(!!getFirestore)}{shared()}{n}</div>;\n}\n',
+  );
+  write("src/admin/styles/index.css", ADMIN_CSS);
+
+  // The fixture resolves the package (for @config) and tailwindcss (for
+  // the layer stylesheets) through symlinks into this repo's own
+  // installation — no network install.
+  const nm = path.join(fixture, "node_modules");
+  mkdirSync(path.join(nm, "@commercebuild"), { recursive: true });
+  symlinkSync(pkgRoot, path.join(nm, "@commercebuild", "extension"));
+  // pnpm layout: this entry is itself a symlink into the store — a
+  // symlink to a symlink resolves fine.
+  symlinkSync(
+    path.join(pkgRoot, "node_modules", "tailwindcss"),
+    path.join(nm, "tailwindcss"),
+  );
+}
+
+function build(env = {}) {
+  execFileSync(viteBin, ["build", "--config", viteConfig], {
+    cwd: fixture,
+    stdio: "pipe",
+    env: { ...process.env, ...env },
+  });
+}
+
+function dist(name) {
+  return readFileSync(path.join(fixture, "dist", name), "utf8");
+}
+
+try {
+  scaffold();
+
+  // --- Dual build: storefront first, then admin (matching cli.js). ---
+  build();
+  build({ CB_BUILD_TARGET: "admin" });
+
+  for (const file of [
+    "index.js",
+    "style.css",
+    "admin.js",
+    "admin.css",
+    "cb-manifest.json",
+  ]) {
+    assert.ok(
+      existsSync(path.join(fixture, "dist", file)),
+      `dist/${file} exists after the dual build`,
+    );
+  }
+
+  // Per-target CSS scan scopes (p-1=storefront page, p-2=shared, p-3=admin).
+  const style = dist("style.css");
+  assert.match(style, /\.p-1\b/, "style.css has storefront utilities");
+  assert.match(style, /\.p-2\b/, "style.css has shared utilities");
+  assert.doesNotMatch(style, /\.p-3\b/, "style.css has NO admin utilities");
+  const adminCss = dist("admin.css");
+  assert.doesNotMatch(adminCss, /\.p-1\b/, "admin.css has NO storefront utilities");
+  assert.match(adminCss, /\.p-2\b/, "admin.css has shared utilities");
+  assert.match(adminCss, /\.p-3\b/, "admin.css has admin utilities");
+
+  // Manifest merge: storefront fields retained, admin.hostLibs per-bundle.
+  const manifest = JSON.parse(dist("cb-manifest.json"));
+  assert.equal(manifest.cbApiVersion, "^0.6");
+  assert.deepEqual(manifest.hostLibs, ["react"]);
+  assert.deepEqual(manifest.admin, {
+    hostLibs: ["firebase/firestore", "react"],
+  });
+
+  // Both bundles carry the meta banner and the shared global protocol.
+  assert.match(dist("admin.js"), /__CBExtensionMeta/);
+  assert.match(dist("admin.js"), /CBExtension/);
+  assert.match(dist("index.js"), /__CBExtensionMeta/);
+
+  // --- Boundary rules fail the build, all three directions. ---
+  const violations = [
+    [
+      "src/admin/pages/bad.ts",
+      'export { x } from "../../cms/bad-target";\n',
+      "src/admin/pages/index.ts",
+      './bad',
+    ],
+    [
+      "src/pages/bad.ts",
+      'export { helper } from "../admin/helper";\n',
+      "src/pages/index.ts",
+      './bad',
+    ],
+    [
+      "src/shared/bad.ts",
+      'export { helper } from "../admin/helper";\n',
+      "src/pages/index.ts",
+      '../shared/bad',
+    ],
+  ];
+  write("src/cms/bad-target.ts", "export const x = 1;\n");
+  write("src/admin/helper.ts", "export const helper = 1;\n");
+  for (const [file, source, barrel, specifier] of violations) {
+    write(file, source);
+    const original = readFileSync(path.join(fixture, barrel), "utf8");
+    write(barrel, `${original}export * from "${specifier}";\n`);
+    let failed = false;
+    try {
+      build(file.startsWith("src/admin/") ? { CB_BUILD_TARGET: "admin" } : {});
+    } catch (err) {
+      failed = true;
+      assert.match(
+        String(err.stderr ?? err),
+        /Forbidden import/,
+        `${file} violation names the rule`,
+      );
+    }
+    assert.ok(failed, `${file} boundary violation fails the build`);
+    rmSync(path.join(fixture, file));
+    write(barrel, original);
+  }
+
+  // --- Admin-less project: classic three artifacts, nothing extra. ---
+  rmSync(path.join(fixture, "src/admin"), { recursive: true });
+  rmSync(path.join(fixture, "dist"), { recursive: true });
+  build();
+  assert.ok(existsSync(path.join(fixture, "dist", "index.js")));
+  assert.ok(existsSync(path.join(fixture, "dist", "style.css")));
+  assert.ok(!existsSync(path.join(fixture, "dist", "admin.js")));
+  assert.ok(!existsSync(path.join(fixture, "dist", "admin.css")));
+  assert.equal(JSON.parse(dist("cb-manifest.json")).admin, undefined);
+  // Admin invocation without an admin entry is an explicit error.
+  assert.throws(
+    () => build({ CB_BUILD_TARGET: "admin" }),
+    /src\/admin\/index\.ts/,
+  );
+
+  console.log("extension dual-build integration test: OK");
+} finally {
+  rmSync(fixture, { recursive: true, force: true });
+}

package/types/css.d.ts

@@ -0,0 +1,7 @@
+// Stylesheet imports are side-effect only: the build extracts them into
+// the bundle's CSS artifact (style.css / admin.css) and they resolve to
+// no JS value. This ambient declaration is what lets the entry barrels'
+// `import "./styles/index.css"` type-check — newer TypeScript
+// (noUncheckedSideEffectImports) errors on side-effect imports that
+// resolve to neither a module nor a type declaration.
+declare module "*.css";

package/types/global.d.ts

@@ -8,7 +8,12 @@ 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, customer_v1 } from "@commercebuild/platform-api";
+import {
+  cart_v2,
+  catalog_v1,
+  Platform,
+  customer_v1,
+} from "@commercebuild/platform-api";
 import * as icons from "lucide-react";
 import * as uis from "@commercebuild/ui";
 import {
@@ -23,7 +28,7 @@ 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;
+  tmsg: (kk: string) => string;
   tlink: (uri: string) => string;
   talink: (uri: string) => string;
   trlink: (uri: string) => string;
@@ -43,6 +48,7 @@ type CartRequestItem = Omit<
   unitPrice?: number;
   detailPageUrl?: string;
 };
+type PostItemsSearchRequest = catalog_v1.PostItemsSearchRequest;
 type PostItemsSearchItem = catalog_v1.PostItemsSearchItem;
 type PostItemsSearchResponse = catalog_v1.PostItemsSearchResponse;
 type GetItemDetailResponse = catalog_v1.GetItemDetailResponse;
@@ -76,12 +82,95 @@ declare function AddToCart({
   fullWidth,
 }: AddToCartProps): React.JSX.Element;
 
+interface GroupSectionItem {
+  sectionKey: "group";
+  id?: string;
+  visible?:
+    | boolean
+    | {
+        value?: boolean;
+        default?: boolean;
+      };
+  gap?: string;
+  justify?: string;
+  align?: string;
+  items?: SectionItem[];
+}
+interface LeafSectionItem {
+  sectionKey: string;
+  id?: string;
+  visible?:
+    | boolean
+    | {
+        value?: boolean;
+        default?: boolean;
+      };
+}
+/**
+ * A leaf section that renders authored rich-text using the variable
+ * resolution pipeline. Carried by the `customText` discriminator so the
+ * variant-specific fields stay off the shared base.
+ */
+interface CustomTextLeafSectionItem extends LeafSectionItem {
+  sectionKey: "customText";
+  customLabel?: string;
+  customLabelVisible?: boolean;
+  customValue?: string;
+}
+type SectionItem =
+  | GroupSectionItem
+  | CustomTextLeafSectionItem
+  | LeafSectionItem;
+
+interface StandardCardLeafField extends LeafSectionItem {
+  sectionKey:
+    | "image"
+    | "item_code"
+    | "title"
+    | "stock"
+    | "price"
+    | "add_to_cart";
+}
+type CardLeafField = StandardCardLeafField | CustomTextLeafSectionItem;
+type CardField = CardLeafField | GroupSectionItem;
+/**
+ * One column of a list-view row. Columns sit left-to-right; the entries inside
+ * a column stack vertically, and a `group` entry puts several of them on one
+ * row (the same primitive the tile card uses).
+ */
+interface CardColumn {
+  id?: string;
+  visible?:
+    | boolean
+    | {
+        value?: boolean;
+        default?: boolean;
+      };
+  /** Key into LIST_COLUMN_WIDTH. */
+  width?: string;
+  /** Key into LIST_COLUMN_ALIGN. */
+  align?: string;
+  items?: CardField[];
+}
+
 declare function CategoryProduct({
   product,
   imagePriority,
+  schemeKey,
+  fields,
+  listColumns,
+  imageSizes,
 }: {
   product: PostItemsSearchItem;
   imagePriority?: boolean;
+  /** Product Card theme scheme chosen on the listing block. */
+  schemeKey?: string;
+  /** Per-block field override; undefined leaves the scheme in charge. */
+  fields?: CardField[];
+  /** List-view columns; undefined renders the stacked tile card. */
+  listColumns?: CardColumn[];
+  /** Overrides the card's default `sizes` (list thumbnails are much smaller). */
+  imageSizes?: string;
 }): React.JSX.Element;
 
 declare function CategoryBreadcrumb({
@@ -102,13 +191,22 @@ declare function CategorySidebar({
   aggregation,
   currentFilters,
   isDrawer,
+  sections,
+  showCounts,
 }: {
   category: Category;
   url: string;
   aggregation?: PostItemsSearchResponse["aggregation"];
   currentFilters: Record<string, string[]>;
   isDrawer?: boolean;
-}): React.JSX.Element | null;
+  /**
+   * Structural elements to render, in order, from the listing block's
+   * `filterSections` repeater. Undefined keeps the historic order.
+   */
+  sections?: string[];
+  /** Show the match count beside each facet name and value. */
+  showCounts?: boolean;
+}): React__default.JSX.Element | null;
 
 declare function CategorySort({
   url,
@@ -125,9 +223,36 @@ declare function CategorySort({
 declare function CategoryProducts({
   hasSiderbar,
   items,
+  columnsClass,
+  schemeKey,
+  fields,
+  listColumns,
+  autoScroll,
+  total,
 }: {
   hasSiderbar?: boolean;
   items: PostItemsSearchItem[];
+  /**
+   * Literal Tailwind column classes from the listing block's frozen map.
+   * Never interpolated — `grid-cols-${n}` compiles to nothing.
+   * The default reproduces the pre-CMS grid exactly.
+   */
+  columnsClass?: string;
+  schemeKey?: string;
+  fields?: CardField[];
+  /**
+   * List-view columns. Non-empty switches the grid to a single column of rows
+   * and hands each card its own layout — `columnsClass` is then unused.
+   */
+  listColumns?: CardColumn[];
+  /**
+   * The route's own search request, replayed a page at a time as the shopper
+   * scrolls. `null` keeps the grid to the server-rendered page, which is what
+   * page-number pagination wants.
+   */
+  autoScroll?: PostItemsSearchRequest | null;
+  /** Total matches, so auto-scroll knows when to stop. */
+  total?: number;
 }): React.JSX.Element;
 
 declare function CategoryProductsPageSize({
@@ -149,13 +274,120 @@ declare function ProductTitle({
   product: GetItemDetailResponse;
 }): React.JSX.Element;
 
+/**
+ * Shared Constants Types
+ *
+ * Type definitions for constants used across the theme editor.
+ * These establish common interfaces for Tailwind CSS constants and configuration.
+ */
+
+/**
+ * Box Shadow Config Interface
+ * Configuration for box shadow utilities
+ * Consolidated from cms/utils/tailwind-utils.ts
+ */
+interface BoxShadowConfig {
+  preset?: string;
+  custom?: {
+    offsetX: string;
+    offsetY: string;
+    blurRadius: string;
+    spreadRadius?: string;
+    color: string;
+    opacity?: string;
+    inset?: boolean;
+  };
+  useCustom?: boolean;
+}
+
+/**
+ * Border Width Interface
+ * Interface for border width configuration
+ * Consolidated from cms/components/property/border-controller.tsx
+ */
+interface BorderWidth {
+  top: string;
+  right: string;
+  bottom: string;
+  left: string;
+}
+/**
+ * Border Radius Interface
+ * Interface for border radius configuration
+ * Consolidated from cms/components/property/border-controller.tsx
+ */
+interface BorderRadius {
+  topLeft: string;
+  topRight: string;
+  bottomRight: string;
+  bottomLeft: string;
+}
+/**
+ * Border Interface
+ * Interface for border configuration
+ * Consolidated from cms/components/property/border-controller.tsx
+ */
+interface Border {
+  width: BorderWidth;
+  style: string;
+  color: string;
+  /** Border color opacity 0–100 (UN-3049). Optional; undefined ⇒ fully opaque. */
+  opacity?: string;
+  radius: BorderRadius;
+}
+
+type ImageFit = "cover" | "contain" | "fill" | "none";
+/** Aspect vocabulary shared with the Product Card scheme (UN-3049). */
+type ImageAspect = "square" | "landscape" | "portrait" | "wide";
+interface ImageSurfaceSettings {
+  border?: Border;
+  shadow?: BoxShadowConfig;
+  bgColor?: string;
+}
+
 type ThumbnailPosition = "top" | "right" | "bottom" | "left";
+/**
+ * How the desktop thumbnail strip presents itself (UN-3295).
+ *
+ * `carousel` is the shipped behaviour: one scrollable rail with prev/next.
+ * `stack` shows a fixed number of thumbnails and expands the rest in place.
+ * Stack applies to `top` and `bottom` only — a `left`/`right` strip is one
+ * `--thumb-w` column wide (80px by default), too narrow for the control.
+ */
+type ThumbnailLayout = "carousel" | "stack";
+/** Main-image controls (UN-3285): presentation + its own Border/Shadow. */
+interface ProductImageDisplaySettings extends ImageSurfaceSettings {
+  aspect?: ImageAspect;
+  fit?: ImageFit;
+}
+/**
+ * Thumbnail controls (UN-3285). Width and height are independent px values;
+ * both default to the legacy 80px box. Desktop-only (sm+) — on mobile the
+ * carousel IS the gallery and its slides stay full-width.
+ */
+interface ProductThumbnailDisplaySettings extends ImageSurfaceSettings {
+  width?: number | "";
+  height?: number | "";
+  /** Gap between thumbnails, px. Unset = the 10px default; explicit 0 holds. */
+  gap?: number | "";
+  /** Gap between the strip and the main image, px. Unset = the 10px default. */
+  imageGap?: number | "";
+  fit?: ImageFit;
+  /** Desktop strip presentation (UN-3295). Unset = the shipped carousel. */
+  layout?: ThumbnailLayout;
+  /** Thumbnails shown before "Show more", stack layout only. Unset = 4. */
+  showMoreAfter?: number | "";
+}
 declare const ProductImages: ({
   product,
   thumbnailPosition,
+  imageSettings,
+  thumbnailSettings,
 }: {
   product: GetItemDetailResponse;
   thumbnailPosition?: ThumbnailPosition;
+  imageSettings?: ProductImageDisplaySettings;
+  thumbnailSettings?: ProductThumbnailDisplaySettings;
 }) => React.JSX.Element;
 
 declare function ProductPrice({
@@ -306,31 +538,27 @@ interface FirebaseConnectionConfig {
   messagingSenderId?: string;
   appId?: string;
   measurementId?: string;
+  /**
+   * Firestore database to use when the project has more than one. NOT part
+   * of the console's firebaseConfig snippet — the SDK has no notion of a
+   * default database in its options, so this rides along as an extra key
+   * (initializeApp keeps unknown keys on `app.options`) and the app passes
+   * it to `getFirestore(app, databaseId)`. Empty/absent = `(default)`.
+   */
+  databaseId?: string;
 }
 
 /**
- * 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.
+ * Shared implementation — see @commercebuild/extension-host-libs
+ * (extension-scope.tsx). Only the TYPE re-exports below stay special:
+ * they are re-exported into the generated author-facing declaration,
+ * and tsup's dts build force-externalizes anything imported by package
+ * name (a storefront dependency) — authors can't install the workspace
+ * package, so its types must inline via a RELATIVE path. A type-only
+ * import is erased at runtime, so the bundler never sees this path;
+ * runtime members keep importing the package normally.
  */
 
-/**
- * The provider type family (config shapes, the ResolvedConnection
- * discriminated union) is owned by the provider registry in
- * @commercebuild/extension-host-libs — one place declares them for the
- * storefront, storeadmin and the config JSON Schema alike. This module
- * re-exports the contract-facing names.
- */
 type CbFirebaseConfig = FirebaseConnectionConfig;
 
 /**
@@ -567,7 +795,9 @@ interface CbHostApi {
      * 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)).
+     * to the product entry points. Honour a named database:
+     * `const id = (app.options as { databaseId?: string }).databaseId;`
+     * `const db = id ? getFirestore(app, id) : getFirestore(app);`
      */
     useFirebaseApp: (
       connection?: string,

package/types/index.d.ts

@@ -1 +1,2 @@
 import "./global";
+import "./css";