@forgecart/cli 2.202610280649.0 → 2.202610280926.0

package/templates/storefront-shadcn-blank/src/components/ForgeTracker.tsx

@@ -0,0 +1,479 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
+
+import {
+  type MarketingIdentifier,
+  parseMarketingParams,
+  type UtmParams,
+} from '../lib/marketing-params';
+import { mintUuid } from '../lib/uuid';
+
+/**
+ * Storefront event tracker (design doc S7). Renders nothing.
+ *
+ * The single client-side emitter of marketing events. Everything goes through
+ * the same-origin `/__fc/track` relay — NEVER the SDK's WebSocket singleton,
+ * whose connection pins one identity and would mis-attribute every event after
+ * a login. The relay replays the shopper's `forgecart-session` cookie per
+ * request, so attribution follows the identity.
+ *
+ * What it emits:
+ *   - `page_view` on the initial load and on every App-Router route change
+ *     (client-effect emission is the only prefetch-safe choice — `<Link>`
+ *     prefetches run middleware and RSC fetches but no client effects).
+ *     `properties.referrerPath` is the module-tracked previous pathname:
+ *     `document.referrer` is frozen across soft navigations and must not be
+ *     read per-view; only the initial load additionally carries it (origin
+ *     level under the default Referrer-Policy) as `properties.referrer`.
+ *   - `cta_click` from ONE delegated capture-phase click listener for any
+ *     `[data-fc-track]` element — the element stays dumb (a semantic slug in
+ *     `properties.trackId`); what the click MEANS is backend automation
+ *     config, never deployed code.
+ *   - `heartbeat` every {@link HEARTBEAT_MS} while the tab is visible (plus
+ *     one on refocus) — liveness plumbing only, excluded from aggregates.
+ *
+ * What a landing additionally does: a view whose URL carries marketing
+ * parameters reads them once (`lib/marketing-params`). The click IDs go to
+ * {@link IDENTIFY_ENDPOINT} and that request is AWAITED before the view is
+ * enqueued, so the identity the relay mints carries them instead of the two
+ * racing; the campaign tags are held for the rest of the visit and ride every
+ * later event. A URL without any of them does nothing at all — no request, no
+ * stored state, no change to the events below.
+ *
+ * Delivery: events buffer and flush as one batch at {@link FLUSH_MAX_EVENTS}
+ * events or after an age timer via `fetch(keepalive)` — the FIRST batch waits
+ * {@link ESTABLISHMENT_GRACE_MS}, every later batch {@link FLUSH_INTERVAL_MS}
+ * (see the grace rationale on the constant); `sendBeacon` is used ONLY for the
+ * `pagehide` flush (its unload-time queueing guarantee is the one thing
+ * keepalive fetch lacks). Every event carries a client-minted `eventId`
+ * (`crypto.randomUUID`) — the server dedupes on it, so an accidental
+ * double-send is harmless. Delivery is fire-and-forget: failures are
+ * swallowed and never retried; analytics must never break the storefront.
+ *
+ * Deliberately NO 30-second same-path dedup (the old `ForgeAnalytics`
+ * behavior): it was live-map-correct but funnel-lossy — A→B→A inside 30s
+ * dropped the return view. The short same-signal suppressors (300ms; also what
+ * keeps StrictMode's double-mount from double-emitting, via module scope) plus
+ * the server-side `eventId` dedupe replace it, so revisits are recorded.
+ *
+ * Two deliberate suppressions:
+ *   - missing config (the pod image pre-renders the template before
+ *     `forgecart init` writes `.env`) → the tracker is inert;
+ *   - framed embeds (`window.parent !== window`) → the visual editor's
+ *     artboard preview emits nothing, so funnels stay production-visitor-only.
+ */
+
+const HEARTBEAT_MS = 60_000;
+/** Minimum spacing between heartbeats (refocus storms, StrictMode remounts). */
+const HEARTBEAT_MIN_SPACING_MS = 30_000;
+/** Batch flush thresholds: whichever of size / age is hit first sends. */
+const FLUSH_MAX_EVENTS = 10;
+const FLUSH_INTERVAL_MS = 500;
+/**
+ * Age timer for the FIRST batch only. On a cookie-less first touch the relay
+ * and the first cart Server Action race to mint the shopper session, and the
+ * browser keeps whichever `Set-Cookie` lands last — if the tracker's ~500ms
+ * page_view batch wins that race against a fast add-to-cart, the cookie flips
+ * away from the session holding the just-created cart. Holding the initial
+ * flush for this grace lets the cart's cookie land first, so the relay batch
+ * then CARRIES it and rides the cart's session instead of minting a rival
+ * (design doc S7: the first tracked interaction establishes the identity the
+ * cart later reuses — establishment still happens, just not mid-race).
+ * Events are timestamped at enqueue (`occurredAt`), so deferral loses nothing.
+ */
+const ESTABLISHMENT_GRACE_MS = 2_000;
+/** Same-signal suppression window (per click slug; per page_view path). */
+const SUPPRESS_MS = 300;
+/**
+ * Minimum VISIBLE dwell before a route's scroll_depth summary is worth a
+ * row (#1022 phase 2b) — filters bounce-through navigations and StrictMode's
+ * dev-only phantom unmount.
+ */
+const ENGAGEMENT_MIN_DWELL_MS = 250;
+const TRACK_ENDPOINT = '/__fc/track';
+/** Landing-only: where a captured click ID is attached to the shopper. */
+const IDENTIFY_ENDPOINT = '/__fc/identify';
+
+/** One buffered event — the relay forwards these fields to `trackEvent`. */
+interface TrackedEvent {
+  eventType: string;
+  eventId: string;
+  occurredAt: string;
+  properties?: Record<string, unknown>;
+  /**
+   * The campaign this visit arrived on, repeated on every event of the visit.
+   *
+   * Spelled out rather than reused from the parser's `UtmParams` because the
+   * five fields are a CONTRACT with the relay's allowlist, not a shape that
+   * should follow the parser if it ever grows a sixth tag. An absent tag is an
+   * absent KEY here, never `''`: the backend stores a present empty string as a
+   * real ClickHouse dimension, where it can no longer be told apart from a
+   * campaign that genuinely has no medium.
+   */
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+}
+
+// Module scope on purpose: the buffer, timers and suppressors must survive
+// StrictMode's mount → unmount → mount cycle (a ref would reset) and there is
+// exactly one tracker per page.
+let buffer: TrackedEvent[] = [];
+let flushTimer: number | null = null;
+/** True once any batch has gone out — ends the establishment grace. */
+let firstBatchSent = false;
+const lastClickAtBySlug = new Map<string, number>();
+let lastPageView: { path: string; at: number } | null = null;
+let previousPathname: string | null = null;
+let lastHeartbeatAt = 0;
+/**
+ * The campaign tags of the landing that started this visit. Module scope for
+ * the same reason as the buffer — StrictMode remounts the component and a ref
+ * would reset — and because there is nowhere else to read them from: an
+ * internal navigation carries no query string.
+ */
+let capturedUtm: UtmParams = {};
+/**
+ * The click IDs already sent to {@link IDENTIFY_ENDPOINT}, as `key=value&…`.
+ *
+ * Module scope so StrictMode's mount → unmount → mount sends ONE identify for
+ * one landing. A signature rather than a boolean because "once per captured
+ * landing" is not "once per visit": a shopper who clicks a second ad back into
+ * the store brings a different click ID that must still be delivered, while a
+ * revisit of the same landing URL must not send the same one twice.
+ */
+let identifiedClickIds: string | null = null;
+
+/**
+ * Consent extension point. Tracking currently needs no opt-in, so this is a
+ * no-op returning `true`; the merchant cookie-banner fast-follow implements
+ * the real gate HERE (read the stored consent state) and every emission path
+ * already respects it — nothing enters the buffer without consent.
+ */
+function hasTrackingConsent(): boolean {
+  return true;
+}
+
+/**
+ * Client-side idempotency key via the shared insecure-context-safe minter
+ * (lib/uuid.ts) — a thrown TypeError inside a click listener would violate
+ * the "analytics never breaks the storefront" invariant.
+ */
+function mintEventId(): string {
+  return mintUuid();
+}
+
+/** Stamp and buffer one event; flush on size, else arm the age timer. */
+function enqueue(eventType: string, properties?: Record<string, unknown>): void {
+  if (!hasTrackingConsent()) return;
+  const event: TrackedEvent = {
+    eventType,
+    eventId: mintEventId(),
+    occurredAt: new Date().toISOString(),
+    // Spreading an empty object adds no keys, so an organic visit emits exactly
+    // the event shape it did before any of this existed.
+    ...capturedUtm,
+  };
+  if (properties) event.properties = properties;
+  buffer.push(event);
+
+  if (buffer.length >= FLUSH_MAX_EVENTS) {
+    flush();
+    return;
+  }
+  if (flushTimer === null) {
+    const delay = firstBatchSent ? FLUSH_INTERVAL_MS : ESTABLISHMENT_GRACE_MS;
+    flushTimer = window.setTimeout(flush, delay);
+  }
+}
+
+/** Drain the buffer, returning the batch to send (empties module state). */
+function drain(): TrackedEvent[] {
+  if (flushTimer !== null) {
+    window.clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  const events = buffer;
+  buffer = [];
+  // The grace ends once a batch actually goes out — from then on the age
+  // timer runs at the normal cadence.
+  if (events.length > 0) firstBatchSent = true;
+  return events;
+}
+
+/** Primary delivery: keepalive fetch, fire-and-forget, failures swallowed. */
+function flush(): void {
+  const events = drain();
+  if (events.length === 0) return;
+  void fetch(TRACK_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ events }),
+    keepalive: true,
+  }).catch(() => undefined);
+}
+
+/**
+ * Read this URL's marketing parameters and act on what it carries.
+ *
+ * Resolves once the click IDs have been delivered — the caller awaits it so the
+ * identify request and the first tracked batch cannot race. Does nothing
+ * whatsoever for a URL that carries none, which is the overwhelmingly common
+ * case and the reason the parser returns a union.
+ */
+async function captureLanding(search: string): Promise<void> {
+  // Consent is checked HERE as well as in `enqueue` because the identify
+  // request is not a buffered event: it leaves on its own, carrying a click ID
+  // that identifies the visitor more directly than anything in the buffer, so
+  // a gate that only guards `enqueue` would let it past a visitor who declined.
+  if (!hasTrackingConsent()) return;
+  const marketing = parseMarketingParams(search);
+  if (marketing.kind === 'none') return;
+
+  // Merge, never clear — the same semantics `middleware.ts` uses for the
+  // `fc-exp` cookie. Only a URL that carries tags updates them, so an internal
+  // navigation keeps the campaign the visitor arrived on, and a second ad
+  // landing legitimately overwrites the tags it brings.
+  capturedUtm = { ...capturedUtm, ...marketing.utm };
+
+  if (marketing.identifiers.length === 0) return;
+  const signature = signClickIds(marketing.identifiers);
+  if (signature === identifiedClickIds) return;
+  // Recorded BEFORE the await: StrictMode's second mount runs while this
+  // request is still in flight and must find the landing already claimed.
+  identifiedClickIds = signature;
+  await fetch(IDENTIFY_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ identifiers: marketing.identifiers }),
+    keepalive: true,
+  }).catch(() => undefined); // same swallow as flush(): analytics never breaks the storefront
+}
+
+/** The click IDs of one landing as a comparable string, in parser order. */
+function signClickIds(identifiers: readonly MarketingIdentifier[]): string {
+  return identifiers.map(({ key, value }) => `${key}=${value}`).join('&');
+}
+
+/**
+ * Capture the landing, THEN record the view.
+ *
+ * The order is the whole point. The first request of a visit is what mints the
+ * shopper session, so sending the identify and the page_view in parallel would
+ * mint one identity per request and split the visit in two — the click ID on
+ * one, every tracked event on the other, and no attribution joining them.
+ */
+async function emitPageView(properties: Record<string, unknown>): Promise<void> {
+  await captureLanding(window.location.search);
+  enqueue('page_view', properties);
+}
+
+/**
+ * `pagehide` delivery: `sendBeacon` — the only flush that uses it, for its
+ * survive-the-unload queueing guarantee. Falls back to keepalive fetch where
+ * the API is unavailable.
+ */
+function flushOnPagehide(): void {
+  const events = drain();
+  if (events.length === 0) return;
+  const body = JSON.stringify({ events });
+  if (typeof navigator.sendBeacon === 'function') {
+    navigator.sendBeacon(TRACK_ENDPOINT, new Blob([body], { type: 'application/json' }));
+    return;
+  }
+  void fetch(TRACK_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+    keepalive: true,
+  }).catch(() => undefined);
+}
+
+/**
+ * `enabled` is computed SERVER-side (env presence) and passed as a boolean —
+ * the tracker only needs to know whether the relay is configured; the channel
+ * token itself must never serialize into the RSC payload.
+ */
+export function ForgeTracker({ enabled }: { enabled: boolean }) {
+  const pathname = usePathname();
+
+  // page_view — initial load + every route change.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+    const now = Date.now();
+    if (lastPageView && lastPageView.path === pathname && now - lastPageView.at < SUPPRESS_MS) {
+      return;
+    }
+    lastPageView = { path: pathname, at: now };
+    const properties: Record<string, unknown> = { path: pathname };
+    if (previousPathname !== null) {
+      properties.referrerPath = previousPathname;
+    } else if (document.referrer) {
+      properties.referrer = document.referrer;
+    }
+    previousPathname = pathname;
+    // The suppressor above is already stamped, so the double mount StrictMode
+    // performs while this is in flight still emits exactly one view.
+    void emitPageView(properties);
+  }, [enabled, pathname]);
+
+  // cta_click — one delegated capture-phase listener — and the pagehide flush.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    const onClick = (event: Event): void => {
+      if (!(event.target instanceof Element)) return;
+      const tracked = event.target.closest('[data-fc-track]');
+      if (!tracked) return;
+      const trackId = tracked.getAttribute('data-fc-track');
+      if (!trackId) return;
+      const now = Date.now();
+      const lastAt = lastClickAtBySlug.get(trackId);
+      if (lastAt !== undefined && now - lastAt < SUPPRESS_MS) return;
+      lastClickAtBySlug.set(trackId, now);
+      enqueue('cta_click', { trackId, path: window.location.pathname });
+    };
+    const onPagehide = (): void => flushOnPagehide();
+
+    // Capture phase so the event is seen even when a handler below stops
+    // propagation (e.g. a framework's synthetic-event stopPropagation).
+    document.addEventListener('click', onClick, true);
+    window.addEventListener('pagehide', onPagehide);
+    return () => {
+      document.removeEventListener('click', onClick, true);
+      window.removeEventListener('pagehide', onPagehide);
+    };
+  }, [enabled]);
+
+  // heartbeat — while visible, plus one on refocus; paused while hidden.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    let interval: ReturnType<typeof setInterval> | null = null;
+
+    const beat = (): void => {
+      const now = Date.now();
+      if (now - lastHeartbeatAt < HEARTBEAT_MIN_SPACING_MS) return;
+      lastHeartbeatAt = now;
+      enqueue('heartbeat');
+    };
+    const start = (): void => {
+      if (interval !== null) return;
+      interval = setInterval(beat, HEARTBEAT_MS);
+    };
+    const stop = (): void => {
+      if (interval === null) return;
+      clearInterval(interval);
+      interval = null;
+    };
+    const onVisibility = (): void => {
+      if (document.visibilityState === 'visible') {
+        beat();
+        start();
+      } else {
+        stop();
+      }
+    };
+
+    document.addEventListener('visibilitychange', onVisibility);
+    if (document.visibilityState === 'visible') start();
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibility);
+      stop();
+    };
+  }, [enabled]);
+
+  // scroll_depth — ONE engagement summary per route (#1022 phase 2b): the
+  // max scroll depth reached (percent, 0-100) and the VISIBLE dwell time,
+  // emitted when the route unmounts (client-side navigation) or the page
+  // hides. Rides the dormant `scroll_depth` event type already in the
+  // default shop allowlist; the server hoists both properties into the
+  // typed `scrollDepth`/`durationMs` ClickHouse columns (CH 005).
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    let maxDepthPct = 0;
+    let visibleMs = 0;
+    let visibleSince: number | null =
+      document.visibilityState === 'visible' ? performance.now() : null;
+    let ticking = false;
+    let emitted = false;
+
+    const measure = (): void => {
+      ticking = false;
+      const doc = document.documentElement;
+      // A page shorter than the viewport is fully seen — 100 by definition;
+      // otherwise percent of total document height brought into view.
+      const pct =
+        doc.scrollHeight <= window.innerHeight
+          ? 100
+          : Math.min(
+              100,
+              Math.round(((window.scrollY + window.innerHeight) / doc.scrollHeight) * 100),
+            );
+      if (pct > maxDepthPct) maxDepthPct = pct;
+    };
+    const onScroll = (): void => {
+      if (ticking) return;
+      ticking = true;
+      requestAnimationFrame(measure);
+    };
+    const onVisibility = (): void => {
+      const now = performance.now();
+      if (document.visibilityState === 'visible') {
+        visibleSince ??= now;
+        return;
+      }
+      if (visibleSince !== null) {
+        visibleMs += now - visibleSince;
+        visibleSince = null;
+      }
+    };
+    const emit = (): void => {
+      if (emitted) return;
+      if (visibleSince !== null) {
+        visibleMs += performance.now() - visibleSince;
+        visibleSince = null;
+      }
+      // Dwell floor: a route that never accumulated meaningful visible time
+      // has no engagement story — this also swallows StrictMode's dev-only
+      // mount/unmount phantom, which would otherwise emit a zero-dwell row.
+      if (visibleMs < ENGAGEMENT_MIN_DWELL_MS) return;
+      emitted = true;
+      enqueue('scroll_depth', {
+        path: window.location.pathname,
+        scrollDepth: maxDepthPct,
+        durationMs: Math.round(visibleMs),
+      });
+    };
+    const onPagehide = (): void => {
+      // Emit BEFORE the flush so the summary rides the pagehide beacon —
+      // flushOnPagehide drains-and-no-ops on empty, so the sibling pagehide
+      // listener's own call stays harmless.
+      emit();
+      flushOnPagehide();
+    };
+
+    measure(); // above-the-fold baseline before any scroll fires
+
+    window.addEventListener('scroll', onScroll, { passive: true });
+    document.addEventListener('visibilitychange', onVisibility);
+    window.addEventListener('pagehide', onPagehide);
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+      document.removeEventListener('visibilitychange', onVisibility);
+      window.removeEventListener('pagehide', onPagehide);
+      emit(); // client-side route change: summarize the route being left
+    };
+  }, [enabled, pathname]);
+
+  return null;
+}

