@pylonsync/create-pylon 0.19.0 → 0.20.0

package/templates/shop/app/(marketing)/success/page.tsx

@@ -1,33 +1,86 @@
 import React from "react";
-import { Link, type Metadata } from "@pylonsync/react";
-import { WRAP } from "@/components/marketing";
+import { Link, type Metadata, type PageProps } from "@pylonsync/react";
+import { Check } from "lucide-react";
+import { WRAP, BUTTON_DARK } from "@/components/marketing";
 import { siteConfig } from "@/lib/site.config";
 
 export const metadata: Metadata = {
-  title: `Thank you — ${siteConfig.brand.name}`,
+  title: `Thank you | ${siteConfig.brand.name}`,
   description: "Your order is confirmed.",
 };
 
-// `app/success/page.tsx` → `/success`. Where Stripe sends the shopper after a
-// completed Checkout (the `successUrl` passed to the `checkout` action). The
-// order is settled server-side by the signed `stripeWebhook` — this page is
-// just the friendly landing, so it doesn't need to read the session id Stripe
-// appends. Rendered with the normal marketing chrome (nav + footer).
-export default function CheckoutSuccess() {
+// `app/(marketing)/success/page.tsx` → `/success`. Two ways in:
+//   • Stripe sends the shopper here after a completed Checkout (the
+//     `successUrl` passed to the `checkout` action). The signed `stripeWebhook`
+//     settles the order, so this page doesn't read the session id Stripe appends.
+//   • With no Stripe key, the cart sends the shopper here with `?order=reserved`
+//     (plus `&sold=` naming any line that sold out during checkout).
+// The page shows no order details: Order rows hold PII and are owner-only.
+export default function CheckoutSuccess({ searchParams }: PageProps) {
+  const reserved = searchParams.order === "reserved";
+  const sold = (searchParams.sold ?? "").split(",").filter(Boolean);
+  const { checkout, brand } = siteConfig;
+
+  const steps = reserved
+    ? ["Order reserved", "Payment link sent by email", "Packed and shipped from Dallas"]
+    : ["Payment received", "Packed in the studio", "Shipped from Dallas"];
+
   return (
-    <section className={`${WRAP} flex min-h-[60vh] flex-col items-center justify-center py-20 text-center`}>
-      <div className="flex size-12 items-center justify-center rounded-full bg-brand text-xl text-white">✓</div>
-      <h1 className="mt-5 text-2xl font-semibold tracking-tight text-zinc-900">Thank you for your order</h1>
-      <p className="mx-auto mt-3 max-w-md text-[15px] leading-relaxed text-zinc-500">
-        Your payment went through and we&apos;ve emailed your receipt. We&apos;ll be in touch when it ships —
-        everything is hand-made, so give us a couple of business days.
-      </p>
-      <Link
-        href="/#shop"
-        className="mt-7 inline-flex h-11 items-center rounded-full bg-brand px-6 text-sm font-medium text-white transition-opacity hover:opacity-90"
-      >
-        Keep shopping
-      </Link>
+    <section className={`${WRAP} grid min-h-[72vh] items-center gap-14 py-16 md:grid-cols-[1.4fr_1fr] md:gap-20 md:py-20`}>
+      <div>
+        <h1 className="rise font-display text-[3rem] font-light leading-[1] tracking-[-0.03em] text-ink sm:text-[4.25rem]">
+          {reserved ? "Your order is reserved." : "Thank you for your order."}
+        </h1>
+        <p
+          className="rise mt-6 max-w-[46ch] text-[17px] leading-[1.65] text-ink-2"
+          style={{ animationDelay: "100ms" }}
+        >
+          {reserved ? checkout.reservedMessage : checkout.paidMessage}
+        </p>
+        {sold.length > 0 ? (
+          <p className="mt-4 max-w-[46ch] text-[14.5px] leading-relaxed text-brand">
+            {sold.join(", ")} sold out before we could hold {sold.length === 1 ? "it" : "them"}, so{" "}
+            {sold.length === 1 ? "it is" : "they are"} not in this order.
+          </p>
+        ) : null}
+
+        <ol className="rise mt-10 max-w-md border-t border-ink/15" style={{ animationDelay: "200ms" }}>
+          {steps.map((step, i) => (
+            <li key={step} className="flex items-center gap-4 border-b border-ink/15 py-4 text-[15px]">
+              <span
+                className={
+                  "flex size-7 shrink-0 items-center justify-center rounded-full text-[12px] tabular-nums " +
+                  (i === 0 ? "bg-ink text-warm-white" : "border border-ink/20 text-ink-2")
+                }
+              >
+                {i === 0 ? <Check className="size-3.5" strokeWidth={2} /> : i + 1}
+              </span>
+              <span className={i === 0 ? "font-medium text-ink" : "text-ink-2"}>{step}</span>
+            </li>
+          ))}
+        </ol>
+
+        <div className="rise mt-10 flex flex-wrap items-center gap-5" style={{ animationDelay: "300ms" }}>
+          <Link href="/#shop" className={BUTTON_DARK}>
+            Back to the shop
+          </Link>
+          <a
+            href={`mailto:${brand.email}`}
+            className="text-[14px] text-ink-2 underline decoration-ink/20 underline-offset-4 transition-colors hover:text-ink hover:decoration-ink"
+          >
+            Questions? {brand.email}
+          </a>
+        </div>
+      </div>
+
+      <div className="relative aspect-[4/5] overflow-hidden bg-stone">
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img
+          src={checkout.image}
+          alt=""
+          className="settle size-full object-cover"
+        />
+      </div>
     </section>
   );
 }

package/templates/shop/app/globals.css

@@ -19,6 +19,14 @@
   --brand: #4f46e5;
   --brand-soft: #eef2ff;
   --paper: #fafafa;
+  /* Storefront palette: bone page, warm near-black type, stone for image
+     wells, and a dark espresso band. */
+  --ink: #1f1b17;
+  --ink-2: #6d645a;
+  --warm-white: #f6f2eb;
+  --stone: #e6ded2;
+  --espresso: #221d18;
+  --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);
   --background: oklch(1 0 0);
   --foreground: oklch(0.141 0.005 285.823);
   --card: oklch(1 0 0);
