@stacksjs/defaults 0.70.54

package/resources/components/Marketing/Testimonials.stx

@@ -0,0 +1,120 @@
+<script>
+interface TestimonialsProps {
+  testimonials?: string
+}
+
+const { testimonials = [ } = defineProps<TestimonialsProps>()
+
+[
+    {
+      content: 'Stacks is a rapid development framework that has helped me create and maintain frontends, backends, and clouds without worrying about the boilerplate.',
+      author: {
+        name: 'Sheryl Berge',
+        role: 'CEO at Lynch LLC',
+        image: '/images/avatars/avatar-1.png',
+      },
+    },
+    {
+      content: 'The Stacks mantra, "Convention over configuration", has made my development process much smoother and efficient.',
+      author: {
+        name: 'Amy Hahn',
+        role: 'Director at Velocity Industries',
+        image: '/images/avatars/avatar-4.png',
+      },
+    },
+  ],
+  [
+    {
+      content: "Getting started with Stacks was incredibly easy. The Buddy toolkit has been a game changer for my project. I suggest you guys give it a try today! It's probably one of the best decisions you'll ever do for yourself this year.",
+      author: {
+        name: 'Leland Kiehn',
+        role: 'Founder of Kiehn and Sons',
+        image: '/images/avatars/avatar-5.png',
+      },
+    },
+    {
+      content: 'The Stacks framework is a harmony of several engines that has allowed me to build web and desktop applications in highly scalable and privacy-friendly ways.',
+      author: {
+        name: 'Erin Powlowski',
+        role: 'COO at Armstrong Inc',
+        image: '/images/avatars/avatar-2.png',
+      },
+    },
+  ],
+  [
+    {
+      content: 'Stacks has enhanced my productivity as a developer. No more creating boilerplate, and the IDE integration is fantastic.',
+      author: {
+        name: 'Peter Renolds',
+        role: 'Founder of West Inc',
+        image: '/images/avatars/avatar-3.png',
+      },
+    },
+    {
+      content: 'The Stacks CI/CD has allowed me to focus on coding, not publishing. The CI/CD is superb!',
+      author: {
+        name: 'Amy Hahn',
+        role: 'Director at Velocity Industries',
+        image: '/images/avatars/avatar-4.png',
+      },
+    },
+  ],
+]
+</script>
+<section
+  id="testimonials"
+  aria-label="What our customers are saying"
+  class="py-20 sm:py-32 bg-slate-50"
+>
+  <Container>
+    <div class="mx-auto max-w-2xl md:text-center">
+      <h2 class="font-display text-3xl text-slate-900 tracking-tight sm:text-4xl">
+        Enjoyed by businesses and highly recommended by devs across the globe.
+      </h2>
+      <p class="mt-4 text-lg text-slate-700 tracking-tight">
+        The goal of the framework is to help you create & maintain frontends, backends, and clouds—without having to worry about the boilerplate. Stacks is a rapid development framework, meeting all your full stack needs.
+      </p>
+    </div>
+    <ul
+      role="list"
+      class="grid gap-6 grid-cols-1 sm:gap-8 lg:grid-cols-3 mt-16 mx-auto lg:mt-20 max-w-2xl lg:max-w-none"
+    >
+      @foreach(testimonials as column)
+        <li>
+          <ul role="list" class="flex flex-col gap-y-6 sm:gap-y-8">
+            @foreach(column as testimonial)
+              <li>
+                <figure class="relative p-6 bg-white rounded-2xl shadow-slate-900/10 shadow-xl">
+                  <blockquote class="relative">
+                    <p class="text-lg text-slate-900 tracking-tight">
+                      {{ testimonial.content }}
+                    </p>
+                  </blockquote>
+                  <figcaption class="flex relative items-center justify-between mt-6 pt-6 border-slate-100 border-t">
+                    <div>
+                      <div class="font-display text-base text-slate-900">
+                        {{ testimonial.author.name }}
+                      </div>
+                      <div class="mt-1 text-slate-500 text-sm">
+                        {{ testimonial.author.role }}
+                      </div>
+                    </div>
+                    <div class="overflow-hidden bg-slate-50 rounded-full">
+                      <img
+                        class="object-cover h-14 w-14"
+                        src="{{ testimonial.author.image }}"
+                        alt=""
+                        width="56"
+                        height="56"
+                      >
+                    </div>
+                  </figcaption>
+                </figure>
+              </li>
+            @endforeach
+          </ul>
+        </li>
+      @endforeach
+    </ul>
+  </Container>
+</section>

