@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0-mvp.2

package/assets/templates/AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md — __SITE_NAME__ storefront
+
+This storefront was generated by `@thorprovider/storefront`. It is governed by a
+manifest (`storefront.config.json` at the project root) and produced by the
+`storefront` CLI. This file is managed: `storefront sync` regenerates it from the
+package template, and `storefront doctor` reports it as drift when edited by
+hand. Read it before changing anything.
+
+## RULE 0 — Non-negotiable
+
+1. **The `storefront` CLI is the authority.** Every structural change — adding or
+   removing a view or feature, composing sections, changing the theme mode,
+   connecting the backend — goes through `npx @thorprovider/storefront …`. Never
+   copy templates or scaffold structure by hand.
+2. **Derived files are CLI-only; never hand-edit them.** The CLI is the only
+   writer of derived files. If a change seems to need a capability the CLI does
+   not expose, first check the CLI subcommands and the `plan` → `apply`
+   operations envelope; if it is still missing, **STOP and report the gap** —
+   do not hand-edit a derived file. A hand edit is silently overwritten by the
+   next `sync`.
+3. **Hand-edit only user-owned files and the bounded external surface.** Manual
+   edits are limited to the declared user-owned files:
+   `lib/<name>/views/<view>/{schema,content,props,data}.ts`, `lib/<name>/mappers.ts`,
+   `lib/<name>/icon-map.ts`, and `lib/<name>/shell/**` — plus the bounded external
+   customization surface of `app/globals.css` and `app/layout.tsx`: theme design
+   tokens and their foreground pairs, font wiring, and global identity/metadata.
+   Prefer the deterministic `storefront theme` controls (colors, radius, fonts,
+   presets, imports) over hand edits; the bounded surface remains editable when a
+   value has no CLI control.
+   Editing the external files must preserve the CLI-managed wiring: the library
+   stylesheet import, the provider import and marker, the theme-mode marker, and
+   the block token contract. The CLI only appends that wiring idempotently, so a
+   restructure that removes it is drift, not a customization. Everything else is
+   derived (CLI-only).
+4. **Respect the architecture invariants.** UI components come only from
+   `@thorprovider/blocks`; data comes only from `@thorprovider/adapters` and
+   `@thorprovider/runtime/commerce` (never HTTP directly); routing stays the
+   catch-all `app/[[...slug]]/page.tsx`; `@thorprovider/medusa-extended` is not
+   used.
+5. **Verify after every change.** Run `npx @thorprovider/storefront sync`, then
+   `npx @thorprovider/storefront doctor`. `doctor` must report no drift; a build
+   (`yarn build`) is the final acceptance.
+6. **Drive non-trivial customization through the spec-driven loop.** A change
+   that needs judgment — content authoring, prop/data mapping, composition
+   reshaping, or a cross-file redesign whose acceptance is not a CLI assertion —
+   is **non-trivial**: drive it through the spec-driven loop and surface the five
+   stages to the user, **explore → plan → build → verify → inform**. A change the
+   CLI performs deterministically (theme mode, `view add|remove`,
+   `feature add|remove`, `setup`) is recorded in `storefront.config.json` and does
+   **not** require an OpenSpec change — the manifest is its record. Never ask the
+   user to run `openspec` or to approve individual artifacts.
+
+## Workflow model
+
+**bootstrap → compose → customize → verify.** The manifest
+(`storefront.config.json`) is the structural source of truth; the CLI is the only
+writer of derived files; the developer (or agent) edits only user-owned files and
+the bounded external surface of `app/globals.css` and `app/layout.tsx`.
+Customization that needs judgment runs through the spec-driven loop surfaced as
+explore → plan → build → verify → inform.
+See the `storefront-workflow` skill for the full model and the ownership classes.
+
+## Router — intent → skill → CLI
+
+The user states the intent in natural language; load the skill and delegate the
+write to the CLI. Never edit a derived file to achieve the intent.
+
+| Intent | Load skill | Delegate to CLI |
+|---|---|---|
+| Add or remove a view; compose a view's sections | `sf-view-gen` | `storefront views --json`, then `storefront view add\|remove …`; sections via `plan` → `apply` |
+| Customize the theme: colors, radius, fonts, presets; identity/SEO | `sf-theme-gen` | `storefront theme` — `--brand orange`, `--primary <color>`, `--accent <color>`, `--radius <length>`, `--font-sans google:Inter`, `--set light.primary=#f97316`, `--preset <ref>`, `--import <src>`, `--export <file>`, `--mode light\|dark\|system`. Visual values live in `app/globals.css`; the mode in `storefront.config.json`. Inspect with `storefront theme --inspect`. The bounded external surface stays editable by hand |
+| Add or remove a feature (e.g. `checkout`) | `sf-feature` | `storefront features --json`, then `storefront feature add\|remove …` |
+| Connect or re-point the Medusa backend; change region, sales channel, or publishable key | `sf-setup` | `storefront setup --backend-url … --publishable-key … --sales-channel-id … --region-id …` |
+| Edit a view's content/props/data; map props or data; reshape composition; any change whose acceptance is not a CLI assertion (non-trivial) | `storefront-workflow` | spec-driven loop surfaced as **explore → plan → build → verify → inform** — the agent drives it and never asks the user to confirm OpenSpec artifacts; structural edits still go through `storefront …`, verified with `storefront sync` then `storefront doctor` |
+
+The step-by-step procedures live in the skills, not in this file.