@@ -112,6 +120,12 @@
   --color-brand: var(--brand);
   --color-brand-soft: var(--brand-soft);
   --color-paper: var(--paper);
+  --color-ink: var(--ink);
+  --color-ink-2: var(--ink-2);
+  --color-warm-white: var(--warm-white);
+  --color-stone: var(--stone);
+  --color-espresso: var(--espresso);
+  --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);
   --color-chart-1: var(--chart-1);
   --color-chart-2: var(--chart-2);
   --color-chart-3: var(--chart-3);
@@ -141,7 +155,7 @@
     color: var(--color-foreground);
     font-family: var(
       --font-sans,
-      Inter,
+      "DM Sans",
       ui-sans-serif,
       system-ui,
       -apple-system,
@@ -153,3 +167,82 @@
     cursor: pointer;
   }
 }
+
+.font-display {
+  font-family: var(--font-display, "Newsreader", Georgia, "Times New Roman", serif);
+  font-optical-sizing: auto;
+}
+
+/* Storefront motion. Every animation uses transform and opacity only, and
+   all of it stops under prefers-reduced-motion. */
+@keyframes rise {
+  from {
+    opacity: 0;
+    transform: translateY(18px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+@keyframes settle {
+  from {
+    transform: scale(1.06);
+  }
+  to {
+    transform: scale(1);
+  }
+}
+@keyframes stock-tick {
+  0% {
+    background-color: color-mix(in srgb, var(--brand) 22%, transparent);
+  }
+  100% {
+    background-color: transparent;
+  }
+}
+@keyframes ping-soft {
+  0% {
+    transform: scale(1);
+    opacity: 0.55;
+  }
+  80%,
+  100% {
+    transform: scale(2.6);
+    opacity: 0;
+  }
+}
+
+.rise {
+  animation: rise 1s var(--ease-out-quint) both;
+}
+.settle {
+  animation: settle 2.2s var(--ease-out-quint) both;
+}
+.stock-tick {
+  animation: stock-tick 1.6s var(--ease-out-quint) both;
+}
+.ping-soft {
+  animation: ping-soft 2s cubic-bezier(0.2, 0.6, 0.3, 1) infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .rise,
+  .settle,
+  .stock-tick,
+  .ping-soft {
+    animation: none;
+  }
+}
+
+/* Paper grain over the storefront. Fixed and non-interactive, so it never
+   repaints on scroll. */
+.grain::after {
+  content: "";
+  position: fixed;
+  inset: 0;
+  z-index: 60;
+  pointer-events: none;
+  opacity: 0.035;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+}

package/templates/shop/app/layout.tsx

@@ -31,10 +31,10 @@ export default function RootLayout({ children }: LayoutProps) {
         <meta charSet="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
         {/* No <title> here — each page's exported `metadata` sets it. */}
-        {/* Inter is declared in app.ts (fonts: [...]) and self-hosted by the
-            build — the runtime injects @font-face + <link rel=preload> + a
-            size-adjusted fallback here automatically. No third-party request,
-            no layout shift; change the family in app.ts. */}
+        {/* DM Sans and Newsreader are declared in app.ts (fonts: [...]) and
+            self-hosted by the build. The runtime injects @font-face + <link
+            rel=preload> + a size-adjusted fallback here automatically. Change
+            the families in app.ts. */}
         {/* Tailwind is compiled by Pylon from app/globals.css and injected here. */}
       </head>
       <body className="flex min-h-screen flex-col bg-background text-foreground antialiased">

package/templates/shop/app/login/page.tsx

@@ -18,14 +18,14 @@ export default function LoginPage({ auth, response }: PageProps) {
   if (auth.user_id && !auth.user_id.startsWith("guest_")) response.redirect("/dashboard");
   const { brand } = siteConfig;
   return (
-    <div className="flex min-h-screen items-center justify-center bg-white px-6 py-12">
-      <div className="w-full max-w-[400px] rounded-2xl border border-zinc-200/70 p-8">
+    <div className="flex min-h-screen items-center justify-center bg-warm-white px-6 py-12">
+      <div className="w-full max-w-[400px] rounded-2xl border border-ink/10 bg-white p-8">
         <Link href="/" className="inline-flex">
-          <span className="flex size-9 items-center justify-center rounded-xl bg-zinc-900 text-base font-bold text-white">
+          <span className="font-display flex size-9 items-center justify-center rounded-full bg-ink text-[18px] text-warm-white">
             {brand.letter}
           </span>
         </Link>
-        <h1 className="mt-5 text-[22px] font-semibold tracking-tight text-zinc-900">
+        <h1 className="font-display mt-5 text-[26px] font-normal tracking-[-0.01em] text-ink">
           {brand.name} dashboard
         </h1>
         <p className="mt-1 text-[13px] text-zinc-500">

package/templates/shop/app.ts

@@ -46,7 +46,7 @@ const Product = entity(
     name: field.string(),
     priceCents: field.int(),
     description: field.string().optional(),
-    image: field.string().optional(), // emoji or image URL
+    image: field.string().optional(), // photo URL or /public path
     stock: field.int().default(0),
   },
   { indexes: [{ name: "by_slug", fields: ["slug"], unique: true }] },
@@ -133,15 +133,27 @@ const manifest = buildManifest({
   actions: fns.actions,
   policies: [productPolicy, orderPolicy, userPolicy],
   auth: auth(),
-  // Self-hosted Inter (next/font parity): the build fetches the woff2, serves it
+  // Self-hosted fonts (next/font parity): the build fetches the woff2, serves it
   // same-origin (no third-party request, no FOUT), preloads it, and synthesizes a
-  // size-adjusted fallback face so there's no layout shift. globals.css reads it
-  // via `var(--font-sans, …)`; layout.tsx carries no font <link>.
+  // size-adjusted fallback face so there's no layout shift. globals.css reads
+  // them via `var(--font-sans, …)` and `var(--font-display, …)`; layout.tsx
+  // carries no font <link>.
   fonts: [
+    // Body text, labels, buttons, prices.
     font({
-      family: "Inter",
+      family: "DM Sans",
       variable: "--font-sans",
-      weights: ["400", "500", "600", "700"],
+      weights: ["400", "500", "600"],
+      subsets: ["latin"],
+      display: "swap",
+      preload: true,
+    }),
+    // The serif for the brand name, headings and product names.
+    font({
+      family: "Newsreader",
+      variable: "--font-display",
+      weights: ["300", "400", "500"],
+      styles: ["normal", "italic"],
       subsets: ["latin"],
       display: "swap",
       preload: true,

package/templates/shop/components/cart-button.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import React from "react";
+import { ShoppingBag } from "lucide-react";
+import { cart, countItems, useCart } from "@/lib/cart-store";
+
+// The nav cart button. Reads the shared cart store so the count matches the
+// grid, and opens the cart panel rendered by the shop island. The count
+// re-mounts on change, which replays its pop-in animation.
+export function CartButton() {
+  const { lines } = useCart();
+  const count = countItems(lines);
+  return (
+    <button
+      type="button"
+      onClick={cart.open}
+      aria-label={count === 1 ? "Cart, 1 item" : `Cart, ${count} items`}
+      className="inline-flex h-10 items-center gap-2 rounded-full pr-1 pl-3 text-[14px] text-ink transition-colors duration-300 hover:bg-ink/[0.05]"
+    >
+      <ShoppingBag className="size-[18px]" strokeWidth={1.25} />
+      <span className="hidden sm:inline">Cart</span>
+      <span
+        key={count}
+        className={
+          "inline-flex h-6 min-w-6 items-center justify-center rounded-full px-1.5 text-[12px] font-medium tabular-nums transition-colors duration-300 " +
+          (count > 0 ? "animate-in zoom-in-50 bg-ink text-warm-white duration-300" : "bg-ink/[0.07] text-ink/60")
+        }
+      >
+        {count}
+      </span>
+    </button>
+  );
+}

package/templates/shop/components/marketing.tsx

@@ -1,96 +1,26 @@
 import React from "react";
 
-// Reusable presentational pieces for the landing page. All server-rendered —
-// no client JS. Restyle here and the whole page follows. The brand accent
-// (`text-brand`, `bg-brand-soft`) comes from CSS vars set on <html> in
-// app/layout.tsx, which read lib/site.config.ts — so re-theming is one edit.
+// Server-rendered layout helpers for the storefront pages. Restyle here and
+// every page follows. The brand accent (`text-brand`, `bg-brand`) comes from
+// CSS vars set on <html> in app/layout.tsx, which read lib/site.config.ts.
 
-// Shared container: a contained, centered column.
-export const WRAP = "mx-auto w-full max-w-3xl px-6";
+// Shared container. The storefront runs wide so product photos stay large.
+export const WRAP = "mx-auto w-full max-w-[1360px] px-5 sm:px-8 lg:px-12";
 
-export function Eyebrow({ children }: { children: React.ReactNode }) {
-  return (
-    <p className="font-mono text-[11px] font-semibold uppercase tracking-[0.14em] text-brand">
-      {children}
-    </p>
-  );
-}
+// Pill buttons. `BUTTON_DARK` is the primary action; `BUTTON_LINE` sits beside it.
+export const BUTTON_DARK =
+  "inline-flex h-12 items-center justify-center gap-2 rounded-full bg-ink px-7 text-[14.5px] font-medium text-warm-white transition-[background-color,transform] duration-300 ease-out-quint hover:bg-brand active:scale-[0.98]";
+export const BUTTON_LINE =
+  "inline-flex h-12 items-center justify-center gap-2 rounded-full border border-ink/25 px-7 text-[14.5px] font-medium text-ink transition-[background-color,border-color,transform] duration-300 ease-out-quint hover:border-ink hover:bg-ink/[0.04] active:scale-[0.98]";
 
-// "New / Coming soon"-style pill for the hero.
-export function Badge({ children }: { children: React.ReactNode }) {
+// A section heading in the display serif.
+export function SectionHeading({ id, children }: { id?: string; children: React.ReactNode }) {
   return (
-    <span className="inline-flex items-center gap-2 rounded-full border border-zinc-200 bg-white py-1 pl-1.5 pr-3 text-[13px] text-zinc-600 shadow-sm">
-      <span className="inline-block size-1.5 rounded-full bg-brand" />
+    <h2
+      id={id}
+      className="font-display text-[2.5rem] font-light leading-[1.02] tracking-[-0.02em] text-balance sm:text-[3.5rem]"
+    >
       {children}
-    </span>
-  );
-}
-
-export function Divider() {
-  return (
-    <div className={WRAP}>
-      <div className="border-t border-zinc-200/70" />
-    </div>
-  );
-}
-
-export function SectionHead({
-  eyebrow,
-  title,
-  body,
-}: {
-  eyebrow: string;
-  title: string;
-  body?: string;
-}) {
-  return (
-    <div>
-      <Eyebrow>{eyebrow}</Eyebrow>
-      <h2 className="mt-4 text-balance text-2xl font-semibold leading-[1.15] tracking-[-0.02em] sm:text-3xl">
-        {title}
-      </h2>
-      {body ? (
-        <p className="mt-4 max-w-xl text-[15px] leading-relaxed text-zinc-500">
-          {body}
-        </p>
-      ) : null}
-    </div>
+    </h2>
   );
 }
-
-// A grid of value props — icon + title + body.
-export function FeatureGrid({
-  items,
-}: {
-  items: { title: string; body: string; icon?: string }[];
-}) {
-  return (
-    <div className="grid gap-6 sm:grid-cols-3">
-      {items.map((f) => (
-        <div key={f.title}>
-          {f.icon ? (
-            <span className="flex size-9 items-center justify-center rounded-lg bg-brand-soft text-brand">
-              {f.icon}
-            </span>
-          ) : null}
-          <h3 className="mt-4 text-[15px] font-semibold text-zinc-900">
-            {f.title}
-          </h3>
-          <p className="mt-2 text-[14px] leading-relaxed text-zinc-500">
-            {f.body}
-          </p>
-        </div>
-      ))}
-    </div>
-  );
-}
-
-// Initials for testimonial avatars, so the cards look finished without a photo.
-export function initials(name: string) {
-  return name
-    .split(/\s+/)
-    .map((w) => w[0])
-    .join("")
-    .slice(0, 2)
-    .toUpperCase();
-}

package/templates/shop/components/shelf-count.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import React from "react";
+import { useShelf } from "@/lib/shelf-store";
+
+// The live stock line in the hero. The product grid publishes shelf totals to
+// lib/shelf-store.ts from its live Product query, so this count drops for
+// every open page when someone checks out. Renders a fixed-width placeholder
+// until the first totals arrive, so the hero does not shift.
+export function ShelfCount() {
+  const shelf = useShelf();
+  return (
+    <p className="flex items-center gap-3 text-[13.5px] text-ink/75" aria-live="polite">
+      <span className="relative flex size-2">
+        <span className="ping-soft absolute inset-0 rounded-full bg-[#5d7a4a]" />
+        <span className="relative size-2 rounded-full bg-[#5d7a4a]" />
+      </span>
+      {shelf ? (
+        <span>
+          <span key={shelf.units} className="stock-tick rounded px-0.5 font-medium tabular-nums text-ink">
+            {shelf.units}
+          </span>{" "}
+          pieces on the studio shelf
+          {shelf.low > 0 ? (
+            <>
+              <span className="mx-2 text-ink/30">/</span>
+              <span className="tabular-nums">{shelf.low}</span> running low
+            </>
+          ) : null}
+        </span>
+      ) : (
+        <span className="inline-block h-4 w-56 rounded bg-ink/[0.06]" />
+      )}
+    </p>
+  );
+}

package/templates/shop/functions/checkout.ts

@@ -1,6 +1,7 @@
 import { action, v } from "@pylonsync/functions";
 import { stripeRequest, assertSafeRedirectUrl } from "@pylonsync/stripe";
-import type { CheckoutResult } from "../lib/shop";
+import { shippingCents, type CheckoutResult } from "../lib/shop";
+import { siteConfig } from "../lib/site.config";
 
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const CURRENCY = "usd";
@@ -92,6 +93,11 @@ export default action<
     // If the session can't be created (bad key, network error, Stripe down) we
     // MUST release the held stock — there's no session that would ever expire to
     // do it for us, so without this the units would be stranded off the shelf.
+    // Shipping follows the same terms the cart shows: a flat rate, free at or
+    // above the threshold. Prices come from the held lines, not the client.
+    const subtotal = held.lines.reduce((s, l) => s + l.unitPriceCents * l.qty, 0);
+    const shipping = shippingCents(subtotal, siteConfig.checkout.shipping);
+
     let session: { id: string; url: string } | undefined;
     try {
       session = await stripeRequest<{ id: string; url: string }>(
@@ -114,6 +120,16 @@ export default action<
               product_data: { name: l.name },
             },
           })),
+          shipping_address_collection: { allowed_countries: ["US"] },
+          shipping_options: [
+            {
+              shipping_rate_data: {
+                type: "fixed_amount",
+                display_name: shipping === 0 ? "Free shipping" : "Standard shipping",
+                fixed_amount: { amount: shipping, currency: CURRENCY },
+              },
+            },
+          ],
         },
       );
     } catch {

package/templates/shop/lib/cart-store.ts

@@ -0,0 +1,57 @@
+// A tiny client-side cart store shared by the product grid (app/(marketing)/
+// shop-client.tsx) and the nav cart button (components/cart-button.tsx). The
+// two live in different client islands, so React state can't be lifted between
+// them; this module holds the cart and both islands subscribe with
+// `useSyncExternalStore`. Cart contents are slug → qty; the grid clamps them to
+// live stock when it renders.
+
+import { useSyncExternalStore } from "react";
+
+export type CartLines = Record<string, number>;
+
+type CartState = { lines: CartLines; open: boolean };
+
+let state: CartState = { lines: {}, open: false };
+const listeners = new Set<() => void>();
+
+function emit() {
+  listeners.forEach((l) => l());
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function getSnapshot() {
+  return state;
+}
+
+// The server render has no cart; every island sees the same empty snapshot.
+const SERVER_STATE: CartState = { lines: {}, open: false };
+function getServerSnapshot() {
+  return SERVER_STATE;
+}
+
+export function useCart() {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+export const cart = {
+  setLines(update: (lines: CartLines) => CartLines) {
+    state = { ...state, lines: update(state.lines) };
+    emit();
+  },
+  open() {
+    state = { ...state, open: true };
+    emit();
+  },
+  close() {
+    state = { ...state, open: false };
+    emit();
+  },
+};
+
+export function countItems(lines: CartLines) {
+  return Object.values(lines).reduce((s, q) => s + q, 0);
+}

package/templates/shop/lib/shelf-store.ts

@@ -0,0 +1,35 @@
+// Live shelf totals, shared between client islands. The product grid
+// (app/(marketing)/shop-client.tsx) owns the live Product query and publishes
+// the totals here; the hero's shelf count (components/shelf-count.tsx) reads
+// them. One query and one guest session serve both islands.
+
+import { useSyncExternalStore } from "react";
+
+export type ShelfTotals = { units: number; low: number; soldOut: number } | null;
+
+let totals: ShelfTotals = null;
+const listeners = new Set<() => void>();
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function publishShelf(stocks: number[], lowAt: number) {
+  const next = {
+    units: stocks.reduce((s, n) => s + Math.max(0, n), 0),
+    low: stocks.filter((n) => n > 0 && n <= lowAt).length,
+    soldOut: stocks.filter((n) => n <= 0).length,
+  };
+  if (totals && totals.units === next.units && totals.low === next.low && totals.soldOut === next.soldOut) return;
+  totals = next;
+  listeners.forEach((l) => l());
+}
+
+export function useShelf(): ShelfTotals {
+  return useSyncExternalStore(
+    subscribe,
+    () => totals,
+    () => null,
+  );
+}

package/templates/shop/lib/shop.ts

@@ -43,3 +43,30 @@ export type CheckoutResult =
 export function formatPrice(cents: number): string {
   return `$${(cents / 100).toFixed(cents % 100 === 0 ? 0 : 2)}`;
 }
+
+// How a product's stock reads on the storefront. "low" at 3 or fewer.
+export const LOW_STOCK_AT = 3;
+
+export type StockStatus =
+  | { kind: "sold_out"; label: string }
+  | { kind: "low"; label: string }
+  | { kind: "in_stock"; label: string };
+
+export function stockStatus(stock: number): StockStatus {
+  if (stock <= 0) return { kind: "sold_out", label: "Sold out" };
+  if (stock <= LOW_STOCK_AT) return { kind: "low", label: stock === 1 ? "Last one" : `Only ${stock} left` };
+  return { kind: "in_stock", label: `${stock} in stock` };
+}
+
+// Shipping terms: a flat rate, free at or above a subtotal threshold. The cart
+// shows these numbers and `checkout` charges them on the Stripe session.
+export type ShippingTerms = { flatCents: number; freeOverCents: number };
+
+// Cents still needed to reach free shipping; 0 once the subtotal qualifies.
+export function freeShippingRemaining(subtotalCents: number, terms: ShippingTerms): number {
+  return Math.max(0, terms.freeOverCents - subtotalCents);
+}
+
+export function shippingCents(subtotalCents: number, terms: ShippingTerms): number {
+  return freeShippingRemaining(subtotalCents, terms) === 0 ? 0 : terms.flatCents;
+}