@tribe-nest/forge 3.11.0 → 3.14.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.11.0",
+  "version": "3.14.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Forge — the headless React SDK for building custom TribeNest creator sites (the Hydrogen of TribeNest). Exposes the backend (memberships, commerce, gated content, ticketing, courses, booking, auth) as data + behavior primitives.",
+  "description": "Forge \u2014 the headless React SDK for building custom TribeNest creator sites (the Hydrogen of TribeNest). Exposes the backend (memberships, commerce, gated content, ticketing, courses, booking, auth) as data + behavior primitives.",
   "exports": {
     ".": "./src/index.ts",
     "./ui": "./src/ui/index.ts",

package/src/contexts/CartContext.tsx

@@ -31,7 +31,19 @@ export type CartItem = {
   payWhatYouWant: boolean;
   color?: string;
   size?: string;
-  deliveryType?: ProductDeliveryType;
+  /**
+   * REQUIRED, and deliberately so.
+   *
+   * Checkout decides whether to ask for a shipping address from this field on
+   * the cart LINE. While it was optional, a caller that forgot it produced an
+   * item that silently read as non-physical — the Craft music page did exactly
+   * that, and a vinyl reached checkout with the buyer never asked where to send
+   * the record. A missing address is not recoverable after payment.
+   *
+   * Making it required turns that into a compile error instead of a defect
+   * nobody sees until an order arrives with nowhere to ship it.
+   */
+  deliveryType: ProductDeliveryType;
   /** Set automatically from `?addonFor=` — see `addToCart`. */
   attachedTo?: AttachedTo;
 };

package/src/data/queries/useProducts.ts

@@ -1,23 +1,39 @@
-import type { IPublicProduct, PaginatedData, ProductCategory } from "../../types/models";
+import type { IPublicProduct, PaginatedData, ProductType } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useQuery } from "@tanstack/react-query";
 
 export interface GetProductsParams {
   query?: string;
-  category?: ProductCategory[];
+  /** What the products ARE. Renamed from `category` in the taxonomy split. */
+  productType?: ProductType[];
+  /**
+   * @deprecated The old name for `productType`. Still honoured, and honoured
+   * deliberately: callers usually build this object in a `useMemo` and pass it
+   * as a VARIABLE, which turns off TypeScript's excess-property check — so a
+   * caller left on the old name compiles clean and silently loses its filter,
+   * listing the whole catalogue on a page meant to show one type. Dropping the
+   * key would make that failure mode look like working code.
+   */
+  category?: ProductType[];
+  /**
+   * A creator-authored category. Descendant-inclusive: filtering on "Apparel"
+   * returns everything filed beneath it, at any depth.
+   */
+  categoryId?: string;
+  collectionId?: string;
   page?: number;
   releaseType?: string;
 }
 