package/resources/components/Pagination.stx

@@ -0,0 +1,149 @@
+<script>
+/**
+ * Pagination component (stacksjs/stacks#1909, P5 from #1910).
+ *
+ * Renders the right shape for whichever paginator variant comes in:
+ *
+ *   - Paginator<T>        → prev / page-numbers / next + first/last jumps
+ *   - SimplePaginator<T>  → prev / next only
+ *   - CursorPaginator<T>  → prev / next only (cursor-based, no page #s)
+ *
+ * The paginator picks up its prev/next URLs from `paginator-request.ts`
+ * (P2) — they include query-string preservation, so search filters
+ * survive across page navigations without extra work here.
+ *
+ * Accessibility: wraps everything in `<nav aria-label="Pagination">`,
+ * sets `aria-current="page"` on the active page, uses real `<a>` tags
+ * (not `<button>`) because pagination is navigation, not action.
+ *
+ * Window-size: the `window` prop controls how many neighbors of the
+ * current page render before the ellipsis kicks in. Default 2 gives
+ * a compact "1 ... 3 4 [5] 6 7 ... 12" shape.
+ *
+ * Algorithm lives in `@stacksjs/ui/pagination` (buildPageSequence /
+ * urlForPage / paginatorVariant) so it's unit-testable independently
+ * of the stx render pipeline.
+ */
+
+import { buildPageSequence, paginatorVariant, urlForPage } from '@stacksjs/ui'
+
+interface PaginationLike {
+  data: unknown[]
+  per_page: number
+  has_more_pages: boolean
+  prev_page_url?: string | null
+  next_page_url?: string | null
+  first_page_url?: string
+  last_page_url?: string
+  // Full paginator only:
+  current_page?: number
+  total?: number
+  last_page?: number
+  from?: number | null
+  to?: number | null
+  // Cursor paginator only:
+  next_cursor?: string | null
+  prev_cursor?: string | null
+}
+
+interface PaginationProps {
+  /** The paginator to render — accepts all three Stacks paginator shapes. */
+  paginator: PaginationLike
+  /**
+   * Page numbers shown on either side of the current page in the full
+   * Paginator variant. `1 ... [3] 4 5 6 7 ... 12` is `window=2`.
+   * @default 2
+   */
+  window?: number
+}
+
+const { paginator, window: windowSize = 2 } = defineProps<PaginationProps>()
+
+const variant = paginatorVariant(paginator)
+const isFull = variant === 'full'
+const isSimple = variant === 'simple'
+const isCursor = variant === 'cursor'
+
+const pages = isFull
+  ? buildPageSequence(paginator.current_page!, paginator.last_page!, windowSize)
+  : []
+
+const baseLink = 'inline-flex items-center px-3 py-2 text-sm font-medium border'
+const activeLink = `${baseLink} border-indigo-500 text-indigo-600 dark:text-indigo-400 bg-indigo-50 dark:bg-indigo-900/30`
+const inactiveLink = `${baseLink} border-gray-300 dark:border-neutral-600 text-gray-700 dark:text-neutral-300 hover:bg-gray-50 dark:hover:bg-neutral-700`
+const disabledLink = `${baseLink} border-gray-200 dark:border-neutral-700 text-gray-400 dark:text-neutral-500 cursor-not-allowed`
+</script>
+
+<nav aria-label="Pagination" class="flex gap-2 items-center justify-between py-3 select-none">
+  @if(isFull)
+    {{-- Mobile: prev / next only (page numbers hidden) --}}
+    <div class="flex sm:hidden flex-1 justify-between">
+      @if(paginator.prev_page_url)
+        <a href="{{ paginator.prev_page_url }}" class="{{ inactiveLink }} rounded-md">Previous</a>
+      @else
+        <span class="{{ disabledLink }} rounded-md">Previous</span>
+      @endif
+      @if(paginator.next_page_url)
+        <a href="{{ paginator.next_page_url }}" class="{{ inactiveLink }} rounded-md">Next</a>
+      @else
+        <span class="{{ disabledLink }} rounded-md">Next</span>
+      @endif
+    </div>
+
+    {{-- Desktop: prev / page numbers / next + "Showing X to Y of Z" --}}
+    <div class="hidden sm:flex sm:flex-1 sm:items-center sm:justify-between">
+      <p class="text-gray-700 text-sm dark:text-neutral-300">
+        @if(paginator.from && paginator.to)
+          Showing <span class="font-medium">{{ paginator.from }}</span>
+          to <span class="font-medium">{{ paginator.to }}</span>
+          of <span class="font-medium">{{ paginator.total }}</span> results
+        @else
+          No results
+        @endif
+      </p>
+
+      <div class="inline-flex -space-x-px rounded-md shadow-sm isolate">
+        @if(paginator.prev_page_url)
+          <a href="{{ paginator.prev_page_url }}" rel="prev" class="{{ inactiveLink }} rounded-l-md" aria-label="Previous page">←</a>
+        @else
+          <span class="{{ disabledLink }} rounded-l-md" aria-label="Previous page">←</span>
+        @endif
+
+        @foreach(pages as p)
+          @if(p === '…')
+            <span class="{{ inactiveLink }}">…</span>
+          @else
+            @if(p === paginator.current_page)
+              <a href="{{ urlForPage(paginator, p) }}" aria-current="page" class="{{ activeLink }}">{{ p }}</a>
+            @else
+              <a href="{{ urlForPage(paginator, p) }}" class="{{ inactiveLink }}">{{ p }}</a>
+            @endif
+          @endif
+        @endforeach
+
+        @if(paginator.next_page_url)
+          <a href="{{ paginator.next_page_url }}" rel="next" class="{{ inactiveLink }} rounded-r-md" aria-label="Next page">→</a>
+        @else
+          <span class="{{ disabledLink }} rounded-r-md" aria-label="Next page">→</span>
+        @endif
+      </div>
+    </div>
+  @endif
+
+  @if(isSimple || isCursor)
+    {{-- Simple / cursor: just prev / next. No page numbers because we
+        don't know last_page (simple) or it doesn't apply (cursor). --}}
+    <div class="flex flex-1 justify-between">
+      @if(paginator.prev_page_url)
+        <a href="{{ paginator.prev_page_url }}" rel="prev" class="{{ inactiveLink }} rounded-md">← Previous</a>
+      @else
+        <span class="{{ disabledLink }} rounded-md">← Previous</span>
+      @endif
+      @if(paginator.next_page_url)
+        <a href="{{ paginator.next_page_url }}" rel="next" class="{{ inactiveLink }} rounded-md">Next →</a>
+      @else
+        <span class="{{ disabledLink }} rounded-md">Next →</span>
+      @endif
+    </div>
+  @endif
+</nav>