package/templates/storefront-shadcn-blank/src/components/ForgecartDesigner.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * Mounts the ForgeCart visual-editor guest runtime. Renders nothing.
+ *
+ * The runtime stays dormant until activated: it registers a single `message`
+ * listener and posts a READY beacon, then waits for the dashboard host to
+ * drive a nonce-gated handshake over `postMessage` (the activation nonce
+ * arrives via the `#fcd=` URL fragment — there is no env switch). On a page
+ * that is not embedded in an iframe it never even loads.
+ *
+ * Production builds ship zero bytes of this: the literal `NODE_ENV` check is
+ * inlined by the bundler, so the effect body — including the dynamic import
+ * and its chunk — is dead-code-eliminated from `next build` output.
+ */
+export function ForgecartDesigner() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') {
+      return;
+    }
+    // Top-level pages have no designer host; skip loading the chunk entirely.
+    if (window.parent === window) {
+      return;
+    }
+    let cancelled = false;
+    let dispose: (() => void) | undefined;
+    const install = async () => {
+      const mod = await import('@forgecart/designer-runtime');
+      if (cancelled) {
+        return;
+      }
+      dispose = mod.installDesignerRuntime();
+    };
+    void install();
+    return () => {
+      cancelled = true;
+      dispose?.();
+    };
+  }, []);
+  return null;
+}