-/** Featured products for the profile, optionally filtered by category. */
-export function useFeaturedProducts(category?: ProductCategory) {
+/** Featured products for the profile, optionally filtered by product type. */
+export function useFeaturedProducts(productType?: ProductType) {
   const { client, profileId } = useForge();
 
   return useQuery<IPublicProduct[]>({
-    queryKey: ["featured-products", profileId, category],
+    queryKey: ["featured-products", profileId, productType],
     queryFn: async () => {
       const res = await client.get("/public/products/featured", {
-        params: { profileId, category },
+        params: { profileId, productType },
       });
       return res.data;
     },
@@ -34,7 +50,9 @@ export function useGetProducts(params?: GetProductsParams, enabled = true) {
       const res = await client.get("/public/products", {
         params: {
           profileId: profileId,
-          category: params?.category,
+          productType: params?.productType ?? params?.category,
+          categoryId: params?.categoryId,
+          collectionId: params?.collectionId,
           page: params?.page || 1,
           limit: 10,
           filter: {
@@ -90,11 +108,21 @@ export function useGetProductsByIds(productIds: string[]) {
   });
 }
 
-export function useGetProductCategories() {
+/**
+ * The product TYPES this creator has products in, plus a synthetic "Coaching"
+ * entry when they sell coaching. This is what the storefront's top-level tabs
+ * are built from.
+ *
+ * The endpoint keeps its `/categories` path: every code-site published before
+ * the taxonomy split calls it and reads this exact payload, and the hook name
+ * is what changed. For the creator's OWN categories use
+ * {@link useProductCategories}.
+ */
+export function useGetProductTypes() {
   const { client, profileId } = useForge();
 
-  return useQuery<{ title: ProductCategory; description: string }[]>({
-    queryKey: ["product-categories", profileId],
+  return useQuery<{ title: string; description: string }[]>({
+    queryKey: ["product-types", profileId],
     queryFn: async () => {
       const res = await client.get("/public/products/categories", {
         params: {
@@ -106,3 +134,69 @@ export function useGetProductCategories() {
     enabled: !!profileId && !!client,
   });
 }
+
+/**
+ * @deprecated Renamed to {@link useGetProductTypes}, which is what it always
+ * returned. Kept so a site built against an earlier Forge keeps compiling; it
+ * will go in a future major.
+ */
+export const useGetProductCategories = useGetProductTypes;
+
+/** A node in the creator's category tree. Children are nested, never repeated at the root. */
+export interface IPublicProductCategory {
+  id: string;
+  title: string;
+  slug: string;
+  description: string | null;
+  parentId: string | null;
+  position: number;
+  productCount: number;
+  children: IPublicProductCategory[];
+}
+
+export interface IPublicProductCollection {
+  id: string;
+  title: string;
+  slug: string;
+  description: string | null;
+  isFeatured: boolean;
+  position: number;
+  productCount: number;
+}
+
+/**
+ * The creator's OWN category tree — what they organise their store by, as
+ * opposed to {@link useGetProductTypes} which is what their products ARE.
+ *
+ * Counts are descendant-inclusive, so "Apparel" reports everything beneath it.
+ */
+export function useProductCategories() {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicProductCategory[]>({
+    queryKey: ["public-product-categories", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/products/product-categories", {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** The creator's curated collections — drops, seasons, hand-picked edits. */
+export function useProductCollections() {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicProductCollection[]>({
+    queryKey: ["public-product-collections", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/products/product-collections", {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}

package/src/index.ts

@@ -26,6 +26,11 @@ export * from "./types";
 export { AudioPlayerProvider, useAudioPlayer } from "./contexts/AudioPlayerContext";
 export type { AudioTrack } from "./contexts/AudioPlayerContext";
 export { CartProvider, useCart } from "./contexts/CartContext";
+// Variant selection, shared with the Craft themes in frontend-shared the same
+// way the cart and audio player are — so a code site and a Craft site cannot
+// disagree about which version a buyer picked.
+export { useVariantSelection } from "./ui/headless/useVariantSelection";
+export type { VariantAxis, VariantAxisValue } from "./ui/headless/useVariantSelection";
 export type { CartItem, TicketCartItem, AttachedTo } from "./contexts/CartContext";
 export {
   ACCESS_TOKEN_KEY,

package/src/types/models.ts

@@ -584,15 +584,35 @@ export type IMedia = {
   previewStatus?: string | null;
 };
 
-export enum ProductCategory {
+/**
+ * What a product IS, which decides how it renders: Music shows a track list,
+ * Merch shows variants, Digital is a download, Service is fulfilled by the
+ * creator.
+ *
+ * Renamed from `ProductType` in the taxonomy split. It used to be the only
+ * taxonomy a product had, pointing into a four-row table shared by every artist
+ * on the platform — so no creator could organise their own store. Creator
+ * authored categories and collections are separate now (`categories`,
+ * `collections` on {@link IPublicProduct}).
+ *
+ * Coaching and Course are gone: they are separate surfaces with their own
+ * tables and never appeared in `products`. The storefront still shows a
+ * Coaching tab — see {@link STOREFRONT_COACHING_TAB}.
+ */
+export enum ProductType {
   Music = "Music",
   Merch = "Merch",
   Digital = "Digital",
   Service = "Service",
-  Coaching = "Coaching",
-  Course = "Course",
 }
 
+/**
+ * The storefront's product-type navigation is not purely {@link ProductType}: a
+ * creator with coaching products gets a "Coaching" tab alongside them, though
+ * no product row is ever of that type.
+ */
+export const STOREFRONT_COACHING_TAB = "Coaching" as const;
+
 export type PostType = "image" | "video" | "audio" | "poll";
 
 export type IPublicComment = {
@@ -658,11 +678,36 @@ export type IPublicProductVariant = {
   payWhatYouWant?: boolean;
   payWhatYouWantMaximum?: number;
   upcCode: string;
+  /**
+   * Where this variant sits on its product's axes, in the axes' own order.
+   *
+   * This is what the picker reads. `color` and `size` below are the two
+   * hardcoded axes that predate the option library — they cannot express a
+   * third ("Format: MP3 / WAV / Stems"), and one product's `color` may hold a
+   * hex while another's holds a name, because three different writers filled
+   * it. Prefer `options`.
+   */
+  options: IPublicVariantOption[];
+  /** @deprecated Read `options`. */
   color: string;
+  /** @deprecated Read `options`. */
   size: string;
+  /** Whether a buyer of this version also receives the downloadable files. */
+  includesDownload?: boolean;
   availabilityStatus: "active" | "temporarily_out_of_stock";
 };
 
+export type IPublicVariantOption = {
+  optionValueId: string;
+  optionTypeId: string;
+  /** "Colour", "Size", "Format" — as the creator named it. */
+  axis: string;
+  value: string;
+  /** Set only when the value genuinely is a colour; a guessed hex would lie. */
+  swatchHex: string | null;
+  displayType: string;
+};
+
 // ---- Reviews -------------------------------------------------------------------
 
 /** Reviewable entity types (v1 — events deferred). */
@@ -750,8 +795,12 @@ export type IPublicProduct = {
   slug?: string;
   title: string;
   description: string;
-  category: ProductCategory;
+  productType: ProductType;
   media: IMedia[];
+  /** Creator-authored categories this product is filed under. Direct only — a parent category resolves its descendants server-side. */
+  categories?: { id: string; title: string; slug: string; parentId: string | null }[];
+  /** Curated collections this product belongs to, with its position in each. */
+  collections?: { id: string; title: string; slug: string; isFeatured: boolean; position: number }[];
   variants: IPublicProductVariant[];
   artist: string;
   credits: string;

package/src/ui/headless/index.ts

@@ -76,3 +76,4 @@ export * from "./work";
 // Funnel instrumentation — wrap a multi-step flow to record step-through and
 // drop-off on the first-party analytics feed.
 export * from "./funnel";
+export * from "./useVariantSelection";

package/src/ui/headless/useVariantSelection.ts

@@ -0,0 +1,138 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { IPublicProductVariant } from "../../types/models";
+
+/**
+ * Picking a version of a product, on any number of axes.
+ *
+ * This replaces a hardcoded colour → size cascade. That cascade could not
+ * express a third axis, so an album sold as MP3 / WAV / Stems had nowhere to put
+ * "Format", and it read `variant.color` — a column one writer fills with a hex
+ * and another with a name.
+ *
+ * The cascade itself is kept, generalised: each axis is narrowed by the axes
+ * BEFORE it. Picking "Black" leaves only the sizes that exist in black, exactly
+ * as before, and picking "FLAC" would leave only the editions pressed in FLAC.
+ * Axis order comes from the server, which sorts by the axis's own position, so
+ * every variant of a product presents its options the same way round.
+ *
+ * Shared by BOTH rendering surfaces. The Craft themes in `frontend-shared`
+ * import it from here, the way they already import the cart and audio player —
+ * the dependency runs one way, so the selection rule cannot drift between a
+ * code site and a Craft site even though their markup is unrelated.
+ */
+
+export type VariantAxisValue = {
+  optionValueId: string;
+  value: string;
+  /** Only set when the value genuinely is a colour. Render a swatch if present. */
+  swatchHex: string | null;
+  /** False when every variant carrying it is out of stock. */
+  isAvailable: boolean;
+};
+
+export type VariantAxis = {
+  optionTypeId: string;
+  /** "Colour", "Size", "Format" — as the creator named it. */
+  axis: string;
+  displayType: string;
+  values: VariantAxisValue[];
+};
+
+type Selection = Record<string, string | undefined>;
+
+const optionFor = (variant: IPublicProductVariant, optionTypeId: string) =>
+  variant.options?.find((option) => option.optionTypeId === optionTypeId);
+
+/** Does this variant match every selection made on the axes listed? */
+const matches = (variant: IPublicProductVariant, selection: Selection, upToAxes: string[]) =>
+  upToAxes.every((optionTypeId) => {
+    const chosen = selection[optionTypeId];
+    if (!chosen) return true;
+    return optionFor(variant, optionTypeId)?.optionValueId === chosen;
+  });
+
+export function useVariantSelection(variants: IPublicProductVariant[]) {
+  const [selection, setSelection] = useState<Selection>({});
+
+  // The axes this product uses, in server order, deduped. Built from the
+  // variants themselves rather than a separate list, so a product can never
+  // advertise an axis none of its versions sits on.
+  const axisOrder = useMemo(() => {
+    const seen: { optionTypeId: string; axis: string; displayType: string }[] = [];
+    for (const variant of variants ?? []) {
+      for (const option of variant.options ?? []) {
+        if (!seen.some((s) => s.optionTypeId === option.optionTypeId)) {
+          seen.push({ optionTypeId: option.optionTypeId, axis: option.axis, displayType: option.displayType });
+        }
+      }
+    }
+    return seen;
+  }, [variants]);
+
+  const axes: VariantAxis[] = useMemo(() => {
+    return axisOrder.map((axis, index) => {
+      // Narrowed by the axes before it, and only those — an axis must not be
+      // constrained by a LATER pick, or choosing a size would start hiding
+      // colours and the buyer could reach a state with nothing selectable.
+      const earlier = axisOrder.slice(0, index).map((a) => a.optionTypeId);
+      const candidates = (variants ?? []).filter((variant) => matches(variant, selection, earlier));
+
+      const values: VariantAxisValue[] = [];
+      for (const variant of candidates) {
+        const option = optionFor(variant, axis.optionTypeId);
+        if (!option) continue;
+        const existing = values.find((v) => v.optionValueId === option.optionValueId);
+        const isActive = variant.availabilityStatus === "active";
+        if (existing) {
+          existing.isAvailable = existing.isAvailable || isActive;
+        } else {
+          values.push({
+            optionValueId: option.optionValueId,
+            value: option.value,
+            swatchHex: option.swatchHex,
+            isAvailable: isActive,
+          });
+        }
+      }
+      return { ...axis, values };
+    });
+  }, [axisOrder, variants, selection]);
+
+  const select = useCallback(
+    (optionTypeId: string, optionValueId: string) => {
+      setSelection((current) => {
+        const index = axisOrder.findIndex((a) => a.optionTypeId === optionTypeId);
+        const next: Selection = { ...current, [optionTypeId]: optionValueId };
+        // Changing an axis invalidates everything narrowed by it. Keeping a
+        // stale later pick is how you end up "selecting" a variant that does
+        // not exist — the buyer sees Black/XL highlighted and the button dead.
+        for (const later of axisOrder.slice(index + 1)) next[later.optionTypeId] = undefined;
+        return next;
+      });
+    },
+    [axisOrder],
+  );
+
+  const selectedVariant = useMemo(() => {
+    // A product with no axes has exactly one version — every digital release in
+    // the catalogue before formats existed.
+    if (axisOrder.length === 0) {
+      return variants?.find((v) => v.isDefault) ?? variants?.[0];
+    }
+    if (axisOrder.some((a) => !selection[a.optionTypeId])) return undefined;
+    return (variants ?? []).find((variant) =>
+      axisOrder.every((a) => optionFor(variant, a.optionTypeId)?.optionValueId === selection[a.optionTypeId]),
+    );
+  }, [axisOrder, selection, variants]);
+
+  // Walk the axes in order and pre-pick the first value that is actually in
+  // stock, falling back to the first at all so the page is never blank.
+  useEffect(() => {
+    const missing = axes.find((axis) => !selection[axis.optionTypeId] && axis.values.length > 0);
+    if (!missing) return;
+    const first = missing.values.find((v) => v.isAvailable) ?? missing.values[0];
+    setSelection((current) => ({ ...current, [missing.optionTypeId]: first.optionValueId }));
+  }, [axes, selection]);
+
+  return { axes, selection, select, selectedVariant, hasOptions: axisOrder.length > 0 };
+}

package/src/ui/index.ts

@@ -65,6 +65,7 @@ export { ContactForm, type ContactFormProps } from "./styled/ContactForm";
 export { Paywall, type PaywallProps } from "./styled/Paywall";
 export { ReactionBar, type ReactionBarProps } from "./styled/ReactionBar";
 export { ProductGrid, type ProductGridProps } from "./styled/ProductGrid";
+export { ProductBrowseNav, type ProductBrowseNavProps } from "./styled/ProductBrowseNav";
 export { Addons, type AddonsProps } from "./styled/Addons";
 export { BundleConfirmation, type BundleConfirmationProps } from "./styled/BundleConfirmation";
 export { ProductDetail, type ProductDetailProps } from "./styled/ProductDetail";

package/src/ui/styled/ProductBrowseNav.tsx

@@ -0,0 +1,212 @@
+import { useState } from "react";
+import {
+  useProductCategories,
+  useProductCollections,
+  type IPublicProductCategory,
+} from "../../data/queries/useProducts";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { Loading } from "./Loading";
+
+export interface ProductBrowseNavProps {
+  /** The currently browsed category, so the nav can mark it. */
+  activeCategoryId?: string;
+  activeCollectionId?: string;
+  /**
+   * Where a category leads. Router-agnostic on purpose: Forge has no router,
+   * so the host decides the path.
+   */
+  hrefForCategory?: (category: IPublicProductCategory) => string;
+  hrefForCollection?: (collection: { id: string; slug: string; title: string }) => string;
+  onSelectCategory?: (category: IPublicProductCategory) => void;
+  onSelectCollection?: (collection: { id: string; slug: string; title: string }) => void;
+  /** Hide collections and show only the category tree, or vice versa. */
+  show?: "all" | "categories" | "collections";
+  /** Show only collections the creator marked as featured. */
+  featuredCollectionsOnly?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+/**
+ * Storefront navigation over the creator's OWN taxonomy.
+ *
+ * Two things it deliberately does not do:
+ *
+ * - **It does not show product types.** Music / Merch / Digital / Service is
+ *   what a product IS; this is how the creator chose to shelve their catalogue.
+ *   Mixing them into one list is the conflation the taxonomy split undid.
+ * - **It does not hide empty branches by counting children.** The counts are
+ *   descendant-inclusive server-side, so a parent with products only in its
+ *   grandchildren still reads as non-empty — which is correct, because browsing
+ *   it returns those products.
+ */
+export function ProductBrowseNav({
+  activeCategoryId,
+  activeCollectionId,
+  hrefForCategory,
+  hrefForCollection,
+  onSelectCategory,
+  onSelectCollection,
+  show = "all",
+  featuredCollectionsOnly = false,
+  className,
+  style,
+}: ProductBrowseNavProps) {
+  const t = useThemeTokens();
+  const categoriesQuery = useProductCategories();
+  const collectionsQuery = useProductCollections();
+  const [expanded, setExpanded] = useState<Set<string>>(new Set());
+
+  const showCategories = show === "all" || show === "categories";
+  const showCollections = show === "all" || show === "collections";
+
+  if (categoriesQuery.isLoading || collectionsQuery.isLoading) return <Loading />;
+
+  const categories = categoriesQuery.data ?? [];
+  const collections = (collectionsQuery.data ?? []).filter((c) =>
+    featuredCollectionsOnly ? c.isFeatured : true,
+  );
+
+  // A creator who has authored no taxonomy gets no nav at all rather than an
+  // empty heading — the storefront should look unchanged until they use it.
+  if (!categories.length && !collections.length) return null;
+
+  const toggle = (id: string) =>
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+
+  const renderCategory = (category: IPublicProductCategory, depth: number): React.ReactNode => {
+    const children = category.children ?? [];
+    const isActive = category.id === activeCategoryId;
+    // A branch containing the active category opens so the reader can see
+    // where they are, without needing to remember the path.
+    const containsActive = (node: IPublicProductCategory): boolean =>
+      node.id === activeCategoryId || (node.children ?? []).some(containsActive);
+    const isOpen = expanded.has(category.id) || containsActive(category);
+
+    const label = (
+      <>
+        <span>{category.title}</span>
+        <span style={{ color: t.muted, fontSize: 12, marginLeft: 8 }}>{category.productCount}</span>
+      </>
+    );
+
+    const linkStyle: React.CSSProperties = {
+      display: "inline-flex",
+      alignItems: "baseline",
+      color: isActive ? t.primary : t.text,
+      fontWeight: isActive ? 600 : 400,
+      textDecoration: "none",
+      background: "none",
+      border: "none",
+      padding: 0,
+      cursor: "pointer",
+      font: "inherit",
+      textAlign: "left",
+    };
+
+    const href = hrefForCategory?.(category);
+
+    return (
+      <li key={category.id} style={{ paddingLeft: depth * 14, listStyle: "none", marginBottom: 6 }}>
+        <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
+          {children.length > 0 && (
+            <button
+              type="button"
+              onClick={() => toggle(category.id)}
+              aria-expanded={isOpen}
+              aria-label={isOpen ? `Collapse ${category.title}` : `Expand ${category.title}`}
+              style={{
+                background: "none",
+                border: "none",
+                cursor: "pointer",
+                color: t.muted,
+                padding: 0,
+                lineHeight: 1,
+                width: 12,
+              }}
+            >
+              {isOpen ? "−" : "+"}
+            </button>
+          )}
+          {children.length === 0 && <span style={{ width: 12 }} />}
+
+          {href ? (
+            <a href={href} style={linkStyle} aria-current={isActive ? "page" : undefined}>
+              {label}
+            </a>
+          ) : (
+            <button type="button" style={linkStyle} onClick={() => onSelectCategory?.(category)}>
+              {label}
+            </button>
+          )}
+        </div>
+
+        {isOpen && children.length > 0 && (
+          <ul style={{ margin: "6px 0 0", padding: 0 }}>
+            {children.map((child) => renderCategory(child, depth + 1))}
+          </ul>
+        )}
+      </li>
+    );
+  };
+
+  const headingStyle: React.CSSProperties = {
+    color: t.muted,
+    fontSize: 12,
+    letterSpacing: "0.08em",
+    textTransform: "uppercase",
+    margin: "0 0 10px",
+  };
+
+  return (
+    <nav className={className} style={{ display: "grid", gap: 24, ...style }} aria-label="Browse the store">
+      {showCategories && categories.length > 0 && (
+        <div>
+          <h2 style={headingStyle}>Categories</h2>
+          <ul style={{ margin: 0, padding: 0 }}>{categories.map((c) => renderCategory(c, 0))}</ul>
+        </div>
+      )}
+
+      {showCollections && collections.length > 0 && (
+        <div>
+          <h2 style={headingStyle}>Collections</h2>
+          <ul style={{ margin: 0, padding: 0 }}>
+            {collections.map((collection) => {
+              const isActive = collection.id === activeCollectionId;
+              const href = hrefForCollection?.(collection);
+              const linkStyle: React.CSSProperties = {
+                color: isActive ? t.primary : t.text,
+                fontWeight: isActive ? 600 : 400,
+                textDecoration: "none",
+                background: "none",
+                border: "none",
+                padding: 0,
+                cursor: "pointer",
+                font: "inherit",
+              };
+              return (
+                <li key={collection.id} style={{ listStyle: "none", marginBottom: 6 }}>
+                  {href ? (
+                    <a href={href} style={linkStyle} aria-current={isActive ? "page" : undefined}>
+                      {collection.title}
+                    </a>
+                  ) : (
+                    <button type="button" style={linkStyle} onClick={() => onSelectCollection?.(collection)}>
+                      {collection.title}
+                    </button>
+                  )}
+                  <span style={{ color: t.muted, fontSize: 12, marginLeft: 8 }}>{collection.productCount}</span>
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      )}
+    </nav>
+  );
+}

package/src/ui/styled/ProductDetail.tsx

@@ -1,7 +1,8 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { Play, Pause, Music, Star } from "lucide-react";
-import { ProductCategory } from "../../types/models";
+import { ProductType } from "../../types/models";
 import type { IPublicProduct, IPublicProductTrack, IPublicProductVariant } from "../../types/models";
+import { useVariantSelection } from "../headless/useVariantSelection";
 import { useGetProduct } from "../../data/queries/useProducts";
 import { useCart } from "../../contexts/CartContext";
 import { useAudioPlayer } from "../../contexts/AudioPlayerContext";
@@ -27,18 +28,34 @@ export interface ProductDetailProps {
   style?: React.CSSProperties;
   /** Server-fetched product used as initial data (SSR), avoids client loading spinner. */
   initialProduct?: IPublicProduct;
+  /**
+   * Make the product's categories/collections links. Router-agnostic, like
+   * `ProductGrid.hrefFor` — Forge has no router, so the host owns the path.
+   * Omit and they render as plain text.
+   */
+  hrefForCategory?: (category: { id: string; slug: string; title: string }) => string;
+  hrefForCollection?: (collection: { id: string; slug: string; title: string }) => string;
 }
 
 const a = (hex: string, al: number) => hex + Math.round(al * 255).toString(16).padStart(2, "0");
 
 /**
- * Drop-in product page. **Music** products (category `Music`) get an album/single
+ * Drop-in product page. **Music** products (productType `Music`) get an album/single
  * preview with per-track playback; everything else — including Digital products
  * (whose downloadable file is stored as a track) — gets the standard product
  * layout. Renders the description as sanitized-by-source HTML with responsive
  * media (no horizontal overflow from embedded video/images).
  */
-export function ProductDetail({ slug, formatAmount, checkoutPath = "/i/checkout", className, style, initialProduct }: ProductDetailProps) {
+export function ProductDetail({
+  slug,
+  formatAmount,
+  checkoutPath = "/i/checkout",
+  className,
+  style,
+  initialProduct,
+  hrefForCategory,
+  hrefForCollection,
+}: ProductDetailProps) {
   const t = useThemeTokens();
   const { data: product, isLoading } = useGetProduct(slug, { initialData: initialProduct });
   const fmt = useAmountFormatter(formatAmount);
@@ -46,14 +63,22 @@ export function ProductDetail({ slug, formatAmount, checkoutPath = "/i/checkout"
   if (isLoading) return <Loading fullPage />;
   if (!product) return <p style={{ color: t.text }}>Product not found.</p>;
 
-  // Classify on the product's category, NOT "has tracks" — a Digital product
+  // Classify on the product's TYPE, NOT "has tracks" — a Digital product
   // stores its download as a track too, so track-presence would misrender it as
   // music (audio player over a PDF, etc.).
-  const isMusic = product.category === ProductCategory.Music;
+  const isMusic = product.productType === ProductType.Music;
   return isMusic ? (
     <MusicDetail product={product} fmt={fmt} checkoutPath={checkoutPath} className={className} style={style} />
   ) : (
-    <StandardDetail product={product} fmt={fmt} checkoutPath={checkoutPath} className={className} style={style} />
+    <StandardDetail
+      product={product}
+      fmt={fmt}
+      checkoutPath={checkoutPath}
+      className={className}
+      style={style}
+      hrefForCategory={hrefForCategory}
+      hrefForCollection={hrefForCollection}
+    />
   );
 }
 
@@ -106,12 +131,16 @@ function StandardDetail({
   checkoutPath,
   className,
   style,
+  hrefForCategory,
+  hrefForCollection,
 }: {
   product: IPublicProduct;
   fmt: (n: number) => string;
   checkoutPath: string;
   className?: string;
   style?: React.CSSProperties;
+  hrefForCategory?: (category: { id: string; slug: string; title: string }) => string;
+  hrefForCollection?: (collection: { id: string; slug: string; title: string }) => string;
 }) {
   const t = useThemeTokens();
   // Inclusive stores caption the price as tax-inclusive (display only).
@@ -120,39 +149,13 @@ function StandardDetail({
   const { add } = useBuy(product, cover, checkoutPath);
   const { isCartOpen } = useCart();
 
-  const [selectedColor, setSelectedColor] = useState<string | null>(null);
-  const [selectedSize, setSelectedSize] = useState<string | null>(null);
   const [quantity, setQuantity] = useState(1);
   const [imageIndex, setImageIndex] = useState(0);
 
-  // Colors that exist across variants (each flagged if it has any in-stock size).
-  const availableColors = useMemo(() => {
-    const colors = Array.from(new Set(product.variants.map((v) => v.color)));
-    return colors
-      .map((color) => ({
-        name: color,
-        hasAvailableSize: product.variants.some((v) => v.color === color && v.availabilityStatus === "active"),
-      }))
-      .filter((c) => c.name);
-  }, [product.variants]);
-
-  // Sizes for the chosen color.
-  const availableSizes = useMemo(() => {
-    if (!selectedColor) return [];
-    return product.variants
-      .filter((v) => v.color === selectedColor)
-      .map((v) => ({ name: v.size, isAvailable: v.availabilityStatus === "active" }))
-      .filter((s) => s.name);
-  }, [selectedColor, product.variants]);
-
-  // Products without color/size options (digital, service, simple physical) just
-  // use the default variant; otherwise the buyer must pick color + size.
-  const hasOptions = availableColors.length > 0;
-  const selectedVariant = useMemo(() => {
-    if (!hasOptions) return product.variants?.find((v) => v.isDefault) ?? product.variants?.[0];
-    if (!selectedColor || !selectedSize) return undefined;
-    return product.variants.find((v) => v.color === selectedColor && v.size === selectedSize);
-  }, [hasOptions, selectedColor, selectedSize, product.variants]);
+  // Any number of axes, narrowed left to right. Was a hardcoded colour → size
+  // cascade, which had nowhere to put "Format" and read a column that holds a
+  // hex from one writer and a name from another.
+  const { axes, selection, select, selectedVariant, hasOptions } = useVariantSelection(product.variants);
 
   // Prefer the selected variant's own images; fall back to the product's.
   const images = useMemo(() => {
@@ -160,19 +163,6 @@ function StandardDetail({
     return vImgs.length > 0 ? vImgs : product.media?.filter((m) => m.type === "image") ?? [];
   }, [selectedVariant, product.media]);
 
-  // Auto-select the first available color, then its first available size.
-  useEffect(() => {
-    if (!selectedColor && availableColors.length > 0) {
-      const first = availableColors.find((c) => c.hasAvailableSize) ?? availableColors[0];
-      setSelectedColor(first.name);
-    }
-  }, [availableColors, selectedColor]);
-  useEffect(() => {
-    if (selectedColor && !selectedSize && availableSizes.length > 0) {
-      const first = availableSizes.find((s) => s.isAvailable) ?? availableSizes[0];
-      setSelectedSize(first.name);
-    }
-  }, [selectedColor, selectedSize, availableSizes]);
   useEffect(() => setImageIndex(0), [selectedVariant]);
 
   // Mobile: once the inline Add-to-cart scrolls out of view, surface a sticky
@@ -257,73 +247,67 @@ function StandardDetail({
             {selectedVariant?.payWhatYouWant && <span style={{ fontSize: 13, opacity: 0.7 }}> (Pay what you want)</span>}
           </p>
 
-          {/* Color */}
-          {availableColors.length > 0 && (
-            <div style={{ marginTop: 18 }}>
-              <p style={{ fontSize: 15, marginBottom: 8 }}>Color</p>
+          {/* Options — one block per axis the product actually uses. */}
+          {axes.map((axis) => (
+            <div key={axis.optionTypeId} style={{ marginTop: 18 }}>
+              <p style={{ fontSize: 15, marginBottom: 8 }}>{axis.axis}</p>
               <div style={{ display: "flex", flexWrap: "wrap", gap: 10, alignItems: "center", minHeight: 40 }}>
-                {availableColors.map((c) => {
-                  const isHex = /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(c.name);
-                  const on = selectedColor === c.name;
-                  return (
+                {axis.values.map((v) => {
+                  const on = selection[axis.optionTypeId] === v.optionValueId;
+                  // A swatch only when the value genuinely carries a colour, or
+                  // when it reads as one. Everything else is a text chip —
+                  // guessing a colour for "Stems" would render a black circle
+                  // with no label.
+                  const hex = v.swatchHex ?? (/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(v.value) ? v.value : null);
+                  return hex ? (
                     <button
-                      key={c.name}
+                      key={v.optionValueId}
                       type="button"
-                      title={c.name}
-                      disabled={!c.hasAvailableSize}
-                      onClick={() => {
-                        setSelectedColor(c.name);
-                        setSelectedSize(null);
-                      }}
+                      title={v.value}
+                      aria-label={`${axis.axis}: ${v.value}`}
+                      aria-pressed={on}
+                      disabled={!v.isAvailable}
+                      onClick={() => select(axis.optionTypeId, v.optionValueId)}
                       style={{
                         position: "relative",
                         width: on ? 34 : 30,
                         height: on ? 34 : 30,
                         borderRadius: "50%",
-                        cursor: c.hasAvailableSize ? "pointer" : "not-allowed",
-                        opacity: c.hasAvailableSize ? 1 : 0.5,
-                        background: isHex ? c.name : c.name.toLowerCase(),
+                        cursor: v.isAvailable ? "pointer" : "not-allowed",
+                        opacity: v.isAvailable ? 1 : 0.5,
+                        background: hex,
                         border: `2px solid ${on ? t.primary : a(t.text, 0.25)}`,
                         boxShadow: on ? "0 2px 8px -2px rgba(0,0,0,0.3)" : "none",
                         transition: "all .15s",
                       }}
                     />
-                  );
-                })}
-              </div>
-            </div>
-          )}
-
-          {/* Size */}
-          {selectedColor && availableSizes.length > 0 && (
-            <div style={{ marginTop: 18 }}>
-              <p style={{ fontSize: 15, marginBottom: 8 }}>Size</p>
-              <div style={{ display: "flex", flexWrap: "wrap", gap: 10 }}>
-                {availableSizes.map((s) => {
-                  const on = selectedSize === s.name;
-                  return (
+                  ) : (
                     <button
-                      key={s.name}
+                      key={v.optionValueId}
                       type="button"
-                      disabled={!s.isAvailable}
-                      onClick={() => setSelectedSize(s.name)}
+                      aria-pressed={on}
+                      // Same accessible name as the swatch form, so one locator
+                      // — and one screen-reader announcement — covers both.
+                      aria-label={`${axis.axis}: ${v.value}`}
+                      disabled={!v.isAvailable}
+                      onClick={() => select(axis.optionTypeId, v.optionValueId)}
                       style={{
                         padding: "8px 16px",
                         borderRadius: t.cornerRadius,
-                        cursor: s.isAvailable ? "pointer" : "not-allowed",
+                        cursor: v.isAvailable ? "pointer" : "not-allowed",
                         fontWeight: 600,
-                        color: s.isAvailable ? t.text : a(t.text, 0.4),
-                        background: on ? a(t.primary, 0.1) : s.isAvailable ? "transparent" : a(t.text, 0.06),
+                        color: v.isAvailable ? t.text : a(t.text, 0.4),
+                        background: on ? a(t.primary, 0.1) : v.isAvailable ? "transparent" : a(t.text, 0.06),
                         border: `2px solid ${on ? t.primary : a(t.text, 0.2)}`,
                       }}
                     >
-                      {s.name}
+                      {v.value}
                     </button>
                   );
                 })}
               </div>
             </div>
-          )}
+          ))}
 
           {/* Quantity */}
           {selectedVariant && (
@@ -354,8 +338,44 @@ function StandardDetail({
           {selectedVariant && (
             <div style={{ marginTop: 20, paddingTop: 16, borderTop: `1px solid ${a(t.text, 0.15)}` }}>
               <p style={{ fontWeight: 700, fontSize: 13, opacity: 0.7, marginBottom: 6 }}>Product details</p>
-              <p style={{ fontSize: 14, opacity: 0.75 }}>Category: {product.category}</p>
+              {/* "Type", not "Category" — the two were the same thing until the
+                  taxonomy split, and the creator's real categories are below. */}
+              <p style={{ fontSize: 14, opacity: 0.75 }}>Type: {product.productType}</p>
               <p style={{ fontSize: 14, opacity: 0.75 }}>SKU: {selectedVariant.upcCode || "N/A"}</p>
+              {!!product.categories?.length && (
+                <p style={{ fontSize: 14, opacity: 0.75 }}>
+                  {product.categories.length === 1 ? "Category: " : "Categories: "}
+                  {product.categories.map((c, i) => (
+                    <span key={c.id}>
+                      {i > 0 && ", "}
+                      {hrefForCategory ? (
+                        <a href={hrefForCategory(c)} style={{ color: t.primary, textDecoration: "none" }}>
+                          {c.title}
+                        </a>
+                      ) : (
+                        c.title
+                      )}
+                    </span>
+                  ))}
+                </p>
+              )}
+              {!!product.collections?.length && (
+                <p style={{ fontSize: 14, opacity: 0.75 }}>
+                  {product.collections.length === 1 ? "Collection: " : "Collections: "}
+                  {product.collections.map((c, i) => (
+                    <span key={c.id}>
+                      {i > 0 && ", "}
+                      {hrefForCollection ? (
+                        <a href={hrefForCollection(c)} style={{ color: t.primary, textDecoration: "none" }}>
+                          {c.title}
+                        </a>
+                      ) : (
+                        c.title
+                      )}
+                    </span>
+                  ))}
+                </p>
+              )}
             </div>
           )}
 
@@ -437,7 +457,13 @@ function MusicDetail({
   const pricesIncludeTax = usePricesIncludeTax();
   const { pause, loadAndPlay, currentTrack, play, isPlaying } = useAudioPlayer();
 
-  const defaultVariant = product.variants.find((v) => v.isDefault) || product.variants[0];
+  // A release can be sold in several forms — MP3 and FLAC, vinyl and cassette —
+  // so this page can no longer assume one version. With no axes the hook returns
+  // exactly what this used to: the default variant.
+  const { axes, selection, select, selectedVariant } = useVariantSelection(product.variants);
+  const defaultVariant = selectedVariant ?? product.variants.find((v) => v.isDefault) ?? product.variants[0];
+  // The TRACKLIST is the release's contents and does not depend on which
+  // version is selected — every version of an album has the same songs.
   const tracks = defaultVariant?.tracks ?? [];
   const isSingle = tracks.length === 1;
   const firstTrack = tracks[0];
@@ -536,6 +562,39 @@ function MusicDetail({
               <div style={{ fontSize: 20, fontWeight: 700, color: t.primary }}>
                 <PriceDisplay amount={defaultVariant.price} pricesIncludeTax={pricesIncludeTax} formatAmount={fmt} mutedColor={t.text} captionStyle={{ opacity: 0.65 }} />
               </div>
+
+              {/* One row per axis, only when the release actually has formats. */}
+              {axes.map((axis) => (
+                <div key={axis.optionTypeId} style={{ display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
+                  <span style={{ fontSize: 13, opacity: 0.7, color: t.text }}>{axis.axis}</span>
+                  {axis.values.map((v) => {
+                    const on = selection[axis.optionTypeId] === v.optionValueId;
+                    return (
+                      <button
+                        key={v.optionValueId}
+                        type="button"
+                        aria-pressed={on}
+                        aria-label={`${axis.axis}: ${v.value}`}
+                        disabled={!v.isAvailable}
+                        onClick={() => select(axis.optionTypeId, v.optionValueId)}
+                        style={{
+                          padding: "6px 12px",
+                          fontSize: 13,
+                          borderRadius: t.cornerRadius,
+                          cursor: v.isAvailable ? "pointer" : "not-allowed",
+                          opacity: v.isAvailable ? 1 : 0.5,
+                          color: t.text,
+                          background: on ? a(t.primary, 0.1) : "transparent",
+                          border: `1px solid ${on ? t.primary : a(t.text, 0.25)}`,
+                        }}
+                      >
+                        {v.value}
+                      </button>
+                    );
+                  })}
+                </div>
+              ))}
+
               <div style={{ display: "flex", gap: 10, flexWrap: "wrap", marginTop: 4 }}>
                 <Button onClick={() => buyNow(defaultVariant, { canIncreaseQuantity: false })}>Buy now</Button>
                 <Button variant="outline" onClick={() => add(defaultVariant, { canIncreaseQuantity: false })}>

package/src/ui/styled/ProductGrid.tsx

@@ -1,5 +1,5 @@
 import { useGetProducts, useGetProductsByIds } from "../../data/queries/useProducts";
-import type { IPublicProduct } from "../../types/models";
+import type { IPublicProduct, ProductType } from "../../types/models";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { useAmountFormatter } from "../format/useFormatCurrency";
 import { PriceDisplay } from "../format/PriceDisplay";
@@ -15,6 +15,17 @@ export interface ProductGridProps {
    * "the first N products".
    */
   productIds?: string[];
+  /**
+   * Show only products filed under this category. **Descendant-inclusive** —
+   * passing "Apparel" returns everything beneath it at any depth, which is what
+   * makes a parent category a usable browse destination rather than an empty
+   * page.
+   */
+  categoryId?: string;
+  /** Show only products in this collection, in the creator's curated order. */
+  collectionId?: string;
+  /** Show only products of this kind (Music / Merch / Digital / Service). */
+  productType?: ProductType[];
   formatAmount?: (amount: number) => string;
   onSelect?: (product: IPublicProduct) => void;
   /**
@@ -39,6 +50,9 @@ export function ProductGrid({
   columns = 3,
   limit,
   productIds,
+  categoryId,
+  collectionId,
+  productType,
   formatAmount,
   onSelect,
   hrefFor,
@@ -52,7 +66,7 @@ export function ProductGrid({
   const byIds = !!productIds?.length;
   // Both hooks are called unconditionally (rules of hooks); each disables
   // itself when it isn't the one in use.
-  const listQuery = useGetProducts({ page: 1 }, !byIds);
+  const listQuery = useGetProducts({ page: 1, categoryId, collectionId, productType }, !byIds);
   const idsQuery = useGetProductsByIds(byIds ? productIds! : []);
 
   const isLoading = byIds ? idsQuery.isLoading : listQuery.isLoading;