package/resources/components/Playground.stx

@@ -0,0 +1,9 @@
+<!--
+  You may reuse this file to demo your component library.
+  All of your components & functions are automatically imported.
+  It is rendered when you run `buddy dev:components`.
+-->
+<HelloWorld
+  greeting="Jane Doe"
+  :show-buttons="true"
+/>

package/resources/components/README.md

@@ -0,0 +1,87 @@
+# The Components Folder
+
+This is where you create your components.
+
+> **Note**
+> If your project does not require any UI components, you can remove this folder. If your library does include components, you may use this readme as the boilerplate of your component library.
+
+## 💡 Get Started
+
+It's easy to get started. The only prerequisite is a basic understanding of HTML, sprinkled with *minimal* JavaScript. In other words, there is virtually no learning curve.
+
+```bash
+# you may use this GitHub template or the following command
+bunx stacks new hello-world
+cd hello-world
+
+buddy install # install deps for all packages
+buddy dev:components # starts the component dev server
+buddy build:components # builds the component library for production-ready use
+```
+
+Additionally, the `package.json` contains some useful snippets you likely want to be aware of.
+
+## 🤖 Usage
+
+Because this project is optimized toward the development of easily reusable & composable component libraries, it’s very easy to use (and distribute):
+
+```vue
+<script setup lang="ts">
+import HelloWorld from 'hello-world-stack'
+</script>
+
+<template>
+  <HelloWorld name="J Doe" />
+</template>
+```
+
+### Tips
+
+This project also includes a simple way to handle your versioning. Through semantic commit names, it will also generate the two changelogs: one as part of the GitHub releases & the one markdown file that's stored within the root of the project.
+
+```bash
+# how to create a git commit
+git add . # select the changes you want to commit
+buddy commit # then simply follow the prompts
+
+# after you successfully committed, you may create a "release"
+buddy release # automates git commits, versioning, and CHANGELOG generation
+```
+
+Read more about these tips in the docs.
+
+### Coding Style
+
+You may want to consider using the "Composition API" with [`<script setup>` SFC syntax](https://github.com/vuejs/rfcs/pull/227), as it is perfectly suited for building component libraries via Stacks. [ESLint](https://github.com/eslint) also comes pre-configured to statically analyze, fix and format your code without the need for Prettier.
+
+When using this template, feel free to adjust it to your needs. It is a framework to help you quickly & efficiently bootstrap and design component libraries using industry best practices.
+
+## 🧪 Testing
+
+```bash
+bun test
+```
+
+## 📈 Changelog
+
+Please see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently.
+
+## 🚜 Contributing
+
+Please review the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
+
+## 🏝 Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+
+## 📄 License
+
+The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/tree/main/LICENSE.md) for more information.
+
+Made with 💙