package/assets/templates/app/app/[[...slug]]/page.tsx

@@ -1,6 +1,7 @@
 // Generated by Thor Commerce storefront (template: assets/templates/app/app/[[...slug]]/page.tsx)
 
 import { notFound } from 'next/navigation'
+import { buildBreadcrumbListJsonLd, serializeJsonLd } from '@thorprovider/runtime/contracts'
 import { __STOREFRONT_CAMEL__App } from '@/lib/__STOREFRONT__/runtime'
 import { readCartStateForRender } from '@/lib/__STOREFRONT__/cart-state'
 import { StorefrontRenderer } from './renderer'
@@ -24,5 +25,45 @@ export default async function Page({
   const cartState = await readCartStateForRender()
   const initialState = { ...(data.initialState ?? {}), ...cartState }
 
-  return <StorefrontRenderer {...data} initialState={initialState} />
+  // Entity structured data is server-rendered from the real loaded entity and
+  // sanitized so entity text cannot terminate the script element.
+  const jsonLd = data.entitySeo?.jsonLd
+  // The entity OpenGraph type (`product`/`CollectionPage`) is emitted here, not
+  // through Next metadata: Next validates `og:type` against the OpenGraph
+  // vocabulary and rejects those entity types, so a raw `property` tag is the
+  // only way to carry the entity type into the rendered `<head>`.
+  const ogType = data.entitySeo?.openGraph?.type
+  // The navigability feature's real trail is server-rendered as a sanitized
+  // `BreadcrumbList` alongside the entity structured data. It is built from the
+  // loader's own state, so it always matches the rendered breadcrumb.
+  const breadcrumbItems = (data.initialState as Record<string, unknown> | undefined)
+    ?.breadcrumbItems
+  const breadcrumbJsonLd = buildBreadcrumbListJsonLd(
+    Array.isArray(breadcrumbItems)
+      ? (breadcrumbItems as { label?: string; href?: string }[])
+      : undefined,
+  )
+
+  return (
+    <>
+      {ogType ? <meta property="og:type" content={ogType} /> : null}
+      {jsonLd ? (
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(jsonLd) }}
+        />
+      ) : null}
+      {breadcrumbJsonLd ? (
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(breadcrumbJsonLd) }}
+        />
+      ) : null}
+      <StorefrontRenderer
+        spec={data.spec}
+        layoutSpec={data.layoutSpec}
+        initialState={initialState}
+      />
+    </>
+  )
 }

package/assets/templates/app/app/[[...slug]]/renderer.tsx

@@ -2,9 +2,20 @@
 
 // Generated by Thor Commerce storefront (template: assets/templates/app/app/[[...slug]]/renderer.tsx)
 
+import { useRef } from 'react'
 import { PageRenderer } from '@json-render/next'
 import type { PageData } from '@json-render/next'
 