package/templates/storefront-shadcn-blank/src/components/LocaleLink.tsx

@@ -0,0 +1,49 @@
+import Link from 'next/link';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { localizedPath } from '../lib/locale/localized-path';
+import type { LocaleBinding } from '../lib/locale/localized-path';
+
+/**
+ * An internal link that stays inside the request's locale cluster (#1346,
+ * W1-8 / S2).
+ *
+ * Every internal navigation goes through this instead of `next/link` directly.
+ * A German page whose links all point at the English cluster leaves every
+ * German page but the entry point unreachable by following links, so a crawler
+ * never discovers them and the locale is effectively unindexed.
+ *
+ * The locale arrives as a PROP and is never derived here. Under the middleware
+ * rewrite the browser's URL and the rendered route differ — `/de/products`
+ * renders the `/products` route — so `usePathname()` returns the REWRITTEN
+ * path, and a component that read the locale from it would emit English links
+ * on every German page while looking correct in review. Server components take
+ * the binding from `getRequestLocale()`; client components receive it from
+ * whichever server component renders them.
+ *
+ * `href` is the UNPREFIXED route path, always — the same string you would have
+ * written before the locale layer existed. Prefixing is this component's job.
+ */
+
+// `locale` is omitted because `next/link` HAS a prop by that name — the Pages
+// Router i18n feature, typed `string | false`. This storefront does its own
+// locale routing (App Router, middleware rewrite), so that prop is never the
+// one we want, and forwarding it would collide with the binding below: the
+// production build fails with TS2430, which `next dev` never reports.
+type ForwardedLinkProps = Omit<ComponentProps<typeof Link>, 'href' | 'children' | 'locale'>;
+
+export interface LocaleLinkProps extends ForwardedLinkProps {
+  /** The unprefixed route path, e.g. `/products`. */
+  href: string;
+  /** The request's locale binding, from `getRequestLocale()`. */
+  locale: LocaleBinding;
+  children: ReactNode;
+}
+
+export function LocaleLink({ href, locale, children, ...rest }: LocaleLinkProps): ReactNode {
+  return (
+    <Link href={localizedPath(href, locale)} {...rest}>
+      {children}
+    </Link>
+  );
+}