package/resources/components/Storefront/AnnouncementBar.stx

@@ -0,0 +1,17 @@
+<script>
+interface AnnouncementBarProps {
+  message?: string
+  className?: string
+}
+
+const {
+  message = 'Free shipping on orders over $40 · Vet-formulated · Made in the USA',
+  className = '',
+} = defineProps<AnnouncementBarProps>()
+</script>
+
+<div class="bg-stone-900 text-stone-100 text-xs {{ className }}">
+  <div class="mx-auto px-6 py-2 max-w-6xl text-center tracking-wide">
+    {{ message }}
+  </div>
+</div>

package/resources/components/Storefront/CartDrawer.stx

@@ -0,0 +1,227 @@
+<script>
+/**
+ * Slide-in cart drawer.
+ *
+ * Server-rendered closed by default. The storefront's add-to-cart button
+ * triggers an XHR POST to `/api/cart/add`; on a 200 the drawer's contents
+ * are refreshed (via `/api/cart`) and the drawer slides in. We use small
+ * vanilla DOM for the open/close because stx signals can't reach across
+ * the layout slot in this case — the data-stx-* hooks below are the
+ * agreed-upon interface other components use to drive it.
+ */
+</script>
+
+<div data-stx-cart-drawer class="fixed inset-0 z-50 pointer-events-none" aria-hidden="true">
+  <!-- Backdrop -->
+  <div
+    data-stx-cart-backdrop
+    class="absolute inset-0 bg-stone-900/40 opacity-0 duration-300 ease-out transition-opacity"
+    style="will-change: opacity"
+  ></div>
+
+  <!-- Panel — translate3d + will-change promote it to its own GPU layer so
+      the slide-in doesn't re-paint the underlying header / content layers
+      and cause the perceived flicker on neighboring elements. -->
+  <aside
+    data-stx-cart-panel
+    class="flex absolute bottom-0 right-0 top-0 flex-col max-w-md w-full bg-stone-50 shadow-2xl duration-300 ease-out transition-transform"
+    style="transform: translate3d(100%, 0, 0); will-change: transform"
+    role="dialog"
+    aria-modal="true"
+    aria-label="Cart"
+    tabindex="-1"
+  >
+    <header class="flex items-center justify-between p-6 border-b border-stone-200">
+      <h2 class="font-bold text-lg text-stone-900">Your bowl</h2>
+      <button type="button" data-stx-cart-close class="text-stone-500 focus-visible:text-stone-900 hover:text-stone-900 focus-visible:outline-none" aria-label="Close cart">
+        <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" /></svg>
+      </button>
+    </header>
+
+    <div data-stx-cart-body class="overflow-y-auto flex-1 p-6 space-y-4">
+      <div data-stx-cart-empty class="py-12 text-center">
+        <div class="inline-flex items-center justify-center mx-auto h-14 w-14 bg-stone-100 rounded-full">
+          <svg xmlns="http://www.w3.org/2000/svg" class="h-7 w-7 text-stone-400" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M2.25 3h1.386c.51 0 .955.343 1.087.835l.383 1.437M7.5 14.25a3 3 0 00-3 3h15.75m-12.75-3h11.218c.51 0 .956-.343 1.087-.835l1.872-7.024A1.125 1.125 0 0019.797 5.25H5.106M7.5 14.25L5.106 5.25M6 20.25a.75.75 0 11-1.5 0 .75.75 0 011.5 0zm12.75 0a.75.75 0 11-1.5 0 .75.75 0 011.5 0z" /></svg>
+        </div>
+        <p class="mt-4 font-medium text-sm text-stone-700">Your bowl is empty.</p>
+        <p class="mt-1 text-stone-500 text-xs">Pick a treat and we'll start one.</p>
+        <a href="/products" class="inline-flex gap-2 items-center mt-5 px-5 py-2.5 font-semibold text-stone-50 text-xs bg-stone-900 hover:bg-stone-800 rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-stone-50 focus-visible:ring-stone-900 transition-colors">
+          Browse the shop
+          <svg xmlns="http://www.w3.org/2000/svg" class="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M13.5 4.5L21 12m0 0l-7.5 7.5M21 12H3"/></svg>
+        </a>
+      </div>
+      <ul data-stx-cart-list class="hidden space-y-4"></ul>
+    </div>
+
+    <footer data-stx-cart-footer class="hidden p-6 space-y-4 border-stone-200 border-t">
+      <div class="flex justify-between text-sm"><span class="text-stone-600">Subtotal</span><span class="font-bold text-stone-900" data-stx-cart-subtotal>$0.00</span></div>
+      <a href="/cart" class="block px-6 py-3 w-full font-semibold text-center text-sm text-stone-900 border border-stone-300 rounded-full hover:border-stone-900 transition-colors">View cart</a>
+      <a href="/checkout/contact" class="block px-6 py-3 w-full font-semibold text-center text-sm text-stone-50 bg-stone-900 hover:bg-stone-800 rounded-full transition-colors">Checkout</a>
+    </footer>
+  </aside>
+</div>
+
+<script data-stx-scoped>
+;(() => {
+  // Idempotency guard. SPA fragment swaps re-inject scoped scripts when
+  // the cart link is followed; without this, every navigation stacked
+  // another set of click listeners on [data-stx-add-to-cart] buttons,
+  // and a single click would fire two/three/N XHRs — the user-visible
+  // tell was a brief flicker as the drawer opened, refreshed, then
+  // refreshed again from the duplicate handlers.
+  if (window.__stxCartWired) return
+  window.__stxCartWired = true
+
+  const root = document.querySelector('[data-stx-cart-drawer]')
+  if (!root) return
+  const backdrop = root.querySelector('[data-stx-cart-backdrop]')
+  const panel = root.querySelector('[data-stx-cart-panel]')
+  const closeBtn = root.querySelector('[data-stx-cart-close]')
+  const list = root.querySelector('[data-stx-cart-list]')
+  const empty = root.querySelector('[data-stx-cart-empty]')
+  const footer = root.querySelector('[data-stx-cart-footer]')
+  const subtotalEl = root.querySelector('[data-stx-cart-subtotal]')
+
+  // Reserve the scrollbar gutter on <html> so locking page scroll while
+  // the drawer is open doesn't cause the page width to jump (~17px on
+  // platforms with overlay scrollbars off). This was the visible flicker
+  // on neighboring elements when the drawer slid in: the page reflowed
+  // because the scrollbar disappeared.
+  document.documentElement.style.scrollbarGutter = 'stable'
+
+  let lastFocus = null
+
+  function open() {
+    lastFocus = document.activeElement
+    root.style.pointerEvents = 'auto'
+    root.setAttribute('aria-hidden', 'false')
+    backdrop.style.opacity = '1'
+    panel.style.transform = 'translate3d(0, 0, 0)'
+    document.body.style.overflow = 'hidden'
+    // Move focus into the panel so Esc + Tab work as expected.
+    requestAnimationFrame(() => { panel.focus({ preventScroll: true }) })
+  }
+  function shut() {
+    root.style.pointerEvents = 'none'
+    root.setAttribute('aria-hidden', 'true')
+    backdrop.style.opacity = '0'
+    panel.style.transform = 'translate3d(100%, 0, 0)'
+    document.body.style.overflow = ''
+    if (lastFocus && typeof lastFocus.focus === 'function') {
+      try { lastFocus.focus({ preventScroll: true }) } catch { /* element gone */ }
+    }
+  }
+
+  backdrop?.addEventListener('click', shut)
+  closeBtn?.addEventListener('click', shut)
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && root.getAttribute('aria-hidden') === 'false') shut()
+  })
+
+  function escapeHtml(s) {
+    return String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
+  }
+
+  function render(items, subtotal) {
+    if (!list || !empty || !footer) return
+    if (!items || items.length === 0) {
+      list.classList.add('hidden')
+      empty.classList.remove('hidden')
+      footer.classList.add('hidden')
+      return
+    }
+    empty.classList.add('hidden')
+    list.classList.remove('hidden')
+    footer.classList.remove('hidden')
+    list.innerHTML = items.map((it) => {
+      const slug = escapeHtml(it.slug || '')
+      const name = escapeHtml(it.name || '')
+      const image = escapeHtml(it.image || '')
+      const qty = Number(it.qty) || 0
+      const price = Number(it.price) || 0
+      const lineTotal = Number(it.lineTotal) || 0
+      return [
+        '<li class="flex gap-3 items-start">',
+        '  <a href="/products/' + slug + '" class="block overflow-hidden flex-shrink-0 h-16 w-16 bg-stone-200 rounded-xl">',
+        '    <img src="' + image + '" alt="' + name + '" class="object-cover h-full w-full">',
+        '  </a>',
+        '  <div class="flex-1 min-w-0">',
+        '    <p class="font-semibold text-sm text-stone-900 truncate">' + name + '</p>',
+        '    <p class="mt-0.5 text-stone-500 text-xs">Qty ' + qty + ' · $' + price.toFixed(2) + '</p>',
+        '  </div>',
+        '  <p class="font-semibold text-sm text-stone-900">$' + lineTotal.toFixed(2) + '</p>',
+        '</li>',
+      ].join('')
+    }).join('')
+    if (subtotalEl) subtotalEl.textContent = '$' + (Number(subtotal) || 0).toFixed(2)
+  }
+
+  let inflightRefresh = null
+  async function refresh() {
+    // Coalesce concurrent refreshes — if a click fires two refresh() in a
+    // row (e.g. add-to-cart + open both call refresh), they reuse the
+    // same network request and the drawer doesn't briefly toggle between
+    // empty and populated.
+    if (inflightRefresh) return inflightRefresh
+    inflightRefresh = (async () => {
+      try {
+        const res = await fetch('/api/cart', {
+          credentials: 'same-origin',
+          headers: { 'X-Requested-With': 'XMLHttpRequest' },
+        })
+        if (!res.ok) return
+        const data = await res.json()
+        render(data.items || [], data.subtotal || 0)
+        const badge = document.querySelector('[data-stx-cart-count]')
+        if (badge) {
+          const total = (data.items || []).reduce((s, i) => s + (Number(i.qty) || 0), 0)
+          badge.textContent = String(total)
+          badge.classList.toggle('hidden', total === 0)
+        }
+      }
+      catch { /* leave existing render in place */ }
+      finally { inflightRefresh = null }
+    })()
+    return inflightRefresh
+  }
+
+  // Public hooks for other components to call.
+  window.stxCart = {
+    open: () => { open(); refresh() },
+    shut,
+    refresh,
+  }
+
+  // Wire any add-to-cart submit buttons via a single document-level
+  // delegated listener. Compared to attaching per-button listeners, this:
+  //   - Stays correct when the catalog page fragment swaps in new
+  //     [data-stx-add-to-cart] buttons.
+  //   - Can't double-fire if the scoped script runs more than once (the
+  //     guard at the top is the primary defense; this is belt-and-braces).
+  document.addEventListener('click', async (e) => {
+    const target = e.target instanceof Element ? e.target : null
+    if (!target) return
+    const btn = target.closest('[data-stx-add-to-cart]')
+    if (!btn) return
+    const form = btn.closest('form')
+    if (!form) return
+    e.preventDefault()
+    const fd = new FormData(form)
+    btn.setAttribute('aria-busy', 'true')
+    try {
+      const res = await fetch(form.action || '/api/cart/add', {
+        method: form.method || 'POST',
+        body: fd,
+        credentials: 'same-origin',
+        headers: { 'X-Requested-With': 'XMLHttpRequest', 'Accept': 'application/json' },
+      })
+      if (res.ok) {
+        await refresh()
+        open()
+      }
+      else { form.submit() }
+    } catch { form.submit() }
+    finally { btn.removeAttribute('aria-busy') }
+  })
+})()
+</script>