-export function StorefrontRenderer(data: PageData) {
-  return <PageRenderer {...data} />
+export function StorefrontRenderer({ initialState, ...data }: PageData) {
+  // The server recomputes `initialState` on every render, and a Server Action
+  // triggers an RSC refresh — so the prop is a fresh object each time even when
+  // its content is unchanged. `@json-render/react`'s StateProvider resets the
+  // client store whenever the `initialState` reference changes, which would wipe
+  // client-owned state (for example the account order history) after an action.
+  // Keep a STABLE reference while the serialized content is unchanged; a genuine
+  // server-side change (for example the cart) still propagates a new value.
+  const key = JSON.stringify(initialState ?? {})
+  const stable = useRef({ key, value: initialState })
+  if (stable.current.key !== key) stable.current = { key, value: initialState }
+  return <PageRenderer {...data} initialState={stable.current.value} />
 }

package/assets/templates/app/app/globals.css

@@ -28,10 +28,10 @@
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
-  --radius-sm: var(--radius-sm);
-  --radius-md: var(--radius-md);
-  --radius-lg: var(--radius-lg);
-  --radius-xl: var(--radius-xl);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
   --font-sans: var(--font-geist-sans);
 }
 
@@ -59,10 +59,7 @@
   --border: oklch(0.88 0.003 90);
   --input: oklch(0.92 0.003 90);
   --ring: oklch(0.15 0 0);
