@forgecart/cli 2.202606151453.0 → 2.202607070306.0

package/dist/src/commands/init.d.ts

@@ -26,6 +26,14 @@ export interface InitOptions {
     apiUrl: string;
     /** Whether to also scaffold a NestJS application (planned for a later phase). */
     application?: boolean;
+    /**
+     * Serve-in-place mode: the target directory is ALREADY a scaffolded,
+     * dependency- and dev-compile-warmed storefront (materialized into the pod's
+     * `/workspace` from the image's pre-warmed tree). Write ONLY the per-channel
+     * config + `.env.local` and skip the template copy entirely — copying would
+     * clobber the warm `.next` and bust the Turbopack dev cache.
+     */
+    configOnly?: boolean;
 }
 /**
  * Run `forgecart init`.

package/dist/src/commands/init.js

@@ -42,6 +42,16 @@ async function isDirectory(path) {
         return false;
     }
 }
+/** True if the path exists and is a regular file. */
+async function isFile(path) {
+    try {
+        const info = await stat(path);
+        return info.isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Read a `package.json` and normalize it for content comparison. Returns null
  * when the file is missing or not valid JSON — callers treat that as "manifests
@@ -121,6 +131,19 @@ function buildEnvLocal(channelToken, apiUrl) {
         '',
     ].join('\n');
 }
+/**
+ * Write the per-channel config the storefront reads at runtime: `.forgecart/
+ * config.json` (channel token, api url, app flag) and `.env.local` (the SDK
+ * client env). Shared by the full scaffold and the `--config-only` serve-in-place
+ * path, so both write byte-identical config — the only difference is whether the
+ * template tree was copied first.
+ */
+async function writeChannelConfig(targetDir, channelToken, options) {
+    const configDir = join(targetDir, '.forgecart');
+    await mkdir(configDir, { recursive: true });
+    await writeFile(join(configDir, 'config.json'), `${JSON.stringify(buildConfig(channelToken, options), null, 2)}\n`, 'utf8');
+    await writeFile(join(targetDir, '.env.local'), buildEnvLocal(channelToken, options.apiUrl), 'utf8');
+}
 /** Print the post-scaffold next steps. */
 function printNextSteps(targetDir, application, depsInstalled) {
     print('');
@@ -141,6 +164,16 @@ function printNextSteps(targetDir, application, depsInstalled) {
         print('');
     }
 }
+/** Print the post-scaffold summary for the `--config-only` serve-in-place path. */
+function printConfigOnly(targetDir) {
+    print('');
+    print('Storefront configured (pre-warmed: dependencies and dev cache already in place).');
+    print('');
+    print('Next steps:');
+    print(`  cd ${targetDir}`);
+    print('  npm run dev');
+    print('');
+}
 /**
  * Run `forgecart init`.
  *
@@ -156,6 +189,18 @@ export async function runInit(name, options) {
         throw new Error('A channel token is required. Pass it with --token <token> (or -t <token>).');
     }
     const targetDir = name ? resolve(process.cwd(), name) : process.cwd();
+    // Serve-in-place: the target is already a warm storefront materialized from the
+    // image's pre-warmed tree (node_modules + a warm `.next`). Write only the
+    // per-channel config + env and return — copying the template would clobber the
+    // pre-warmed `.next` and bust the Turbopack dev cache the bake exists to provide.
+    if (options.configOnly) {
+        if (!(await isFile(join(targetDir, 'package.json')))) {
+            throw new Error(`--config-only requires an existing storefront at ${targetDir} (no package.json found).`);
+        }
+        await writeChannelConfig(targetDir, channelToken, options);
+        printConfigOnly(targetDir);
+        return;
+    }
     const templateDir = getStorefrontTemplateDir();
     if (!(await isDirectory(templateDir))) {
         throw new Error(`Storefront template not found at ${templateDir}.`);
@@ -168,13 +213,9 @@ export async function runInit(name, options) {
             recursive: true,
         });
     }
-    const configDir = join(targetDir, '.forgecart');
-    await mkdir(configDir, { recursive: true });
-    const config = buildConfig(channelToken, options);
-    await writeFile(join(configDir, 'config.json'), `${JSON.stringify(config, null, 2)}\n`, 'utf8');
-    await writeFile(join(targetDir, '.env.local'), buildEnvLocal(channelToken, options.apiUrl), 'utf8');
+    await writeChannelConfig(targetDir, channelToken, options);
     await writeDepsReadyMarker(targetDir, plan);
-    printNextSteps(name ?? '.', config.hasApplication, plan.source === 'warmed');
+    printNextSteps(name ?? '.', options.application ?? false, plan.source === 'warmed');
 }
 /** Build the `init [name]` command. */
 export function createInitCommand() {
@@ -184,6 +225,7 @@ export function createInitCommand() {
         .option('-t, --token <token>', 'ForgeCart channel token (required)')
         .option('--api-url <url>', 'Shop API base URL written to the storefront environment', DEFAULT_SHOP_API_URL)
         .option('-a, --application', 'Also scaffold a NestJS application (TODO: next phase)')
+        .option('--config-only', 'Write only per-channel config into an existing pre-warmed storefront (skip the template copy)')
         .action(async (name, options) => {
         await runInit(name, options);
     });

package/dist/src/commands/init.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/cli",
-  "version": "2.202606151453.0",
+  "version": "2.202607070306.0",
   "type": "module",
   "description": "CLI for scaffolding and operating ForgeCart channel storefronts",
   "bin": {

package/templates/storefront/next.config.js

@@ -4,6 +4,26 @@ const nextConfig = {
   // storefront with `next start` without a full node_modules tree.
   output: 'standalone',
   reactStrictMode: true,
+  // The visual-editor preview runs THIS dev server inside a workspace pod and is
+  // reached cross-origin through the channel's preview ingress host
+  // (`<code>.127.0.0.1.nip.io:8081` locally; `<code>.dev|test.forgecart.dev` and
+  // `<code>.forgecart.dev` deployed) — never the pod's own `localhost:3000`. Next
+  // 16 ENFORCES `allowedDevOrigins`: a dev request whose host is not
+  // localhost/127.0.0.1 and not listed here is blocked, which silently kills the
+  // `/_next` HMR websocket (and the dashboard iframe's dev channel) with no page
+  // error. The `*` wildcard matches across dots, so `*.forgecart.dev` covers every
+  // env's preview subdomain. Dev-only — `next start` (deployed storefronts) ignores it.
+  allowedDevOrigins: ['*.127.0.0.1.nip.io', '*.dev.forgecart.dev', '*.forgecart.dev'],
+  experimental: {
+    // Persist Turbopack's dev compile artifacts to `.next` so a pod can serve
+    // a PRE-WARMED `.next` baked at build time instead of paying a cold first
+    // compile. The cache is path-keyed, so it is only valid when warmed at the
+    // SAME absolute path the pod serves from (/workspace) — see the workspace-pod
+    // Dockerfile `storefront-prewarm` stage and the STOREFRONT materialization
+    // initContainer (serve-in-place; never the /opt→/workspace copy). Default-on
+    // in Next 16.1+; set explicitly to document the contract.
+    turbopackFileSystemCacheForDev: true,
+  },
   // Dev-only `data-fc-source` stamping for the ForgeCart visual editor. The
   // loader marks host JSX elements with their source file:line:col so the
   // dashboard can map a sprayed region back to code. It runs under Turbopack

package/templates/storefront/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@forgecart/designer-runtime": "^1.0.0",
     "@forgecart/sdk": "^1.2.6",
-    "next": "^15.1.0",
+    "next": "^16.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

package/templates/storefront/src/app/__forge_beacon/route.ts

@@ -0,0 +1,36 @@
+/**
+ * DEV-ONLY same-origin error-beacon forwarder.
+ *
+ * The storefront's client beacon (`ForgeErrorBeacon`) POSTs a browser-surfaced
+ * runtime error here — same-origin, so the browser never learns the pod-internal
+ * receiver address. This handler forwards the body SERVER-side to the in-pod
+ * workspace-manager receiver at `http://127.0.0.1:<FORGE_BEACON_PORT>/__forge_beacon`,
+ * which folds it into the supervisor's runtime state so the shop's recovery brain
+ * can originate a fix for a crash the dev-server's stderr scan cannot see.
+ *
+ * Gated entirely on `NODE_ENV === 'development'`: a deployed `next start` storefront
+ * answers 404 here and forwards nothing — the whole beacon path ships only in the
+ * in-pod dev-server. `force-dynamic` keeps it out of the static prerender so it
+ * behaves identically under `next dev` and a dev build.
+ */
+export const dynamic = 'force-dynamic';
+
+const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
+
+export async function POST(request: Request): Promise<Response> {
+  if (process.env.NODE_ENV !== 'development') {
+    return new Response(null, { status: 404 });
+  }
+
+  const body = await request.text();
+  // Forward server-side to the loopback receiver. A delivery failure is swallowed —
+  // the beacon is a best-effort backstop, never a hard dependency of the page — but
+  // the client still gets a clean 204 so it never retries against a flapping pod.
+  await fetch(`http://127.0.0.1:${BEACON_PORT}/__forge_beacon`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+  }).catch(() => undefined);
+
+  return new Response(null, { status: 204 });
+}

package/templates/storefront/src/app/cart/page.tsx

@@ -1,88 +1,13 @@
-'use client';
+import { CartView } from '../../components/CartView';
+import { getChannelSellingPlanGroups } from '../../lib/forgecart';
 
-import Link from 'next/link';
+export const dynamic = 'force-dynamic';
 
-import { useCart } from '../../lib/cart-context';
-import { formatPrice } from '../../lib/forgecart';
+export default async function CartPage() {
+  // Channel-wide subscription plans are fetched server-side (the shop client is
+  // server-only) and handed to the client cart view, which renders the
+  // "Subscribe to your whole order" box only when there are any.
+  const channelGroups = await getChannelSellingPlanGroups();
 
-export default function CartPage() {
-  const { cart, itemCount, subtotal, setQuantity, remove, pending } = useCart();
-  const lines = cart?.lines ?? [];
-
-  if (itemCount === 0) {
-    return (
-      <div className="space-y-4">
-        <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
-        <p className="text-gray-500">Your cart is empty.</p>
-        <Link
-          href="/products"
-          className="inline-block rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
-        >
-          Browse products
-        </Link>
-      </div>
-    );
-  }
-
-  return (
-    <div className="space-y-6">
-      <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
-
-      <ul className="divide-y divide-gray-200 rounded-lg border border-gray-200 bg-white">
-        {lines.map((line) => (
-          <li key={line.id} className="flex items-center gap-4 p-4">
-            <div className="h-16 w-16 shrink-0 overflow-hidden rounded bg-gray-100">
-              {line.featuredAsset?.preview ? (
-                // eslint-disable-next-line @next/next/no-img-element
-                <img
-                  src={line.featuredAsset.preview}
-                  alt={line.productVariant.name}
-                  className="h-full w-full object-cover"
-                />
-              ) : null}
-            </div>
-
-            <div className="min-w-0 flex-1">
-              <p className="truncate font-medium text-gray-900">{line.productVariant.name}</p>
-              <p className="text-sm text-gray-500">{formatPrice(line.unitPriceWithTax)} each</p>
-            </div>
-
-            <div className="flex items-center gap-2">
-              <label className="sr-only" htmlFor={`qty-${line.id}`}>
-                Quantity
-              </label>
-              <input
-                id={`qty-${line.id}`}
-                type="number"
-                min={1}
-                value={line.quantity}
-                disabled={pending}
-                onChange={(e) => setQuantity(line.id, Number.parseInt(e.target.value, 10) || 1)}
-                className="w-16 rounded border border-gray-300 px-2 py-1 text-sm disabled:opacity-50"
-              />
-            </div>
-
-            <div className="w-24 text-right font-medium text-gray-900">
-              {formatPrice(line.linePriceWithTax)}
-            </div>
-
-            <button
-              type="button"
-              onClick={() => remove(line.id)}
-              disabled={pending}
-              className="text-sm text-gray-400 hover:text-red-600 disabled:opacity-50"
-              aria-label={`Remove ${line.productVariant.name}`}
-            >
-              Remove
-            </button>
-          </li>
-        ))}
-      </ul>
-
-      <div className="flex items-center justify-between rounded-lg border border-gray-200 bg-white p-4">
-        <span className="text-sm text-gray-600">Subtotal ({itemCount} items)</span>
-        <span className="text-lg font-semibold text-gray-900">{formatPrice(subtotal)}</span>
-      </div>
-    </div>
-  );
+  return <CartView channelGroups={channelGroups} />;
 }

package/templates/storefront/src/app/layout.tsx

@@ -1,6 +1,7 @@
 import type { Metadata } from 'next';
 import type { ReactNode } from 'react';
 
+import { ForgeErrorBeacon } from '../components/ForgeErrorBeacon';
 import { ForgecartDesigner } from '../components/ForgecartDesigner';
 import { Header } from '../components/Header';
 import { getCart } from '../lib/cart-actions';
@@ -28,6 +29,7 @@ export default async function RootLayout({ children }: { children: ReactNode })
           </footer>
         </CartProvider>
         <ForgecartDesigner />
+        <ForgeErrorBeacon />
       </body>
     </html>
   );

package/templates/storefront/src/app/ping/route.ts

@@ -0,0 +1,22 @@
+/**
+ * Liveness ping for the in-pod dev-server readiness probe.
+ *
+ * Returns a static 200 with no layout, data fetch, or session. The workspace's
+ * readiness probe hits THIS route (not `/`) on a fast cadence while the store is
+ * STARTING and then a slow liveness cadence forever — and `/` renders the
+ * cart-aware layout, whose `activeOrder` call MATERIALISES an active order on every
+ * request. Probing `/` therefore minted a throwaway order on every poll; probing a
+ * route handler renders nothing and touches no session, so readiness polling stays
+ * side-effect-free.
+ *
+ * `force-dynamic` keeps it out of the static prerender so a production build serves
+ * it on demand exactly like `next dev` does — the probe always gets a fresh 200.
+ */
+export const dynamic = 'force-dynamic';
+
+export function GET(): Response {
+  return new Response('ok', {
+    status: 200,
+    headers: { 'content-type': 'text/plain' },
+  });
+}

package/templates/storefront/src/app/products/[slug]/page.tsx

@@ -2,7 +2,11 @@ import Link from 'next/link';
 import { notFound } from 'next/navigation';
 
 import { ProductPurchase } from '../../../components/ProductPurchase';
-import { getProductBySlug } from '../../../lib/forgecart';
+import {
+  getProductBySlug,
+  getSellingPlanGroupsForVariant,
+  type SellingPlanGroup,
+} from '../../../lib/forgecart';
 
 export const dynamic = 'force-dynamic';
 
@@ -19,6 +23,21 @@ export default async function ProductDetailPage({
     notFound();
   }
 
+  // Subscription selling plans are eligible per variant, so fetch the groups for
+  // each of the product's variants (in parallel) and pass a variantId -> groups
+  // map to the client purchase control. Variants with no plans get the plain
+  // one-time add-to-cart path.
+  const planGroupsByVariant: Record<string, SellingPlanGroup[]> = Object.fromEntries(
+    await Promise.all(
+      product.variants.map(
+        async (variant): Promise<[string, SellingPlanGroup[]]> => [
+          variant.id,
+          await getSellingPlanGroupsForVariant(variant.id),
+        ],
+      ),
+    ),
+  );
+
   return (
     <div className="space-y-6">
       <Link href="/products" className="text-sm text-gray-600 hover:text-gray-900">
@@ -52,8 +71,8 @@ export default async function ProductDetailPage({
             />
           )}
 
-          {/* Pick a variant (Size/Color) -> price + add-to-cart. */}
-          <ProductPurchase product={product} />
+          {/* Pick a variant (Size/Color) -> price + purchase options + add-to-cart. */}
+          <ProductPurchase product={product} planGroupsByVariant={planGroupsByVariant} />
         </div>
       </div>
     </div>

package/templates/storefront/src/components/CartView.tsx

@@ -0,0 +1,161 @@
+'use client';
+
+import Link from 'next/link';
+
+import { useCart } from '../lib/cart-context';
+import {
+  formatPrice,
+  getPlanCadenceLabel,
+  getPlanSavingsLabel,
+  type SellingPlan,
+  type SellingPlanGroup,
+} from '../lib/forgecart';
+
+/**
+ * The interactive cart, rendered off the live order from `useCart()`.
+ *
+ * `channelGroups` are the channel-wide subscription selling plans, fetched
+ * server-side by the cart route and passed in (the shop client is server-only,
+ * so a client component can't fetch them itself). When present, a "Subscribe to
+ * your whole order" box lets the customer put the entire order on a recurring
+ * plan; the chosen plan is reflected by the order's `sellingPlanId`. Lines that
+ * carry their own `sellingPlanId` (per-line subscriptions added from a product
+ * page) get a small "Subscription" label.
+ */
+export function CartView({ channelGroups }: { channelGroups: SellingPlanGroup[] }) {
+  const { cart, itemCount, subtotal, setQuantity, remove, setSellingPlan, pending } = useCart();
+  const lines = cart?.lines ?? [];
+
+  if (itemCount === 0) {
+    return (
+      <div className="space-y-4">
+        <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
+        <p className="text-gray-500">Your cart is empty.</p>
+        <Link
+          href="/products"
+          className="inline-block rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
+        >
+          Browse products
+        </Link>
+      </div>
+    );
+  }
+
+  // Channel-wide plans (enabled only), flattened across the channel groups.
+  const channelPlans: SellingPlan[] = channelGroups.flatMap((g) => g.plans).filter((p) => p.enabled);
+  const activePlanId = cart?.sellingPlanId ?? null;
+
+  return (
+    <div className="space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
+
+      <ul className="divide-y divide-gray-200 rounded-lg border border-gray-200 bg-white">
+        {lines.map((line) => (
+          <li key={line.id} className="flex items-center gap-4 p-4">
+            <div className="h-16 w-16 shrink-0 overflow-hidden rounded bg-gray-100">
+              {line.featuredAsset?.preview ? (
+                // eslint-disable-next-line @next/next/no-img-element
+                <img
+                  src={line.featuredAsset.preview}
+                  alt={line.productVariant.name}
+                  className="h-full w-full object-cover"
+                />
+              ) : null}
+            </div>
+
+            <div className="min-w-0 flex-1">
+              <p className="truncate font-medium text-gray-900">{line.productVariant.name}</p>
+              <p className="text-sm text-gray-500">{formatPrice(line.unitPriceWithTax)} each</p>
+              {line.sellingPlanId && (
+                <span className="mt-1 inline-block rounded bg-gray-900 px-1.5 py-0.5 text-xs font-medium text-white">
+                  Subscription
+                </span>
+              )}
+            </div>
+
+            <div className="flex items-center gap-2">
+              <label className="sr-only" htmlFor={`qty-${line.id}`}>
+                Quantity
+              </label>
+              <input
+                id={`qty-${line.id}`}
+                type="number"
+                min={1}
+                value={line.quantity}
+                disabled={pending}
+                onChange={(e) => setQuantity(line.id, Number.parseInt(e.target.value, 10) || 1)}
+                className="w-16 rounded border border-gray-300 px-2 py-1 text-sm disabled:opacity-50"
+              />
+            </div>
+
+            <div className="w-24 text-right font-medium text-gray-900">
+              {formatPrice(line.linePriceWithTax)}
+            </div>
+
+            <button
+              type="button"
+              onClick={() => remove(line.id)}
+              disabled={pending}
+              className="text-sm text-gray-400 hover:text-red-600 disabled:opacity-50"
+              aria-label={`Remove ${line.productVariant.name}`}
+            >
+              Remove
+            </button>
+          </li>
+        ))}
+      </ul>
+
+      {channelPlans.length > 0 && (
+        <div className="space-y-2 rounded-lg border border-gray-200 bg-white p-4">
+          <h2 className="text-sm font-medium text-gray-700">Subscribe to your whole order</h2>
+          <div className="flex flex-col gap-2">
+            <button
+              type="button"
+              onClick={() => setSellingPlan(null)}
+              disabled={pending}
+              aria-pressed={activePlanId === null}
+              className={`rounded-md border px-3 py-2 text-left text-sm transition disabled:opacity-50 ${
+                activePlanId === null
+                  ? 'border-gray-900 ring-1 ring-gray-900'
+                  : 'border-gray-300 hover:border-gray-900'
+              }`}
+            >
+              <span className="font-medium text-gray-900">No, one-time</span>
+            </button>
+            {channelPlans.map((plan) => {
+              const savings = getPlanSavingsLabel(plan);
+              const hint = [savings, plan.trialDays > 0 ? `${plan.trialDays}-day free trial` : null]
+                .filter(Boolean)
+                .join(' · ');
+              const active = activePlanId === plan.id;
+              return (
+                <button
+                  key={plan.id}
+                  type="button"
+                  onClick={() => setSellingPlan(plan.id)}
+                  disabled={pending}
+                  aria-pressed={active}
+                  className={`rounded-md border px-3 py-2 text-left text-sm transition disabled:opacity-50 ${
+                    active
+                      ? 'border-gray-900 ring-1 ring-gray-900'
+                      : 'border-gray-300 hover:border-gray-900'
+                  }`}
+                >
+                  <span className="block font-medium text-gray-900">
+                    Subscribe — {getPlanCadenceLabel(plan)}
+                  </span>
+                  {hint && <span className="block text-xs text-gray-500">{hint}</span>}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      )}
+
+      <div className="flex items-center justify-between rounded-lg border border-gray-200 bg-white p-4">
+        <span className="text-sm text-gray-600">Subtotal ({itemCount} items)</span>
+        <span className="text-lg font-semibold text-gray-900">{formatPrice(subtotal)}</span>
+      </div>
+    </div>
+  );
+}

package/templates/storefront/src/components/ForgeErrorBeacon.tsx

@@ -0,0 +1,71 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * DEV-ONLY storefront error beacon. Renders nothing.
+ *
+ * Registers `window.onerror` + `window.onunhandledrejection` and POSTs the failure
+ * detail to the same-origin Next API route `/__forge_beacon`, which forwards it
+ * server-side to the in-pod workspace-manager receiver. This surfaces the crash
+ * class the pod's dev-server stderr scan CANNOT see: a client-component runtime
+ * error or a hydration/SSR-boundary throw that never reaches the dev-server's
+ * output. The browser only ever talks SAME-ORIGIN — the API route is the only thing
+ * that knows the pod-internal receiver address.
+ *
+ * Production builds ship zero bytes of this: the literal `NODE_ENV` check is inlined
+ * by the bundler, so the effect body is dead-code-eliminated from `next build` /
+ * `next start` output — a deployed storefront registers no global error handlers and
+ * has no beacon API route reachable in prod (the route itself is dev-gated too).
+ *
+ * The beacon is best-effort and never blocks the page: the POST is fire-and-forget
+ * with `keepalive` so it survives an unload, and a delivery failure is swallowed —
+ * the page's own error boundary still renders. The full
+ * browser → API route → pod → supervisor-fold path is exercised at the e2e layer,
+ * not in this template.
+ */
+export function ForgeErrorBeacon() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') {
+      return;
+    }
+
+    const send = (message: string, stack?: string) => {
+      const body = JSON.stringify({
+        message,
+        stack,
+        route: window.location.pathname,
+        source: 'browser',
+      });
+      // Same-origin POST; keepalive lets it survive a navigation/unload. A failed
+      // delivery is intentionally swallowed — the beacon is a backstop signal, not
+      // a hard dependency of the page.
+      void fetch('/__forge_beacon', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        keepalive: true,
+      }).catch(() => undefined);
+    };
+
+    const onError = (event: ErrorEvent) => {
+      send(event.message || 'window.onerror', event.error?.stack);
+    };
+    const onRejection = (event: PromiseRejectionEvent) => {
+      const reason = event.reason;
+      const message =
+        reason instanceof Error ? reason.message : String(reason ?? 'unhandledrejection');
+      const stack = reason instanceof Error ? reason.stack : undefined;
+      send(message, stack);
+    };
+
+    window.addEventListener('error', onError);
+    window.addEventListener('unhandledrejection', onRejection);
+    return () => {
+      window.removeEventListener('error', onError);
+      window.removeEventListener('unhandledrejection', onRejection);
+    };
+  }, []);
+
+  return null;
+}

package/templates/storefront/src/components/ProductCard.tsx

@@ -1,7 +1,6 @@
-import type { Product } from '@forgecart/sdk/shop';
 import Link from 'next/link';
 
-import { formatPrice, getStartingPrice } from '../lib/forgecart';
+import { formatPrice, getStartingPrice, type Product } from '../lib/forgecart';
 
 /** A product tile linking to its detail page. Used by the home and grid pages. */
 export function ProductCard({ product }: { product: Product }) {