package/resources/components/Storefront/CheckoutSteps.stx

@@ -0,0 +1,50 @@
+<script>
+interface CheckoutStep {
+  key: string
+  label: string
+  href?: string
+}
+
+interface CheckoutStepsProps {
+  current: string
+  steps?: CheckoutStep[]
+}
+
+const {
+  current,
+  steps = [
+    { key: 'contact', label: 'Contact', href: '/checkout/contact' },
+    { key: 'shipping', label: 'Shipping', href: '/checkout/shipping' },
+    { key: 'payment', label: 'Payment', href: '/checkout/payment' },
+  ],
+} = defineProps<CheckoutStepsProps>()
+
+const currentIndex = steps.findIndex(s => s.key === current)
+</script>
+
+<nav aria-label="Checkout progress" class="mb-10">
+  <ol class="flex gap-3 items-center text-sm">
+    @foreach (steps as step, i)
+      <li class="flex flex-1 gap-3 items-center min-w-0">
+        <span class="inline-flex h-7 w-7 items-center justify-center rounded-full text-xs font-semibold flex-shrink-0
+          {{ i < currentIndex ? 'bg-stone-900 text-stone-50' : '' }}
+          {{ i === currentIndex ? 'bg-stone-900 text-stone-50 ring-4 ring-stone-200' : '' }}
+          {{ i > currentIndex ? 'bg-stone-200 text-stone-500' : '' }}">
+          @if (i < currentIndex)
+            <svg xmlns="http://www.w3.org/2000/svg" class="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke-width="3" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M4.5 12.75l6 6 9-13.5" /></svg>
+          @else
+            {{ i + 1 }}
+          @endif
+        </span>
+        @if (step.href && i <= currentIndex)
+          <a href="{{ step.href }}" class="font-semibold text-stone-900 truncate hover:underline">{{ step.label }}</a>
+        @else
+          <span class="{{ i === currentIndex ? 'text-stone-900 font-semibold' : 'text-stone-500' }} truncate">{{ step.label }}</span>
+        @endif
+        @if (i < steps.length - 1)
+          <span class="hidden md:block flex-1 h-px bg-stone-200"></span>
+        @endif
+      </li>
+    @endforeach
+  </ol>
+</nav>