package/templates/storefront-shadcn-blank/src/components/ui/alert.tsx

@@ -0,0 +1,75 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * The shadcn/ui alert, with the status variants this variant declares.
+ *
+ * shadcn/ui ships `default` and `destructive`; the storefront also speaks
+ * success, warning and info, so those three are variants here, each filled
+ * with its own `--success` / `--warning` / `--info` token and the
+ * `-foreground` that stays legible on it (see the mapping table in
+ * `src/app/globals.css`). An alert is `role="alert"` unless the caller says
+ * otherwise — a polite outcome passes `role="status"`.
+ */
+const alertVariants = cva(
+  'relative grid w-full grid-cols-[0_1fr] items-start gap-y-0.5 rounded-lg border px-4 py-3 text-sm has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] has-[>svg]:gap-x-3 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
+  {
+    variants: {
+      variant: {
+        default: 'bg-card text-card-foreground',
+        destructive:
+          'bg-card text-destructive [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90',
+        success:
+          'border-success bg-success text-success-foreground *:data-[slot=alert-description]:text-success-foreground/90',
+        warning:
+          'border-warning bg-warning text-warning-foreground *:data-[slot=alert-description]:text-warning-foreground/90',
+        info: 'border-info bg-info text-info-foreground *:data-[slot=alert-description]:text-info-foreground/90',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+function Alert({
+  className,
+  variant,
+  ...props
+}: ComponentProps<'div'> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      data-slot="alert"
+      role="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+function AlertTitle({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn('col-start-2 min-h-4 font-medium tracking-tight', className)}
+      {...props}
+    />
+  );
+}
+
+function AlertDescription({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        'col-start-2 grid justify-items-start gap-1 text-sm text-muted-foreground [&_p]:leading-relaxed',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Alert, AlertDescription, AlertTitle };

package/templates/storefront-shadcn-blank/src/components/ui/badge.tsx

@@ -0,0 +1,40 @@
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * The shadcn/ui badge — the cart count, a subscription line's label, an
+ * applied coupon. As with the button, the variant shadcn/ui paints with a raw
+ * `text-white` is not vendored: every colour here is a token.
+ */
+const badgeVariants = cva(
+  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden whitespace-nowrap rounded-md border px-2 py-0.5 text-xs font-medium transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 [&>svg]:pointer-events-none [&>svg]:size-3',
+  {
+    variants: {
+      variant: {
+        default: 'border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+        secondary:
+          'border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+        outline: 'text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+function Badge({
+  className,
+  variant,
+  asChild = false,
+  ...props
+}: ComponentProps<'span'> & VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot : 'span';
+
+  return <Comp data-slot="badge" className={cn(badgeVariants({ variant }), className)} {...props} />;
+}
+
+export { Badge, badgeVariants };