-  --radius-sm: 0.25rem;
-  --radius-md: 0.375rem;
-  --radius-lg: 0.5rem;
-  --radius-xl: 0.75rem;
+  --radius: 0.5rem;
 }
 
 .dark {

package/assets/templates/app/app/layout.tsx

@@ -4,8 +4,6 @@ import type { Metadata } from 'next'
 import { Geist } from 'next/font/google'
 import { ThemeProvider } from 'next-themes'
 import { StorefrontProvider } from '@thorprovider/runtime/host-glue/providers'
-import { themeVarsToCss, themeTokensToVars } from '@thorprovider/runtime/render-core/theme'
-import { DEFAULT_THEME_TOKENS } from '@thorprovider/runtime/contracts'
 import { registry } from '@/lib/__STOREFRONT__/registry'
 import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
 import './globals.css'
@@ -15,8 +13,6 @@ const geist = Geist({
   subsets: ['latin'],
 })
 
-const themeCss = themeVarsToCss(themeTokensToVars(DEFAULT_THEME_TOKENS))
-
 // The canonical public origin is optional: when THOR_SITE_URL is unset no base
 // URL is invented. `metadataBase` is left undefined in that case.
 const siteUrl = getSiteUrl()
@@ -39,7 +35,7 @@ export default function RootLayout({
     <html lang="es" className={geist.variable} suppressHydrationWarning>
       <body className="font-sans antialiased">
         <ThemeProvider attribute="class" defaultTheme="__STOREFRONT_MODE__" enableSystem>
-          <StorefrontProvider themeCss={themeCss} registry={registry}>
+          <StorefrontProvider registry={registry}>
             {children}
           </StorefrontProvider>
         </ThemeProvider>

package/assets/templates/app/app/robots.ts

@@ -1,13 +1,19 @@
 // Generated by Thor Commerce storefront (template: assets/templates/app/app/robots.ts)
-// Always served. Points at the sitemap only when THOR_SITE_URL is configured.
+// Always served. Allows public pages, disallows private surfaces, and points at
+// the sitemap only when THOR_SITE_URL is configured.
 
 import type { MetadataRoute } from 'next'
-import { robotsSitemapUrl } from '@/lib/__STOREFRONT__/spec/seo'
+import { __STOREFRONT_CAMEL__Spec } from '@/lib/__STOREFRONT__/spec'
+import { robotsDisallowPaths, robotsSitemapUrl } from '@/lib/__STOREFRONT__/spec/seo'
 import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
 
 export default function robots(): MetadataRoute.Robots {
   return {
-    rules: { userAgent: '*', allow: '/' },
+    rules: {
+      userAgent: '*',
+      allow: '/',
+      disallow: robotsDisallowPaths(__STOREFRONT_CAMEL__Spec.routes ?? {}),
+    },
     sitemap: robotsSitemapUrl(getSiteUrl()),
   }
 }

package/assets/templates/app/app/sitemap.ts

@@ -1,12 +1,71 @@
 // Generated by Thor Commerce storefront (template: assets/templates/app/app/sitemap.ts)
-// Lists the storefront's fixed routes. Absolute URLs are emitted only when
-// THOR_SITE_URL is configured; otherwise the sitemap is empty (no invented URL).
+// Lists the fixed public routes plus every public catalog entity, enumerated
+// across adapter pagination with a bound and a cycle guard. Absolute URLs are
+// emitted only when THOR_SITE_URL is configured; otherwise the sitemap is empty
+// (no invented URL). An enumeration failure fails loudly (no partial sitemap).
 
 import type { MetadataRoute } from 'next'
+import { getCatalog, getCatalogResults } from '@thorprovider/runtime/commerce'
 import { __STOREFRONT_CAMEL__Spec } from '@/lib/__STOREFRONT__/spec'
-import { sitemapUrls } from '@/lib/__STOREFRONT__/spec/seo'
+import {
+  buildSitemapEntries,
+  enumeratePublicEntities,
+  SitemapEnumerationError,
+  type PublicEntityPage,
+} from '@/lib/__STOREFRONT__/spec/seo'
 import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
 
-export default function sitemap(): MetadataRoute.Sitemap {
-  return sitemapUrls(__STOREFRONT_CAMEL__Spec.routes ?? {}, getSiteUrl()).map((url) => ({ url }))
+const ENTITY_PAGE_SIZE = 100
+const MAX_PAGES = 100
+
+async function productPage(cursor: string | undefined): Promise<PublicEntityPage> {
+  const page = cursor ? Number(cursor) : 1
+  const outcome = await getCatalogResults({
+    page,
+    pageSize: ENTITY_PAGE_SIZE,
+    sort: 'name',
+  })
+  if (!outcome.ok) {
+    throw new SitemapEnumerationError({
+      kind: 'enumeration',
+      message: outcome.error.message,
+    })
+  }
+  const items = outcome.results.products.map((product) => ({
+    id: product.id,
+    path: `/products/${product.handle}`,
+  }))
+  const total = outcome.results.total
+  const hasMore =
+    typeof total === 'number' ? page * ENTITY_PAGE_SIZE < total : items.length >= ENTITY_PAGE_SIZE
+  return hasMore ? { items, nextCursor: String(page + 1) } : { items }
+}
+
+async function categoryPage(): Promise<PublicEntityPage> {
+  const catalog = await getCatalog()
+  return {
+    items: catalog.categoriesRaw.map((category) => ({
+      id: category.id,
+      path: `/categories/${category.handle}`,
+    })),
+  }
+}
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const siteUrl = getSiteUrl()
+  if (!siteUrl) return []
+
+  const routes = __STOREFRONT_CAMEL__Spec.routes ?? {}
+  const [products, categories] = await Promise.all([
+    enumeratePublicEntities(productPage, { maxPages: MAX_PAGES }),
+    enumeratePublicEntities(categoryPage, { maxPages: MAX_PAGES }),
+  ])
+  if (!products.ok) throw new SitemapEnumerationError(products.failure)
+  if (!categories.ok) throw new SitemapEnumerationError(categories.failure)
+
+  return buildSitemapEntries({
+    routes,
+    siteUrl,
+    entities: [...products.entities, ...categories.entities],
+  })
 }

package/assets/templates/app/lib/__STOREFRONT__/actions.ts

@@ -29,12 +29,15 @@ import {
   loadCheckoutCountries,
   loadCustomer,
   loadOrders,
+  loadOrdersPage,
   loadPaymentMethods,
+  loadProductDetailById,
   loadShippingMethods,
   readCart,
   reconcileOrder,
   registerShopper,
   removeLine,
+  resolveProductCartTarget,
   saveShippingAddress,
   selectShipping,
   setLineQuantity,
@@ -91,6 +94,11 @@ type OrdersActionResult =
   | { ok: true; orders: AccountOrderView[] }
   | { ok: false; error: string }
 
+/** Structured result for a paginated customer order-history load. */
+type OrdersPageActionResult =
+  | { ok: true; orders: AccountOrderView[]; count: number; limit: number; offset: number }
+  | { ok: false; error: string }
+
 /** Basic email shape check; a boundary guard, not a full RFC validation. */
 const EMAIL_PATTERN = /\S+@\S+\.\S+/
 
@@ -152,6 +160,34 @@ export async function addToCartAction(input: {
   }
 }
 
+/**
+ * Add a product's FIRST purchasable variant by backend product id — the
+ * product-card shortcut. The variant is resolved server-side from the backend
+ * detail (card data carries no variant ids); a product with no purchasable
+ * variant returns a truthful error and adds nothing. The product detail remains
+ * the explicit-selection surface (change storefront-card-add-to-cart).
+ */
+export async function addToCartByProductAction(input: {
+  productId: string
+  quantity?: number
+}): Promise<CartActionResult> {
+  try {
+    const productId = typeof input?.productId === 'string' ? input.productId : ''
+    if (productId === '') return { ok: false, error: 'Producto no válido.' }
+    const quantity =
+      Number.isFinite(input?.quantity) && (input.quantity as number) > 0
+        ? Math.floor(input.quantity as number)
+        : 1
+    const detail = await loadProductDetailById(productId)
+    const target = resolveProductCartTarget(detail)
+    if (!target.ok) return { ok: false, error: target.error }
+    const { cartId, context } = await ensureActiveCartId()
+    return { ok: true, cart: await addVariant(cartId, target.variantId, quantity, context) }
+  } catch (error) {
+    return { ok: false, error: toError(error, 'No se pudo agregar el producto.') }
+  }
+}
+
 /** Set a backend cart line to an ABSOLUTE quantity by its line-item id. */
 export async function setLineQuantityAction(input: {
   lineId: string
@@ -540,3 +576,37 @@ export async function loadOrdersAction(): Promise<OrdersActionResult> {
     return { ok: false, error: toError(error, 'No se pudieron cargar tus pedidos.') }
   }
 }
+
+/**
+ * Load ONE bounded page of the authenticated customer's channel-scoped order
+ * history through the additive paginated contract, returning the backend's real
+ * `count`. A missing token resolves to an empty page with `count: 0` without
+ * contacting the backend. This action touches ONLY the auth cookie — never the
+ * guest session cookie or the cart — and no token is logged or returned.
+ */
+export async function loadOrdersPageAction(input?: {
+  page?: number
+  pageSize?: number
+}): Promise<OrdersPageActionResult> {
+  const context = getStoreContext()
+  const token = await readAuthToken(context)
+  const page = Number.isInteger(input?.page) && (input?.page as number) > 0 ? (input?.page as number) : 1
+  const pageSize =
+    Number.isInteger(input?.pageSize) && (input?.pageSize as number) > 0
+      ? (input?.pageSize as number)
+      : 10
+  if (!token) return { ok: true, orders: [], count: 0, limit: pageSize, offset: (page - 1) * pageSize }
+  try {
+    const result = await loadOrdersPage(token, { page, pageSize }, context)
+    return {
+      ok: true,
+      orders: result.orders,
+      count: result.count,
+      limit: result.limit,
+      offset: result.offset,
+    }
+  } catch (error) {
+    logServerError('loadOrdersPageAction', error)
+    return { ok: false, error: toError(error, 'No se pudieron cargar tus pedidos.') }
+  }
+}

package/assets/templates/app/lib/__STOREFRONT__/catalog.ts

@@ -7,11 +7,13 @@ import { defineCatalog } from '@json-render/core'
 import { schema } from '@json-render/react/schema'
 import { z } from 'zod'
 import {
+  backToTopPropsSchema,
   bannerPropsSchema,
-  cartDrawerPropsSchema,
   footerPropsSchema,
+  mobileBottomNavPropsSchema,
   navbarPropsSchema,
   productCardPropsSchema,
+  skipToContentPropsSchema,
   storefrontNavbarPropsSchema,
 } from './schema'
 import { views } from './views'
@@ -43,10 +45,6 @@ const baseComponents = {
     props: storefrontNavbarPropsSchema,
     description: 'Store navigation bar with category menu and cart.',
   },
-  CartDrawer: {
-    props: cartDrawerPropsSchema,
-    description: 'Slide-over shopping cart.',
-  },
   Banner: {
     props: bannerPropsSchema,
     description: 'Announcement banner above the header.',
@@ -59,6 +57,18 @@ const baseComponents = {
     props: footerPropsSchema,
     description: 'Site footer.',
   },
+  SkipToContent: {
+    props: skipToContentPropsSchema,
+    description: 'Keyboard bypass link to the main content landmark.',
+  },
+  BackToTop: {
+    props: backToTopPropsSchema,
+    description: 'Scroll-to-top control revealed past a threshold.',
+  },
+  MobileBottomNav: {
+    props: mobileBottomNavPropsSchema,
+    description: 'Mobile-only bottom navigation for primary destinations.',
+  },
 }
 
 const viewComponents = Object.assign({}, ...views.map((view) => view.catalog))

package/assets/templates/app/lib/__STOREFRONT__/commerce.ts

@@ -39,14 +39,17 @@ import {
   getCheckoutCountries,
   getCurrentCustomer,
   getCustomerOrders,
+  getCustomerOrdersPage,
   getEligibleShippingMethods,
   getPaymentMethodsByRegion,
+  getProductDetailById,
   getProductDetailByHandle,
   loginCustomer,
   logoutCustomer,
   reconcileCart,
   registerCustomer,
   removeCartLines,
+  selectFirstPurchasableVariant,
   selectShippingMethod,
   toAbsoluteLineUpdate,
   updateCartLines,
@@ -263,6 +266,38 @@ export async function loadProductDetail(handle: string): Promise<CatalogDetailRe
   return { detail, source }
 }
 
+/** Directed product-detail lookup by backend id, priced in the store context region. */
+export async function loadProductDetailById(
+  productId: string,
+): Promise<CatalogProductDetail | undefined> {
+  const context = getStoreContext()
+  assertBackendConfigured()
+  return getProductDetailById(productId, context)
+}
+
+/** The resolved add-to-cart target for a product-card shortcut. */
+export type ProductCartTarget =
+  | { ok: true; variantId: string }
+  | { ok: false; error: string }
+
+/**
+ * Resolve the product-card add-to-cart target: the product's FIRST purchasable
+ * variant (available for sale AND with a resolvable price), identified by its
+ * backend variant id. This is the explicit card exception to the product-detail
+ * rule that never falls back to a first variant (change
+ * storefront-card-add-to-cart). A product with no purchasable variant — or an
+ * unknown product — returns a truthful error and adds nothing.
+ */
+export function resolveProductCartTarget(
+  detail: CatalogProductDetail | undefined,
+): ProductCartTarget {
+  const variant = detail ? selectFirstPurchasableVariant(detail) : undefined
+  if (!variant) {
+    return { ok: false, error: 'Este producto no tiene variantes disponibles.' }
+  }
+  return { ok: true, variantId: variant.id }
+}
+
 /** The context-scoped backend cart projected for the UI, or undefined when absent. */
 export async function readCart(
   cartId: string,
@@ -605,4 +640,40 @@ export async function loadOrders(
   return orders.map(toAccountOrderView)
 }
 
+/**
+ * The additive paginated history window projected for the account view.
+ * `count` is the backend's real total for the authenticated customer on the
+ * store's channel; it is never the page length.
+ */
+export interface AccountOrdersPage {
+  orders: AccountOrderView[]
+  count: number
+  limit: number
+  offset: number
+}
+
+/**
+ * Load one bounded page of the authenticated customer's channel-scoped history
+ * through the additive paginated contract. A missing token yields an empty page
+ * with `count: 0` (the runtime builds no provider); it never fabricates an order.
+ */
+export async function loadOrdersPage(
+  token: string | null,
+  options: { page?: number; pageSize?: number } = {},
+  context: StoreContext = getStoreContext(),
+): Promise<AccountOrdersPage> {
+  const page = await getCustomerOrdersPage({
+    token,
+    page: options.page,
+    pageSize: options.pageSize,
+    salesChannelId: context.salesChannelId,
+  })
+  return {
+    orders: page.orders.map(toAccountOrderView),
+    count: page.count,
+    limit: page.limit,
+    offset: page.offset,
+  }
+}
+
 export type { Money }

package/assets/templates/app/lib/__STOREFRONT__/composition.ts

@@ -0,0 +1,26 @@
+// Generated by Thor Commerce storefront (composition composer: features).
+// Do not edit by hand — the manifest is the source of truth; run `storefront sync`.
+// Installed manifest catalog features, in stable order, with their persisted
+// config. This is the generation seam the catalog URL boundary consumes to
+// reject parameters owned by a feature that is not installed, and the seam the
+// single controlled CategoryFilter2 reads to select its control
+// visibility/config from the installed manifest only.
+
+import type { CatalogFeatureName } from '@thorprovider/runtime/contracts'
+
+export const mountedFeatures: readonly CatalogFeatureName[] = []
+
+// Every installed feature name, unfiltered by the catalog URL boundary. The
+// general presence seam cross-cutting features read to gate their own
+// contributions (e.g. the navigability feature's shell chrome).
+export const mountedFeatureNames: readonly string[] = []
+
+export const mountedFeatureConfigs: Partial<Record<string, Record<string, unknown>>> = {
+}
+
+// Typed route/action availability derived from the installed manifest. The
+// generated host uses these to hide links to routes that are not installed,
+// so a removed view never leaves an active dead-end navigation target.
+export const cartViewAvailable = false
+
+export const checkoutAvailable = false

package/assets/templates/app/lib/__STOREFRONT__/handlers.core.ts

@@ -15,6 +15,7 @@ import { useActions, useStateStore } from '@json-render/react'
 import { useNextApp } from '@json-render/next'
 import {
   addToCartAction,
+  addToCartByProductAction,
   applyQuantityDeltaAction,
   ensureCartAction,
   loadCartStateAction,
@@ -22,6 +23,8 @@ import {
   setLineQuantityAction,
 } from './actions'
 import type { CartStatePatch } from './commerce'
+import { cartViewAvailable } from './composition'
+import { recordConfirmedTransition } from './section-observation'
 
 /** A product-like object the views leave in `/lastClicked` (card/hero shortcut). */
 interface ClickedProduct {
@@ -81,10 +84,30 @@ export function useCoreHandlers() {
             if (result.ok) {
               applyCart(result.cart)
               set('/cartOpen', true)
+              // A confirmed cart transition — observed only after the mutation
+              // succeeded, and only when a section origin exists (default: off).
+              recordConfirmedTransition('cart_add_confirmed')
             } else fail(result.error)
           })
           .catch(onError('addToCart'))
       },
+      addClickedToCart: () => {
+        // Product-card shortcut: add the clicked product's first purchasable
+        // variant. The backend variant id is resolved server-side from the
+        // product id (the card carries no variant ids).
+        const product = get('/lastClicked') as ClickedProduct | null
+        if (!product?.id) return
+        begin()
+        void addToCartByProductAction({ productId: String(product.id) })
+          .then((result) => {
+            if (result.ok) {
+              applyCart(result.cart)
+              set('/cartOpen', true)
+              recordConfirmedTransition('cart_add_confirmed')
+            } else fail(result.error)
+          })
+          .catch(onError('addClickedToCart'))
+      },
       ensureCart: () => {
         begin()
         void ensureCartAction()
@@ -141,17 +164,26 @@ export function useCoreHandlers() {
       openProduct: () => {
         const product = get('/lastClicked') as ClickedProduct | null
         if (!product?.id) return
-        navigate(`/productos/${product.id}`)
+        navigate(`/products/${product.id}`)
       },
       openCategory: () => {
-        const handle = get('/lastCategory') as string | null
-        navigate(handle ? `/categorias/${handle}` : '/categorias')
+        // `/lastCategory` already holds the category href the card was given
+        // (`StoreCategory.href`, e.g. `/categories/jackets`); navigate it as-is
+        // so the route scope is not prefixed twice.
+        const href = get('/lastCategory') as string | null
+        navigate(href ?? '/categories')
       },
       goHome: () => {
         set('/cartOpen', false)
         navigate('/')
       },
-      goToCart: () => set('/cartOpen', true),
+      goToCart: () => {
+        // Visibility only: dismiss the lateral and go to the review route. The
+        // navigation is guarded by the installed composition so a store without
+        // the cart view never routes to a missing page.
+        set('/cartOpen', false)
+        if (cartViewAvailable) navigate('/cart')
+      },
       submitReview: () => {},
       toggleReviewLike: () => {},
     }