@thorprovider/storefront 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.4.0
+
+- **Renamed package**: `@thorprovider/create-storefront` → `@thorprovider/storefront`;
+  the `bin` is now `storefront` (`npx @thorprovider/storefront create`).
+- **Single scaffold command**: `storefront create <dir>` scaffolds the storefront and
+  installs the OpenCode command suite in the same run. The standalone `install` action
+  is gone; `storefront update` refreshes, prunes removed files, and migrates the
+  version record.
+- **Interactive wizard**: on a TTY, `create` prompts for name, site name, backend URL,
+  and preset (Maia preselected). Brand color is decided via `/sf-theme`, not the wizard.
+  Without a TTY, every required input must be passed as a flag or the command fails
+  fast before writing anything.
+- **Command surface**: `<dir>` is positional; `--dir` is removed; `--name` is a flag or
+  wizard prompt. Commands are `storefront create|update|doctor <dir>`.
+- **Removed `/sf-init`**: the `sf-init` command and `sf-scaffold` skill are gone.
+  Scaffolding is fully deterministic inside the binary.
+- **Decoupled templates**: the scaffold templates moved from the `sf-scaffold` skill
+  into `assets/templates/` at the package root.
+- **Version record**: `.opencode/storefront.json` (replacing `.create-storefront.json`);
+  `update` migrates existing installs.
+
+## 0.3.0
+
+- **Embedded assets**: each skill now carries the templates, recipes, and scripts it
+  uses inside its own directory (`assets/`, `scripts/`, `references/`) and addresses
+  them by relative path. No path marker is needed to locate the package.
+- **Versioned install command**: `bin` exposes `create-storefront` with `install`,
+  `update`, and `doctor`. Installation is an explicit command; there is no
+  `postinstall`. The installer records `{ version, installedAt }` in
+  `.opencode/.create-storefront.json` (replacing the `.create-storefront-root` marker).
+- **Single source, generated copies**: `recipes/` stays the single source at the
+  package root; `scripts/sync-assets.mjs` generates the per-skill copies and a
+  `--check` mode fails on drift. The check runs at build/pretest and before the
+  installer copies anything into a target project.
+- **Positive source-of-truth rule**: the skills state that the workflow uses the assets
+  inside the skill and that an undecided choice is resolved by asking the user.
+- **Named interfaces**: each skill declares the target-project inputs it reads and the
+  outputs it produces.
+- **General self-containment check**: the test fails on any absolute machine path in a
+  shipped artifact, independent of any name.
+
+## 0.2.0
+
+- Per-view templates: every recipe view (`home`, `product`, `category`, `checkout`,
+  `user-panel`) ships as a self-contained module under `templates/views/<view>/`.
+- Generated storefronts now compose views through a barrel (`lib/<name>/views/index.ts`);
+  shared files (`catalog.ts`, `registry.tsx`, `runtime.ts`, `spec/index.ts`) derive from
+  the registered views and are never edited per view.
+- `/sf-add-view` copies a view module and registers one barrel entry, substituting only
+  the imported block identifier for the resolved variant. No hand-authored wiring.
+- Optional sections (testimonials, FAQ, statistics, logo cloud, pricing) ship as
+  fragments under `views/sections/` and are validated against `recipes/sections.json`.
+- `sf-scaffold` copies `templates/app/` plus `templates/views/home/` and registers
+  `home` in the barrel.
+- Templates and skills no longer reference any repository-local application.
+
+## 0.1.3
+
+- Previous release.

package/README.md

@@ -0,0 +1,333 @@
+---
+title: "@thorprovider/storefront"
+purpose: "Deterministic storefront scaffolder and installable command suite for Thor Commerce"
+lastReviewed: "2026-10-01"
+---
+
+# @thorprovider/storefront
+
+Deterministic storefront scaffolder and installable command suite for Thor Commerce.
+
+`npx @thorprovider/storefront create <dir>` scaffolds a complete, buildable storefront
+and installs the `/sf-*` OpenCode command suite into `<dir>/.opencode/` in the same
+run. It ships static project templates, a recipe registry, and vendored skills, and
+installs them into any project's `.opencode/` directory. Nothing else from the Thor
+Commerce monorepo is required at generation time.
+
+This README is organised in two parts:
+
+- **Getting started** — for consumers who install the published package and want a
+  running storefront. Start here.
+- **Contributing** — for maintainers working on the package itself. See
+  [Development](#development).
+
+---
+
+## Getting started
+
+You need no checkout of the Thor Commerce monorepo. The package is on npm and the
+storefront it generates resolves its own dependencies from the registry.
+
+### Prerequisites
+
+| Requirement | Supported |
+| --- | --- |
+| Node.js | >= 18.17.0 |
+| Package manager | Yarn with the `node-modules` linker (for generated projects) |
+| OpenCode | a version that supports project skills in `.opencode/skills/` |
+| OS | macOS, Linux, Windows (via WSL) |
+| Network | access to the npm registry (the generated project installs its dependencies from it) |
+
+Generated projects use Yarn with the `node-modules` linker, not Plug'n'Play (PnP).
+Yarn 4 defaults to PnP, which Next.js 16's Turbopack cannot resolve from, so the
+scaffold writes a `.yarnrc.yml` setting `nodeLinker: node-modules` before installing
+dependencies. PnP is not used. You do not need to configure this yourself.
+
+### Install
+
+Run the scaffolder directly from npm — no global install required. `npx` and
+`yarn dlx` are equivalent:
+
+```bash
+npx @thorprovider/storefront create my-shop \
+  --site-name "My Shop" \
+  --backend-url http://localhost:9000 \
+  --preset maia
+```
+
+```bash
+yarn dlx @thorprovider/storefront create my-shop --preset maia
+```
+
+The first positional argument is the target directory: it is created if missing, and
+it is where `.opencode/`, the Next.js app, and `lib/<name>/` live. Run the command
+from the parent directory you want the project created in.
+
+In a terminal, `create` runs an interactive wizard for any input you omit (name,
+site name, backend URL, preset — Maia is preselected). Without a terminal, every
+required input must be passed as a flag; the command fails fast and writes nothing
+rather than guessing. Brand color is never asked by the wizard — apply it later with
+`/sf-theme`, or pass `--brand` on the command line.
+
+Once the package is installed as a dependency, the shorter binary form is available:
+
+```bash
+storefront create my-shop --preset maia    # scaffold + install the suite
+storefront update                          # refresh an existing install
+storefront doctor                          # report the recorded version and status
+```
+
+### Create a storefront
+
+`create` scaffolds a complete, buildable storefront in one reproducible pass — no
+LLM re-derivation, no hand-editing. The target directory (positional `<dir>`) is the
+project root that will hold `.opencode/`:
+
+```bash
+storefront create my-shop \
+  --name my-shop \
+  --site-name "My Shop" \
+  --backend-url http://localhost:9000 \
+  --preset maia \
+  [--brand orange]
+```
+
+| Flag | Meaning | Default |
+| --- | --- | --- |
+| `<dir>` (positional) | target project directory (created if missing) | required |
+| `--name <name>` | kebab-case storefront name = `lib/<name>/` = `__STOREFRONT__` | prompted in the wizard |
+| `--site-name <name>` | human site name (`__SITE_NAME__`) | `<name>` |
+| `--backend-url <url>` | Medusa backend URL | `http://localhost:9000` |
+| `--preset <preset>` | visual preset: `maia`, `nova`, `vega`, `luma`, `lyra`, `mira` | prompted in the wizard (Maia preselected) |
+| `--brand <color>` | named brand color overriding preset primary/nav/ring tokens (never prompted) | none |
+| `--force`, `-f` | overwrite files that already exist | off |
+
+The pipeline runs: preconditions → Next.js base → shadcn base with the preset →
+`.yarnrc.yml` (`nodeLinker: node-modules`) → dependency install → template copy +
+placeholder substitution → default-page removal → `.env.local` + theme → suite
+install into `.opencode/`.
+
+Same inputs produce a byte-identical tree (verified by recursive `diff -r`). Running
+`create` twice with different inputs is the only reason the output differs.
+
+The suite install copies `commands/` and the shipped skills under `skills/` (own
+skills and vendored skills, flat) into `<dir>/.opencode/`. It verifies its own
+generated copies against their source before copying, records the installed version
+in `.opencode/storefront.json`, and is idempotent: use `--force` to overwrite files
+that already exist.
+
+### Run the storefront
+
+When `create` finishes it prints the next steps:
+
+```bash
+cd my-shop
+yarn dev
+```
+
+The storefront renders its home view — hero, benefits, and category sections — using
+only `@thorprovider/blocks` for UI and `@thorprovider/adapters` for data. Then grow
+it incrementally from OpenCode:
+
+```
+/sf-add-view product      # add a view from its recipe
+/sf-view home add a testimonials section   # modify an existing view
+/sf-theme                 # colors, typography, identity
+```
+
+### Backend configuration
+
+Generated projects expect a Medusa backend. `create` writes a `.env.local` with the
+backend URL you passed and blank placeholders for the rest:
+
+```bash
+MEDUSA_BACKEND_URL=http://localhost:9000
+MEDUSA_REGION_ID=
+MEDUSA_PUBLISHABLE_KEY=
+```
+
+Set `MEDUSA_REGION_ID` and `MEDUSA_PUBLISHABLE_KEY` as needed, then restart
+`yarn dev`. The storefront shows no catalog data until these are set (see
+[Backend not configured](#backend-not-configured)). During local development you can
+use the `mock` adapter data source instead of a live backend.
+
+### Troubleshooting / Known Issues
+
+Each entry below follows the same shape: **cause** → **symptom** → **remedy**.
+
+#### Ancestor `.opencode/`
+
+- **Cause**: the project is created under a directory tree in which an ancestor
+  directory already contains a `.opencode/`.
+- **Symptom**: OpenCode resolves the wrong command set — `/sf-add-view`, `/sf-view`,
+  and `/sf-theme` run commands from the ancestor's `.opencode/` instead of the ones
+  this package installed, so you see stale or unrelated behaviour.
+- **Remedy**: scaffold in a clean root with no ancestor `.opencode/` (for example a
+  fresh directory outside the monorepo), or remove/relocate the ancestor `.opencode/`
+  before opening the project.
+
+#### Non-empty target directory
+
+- **Cause**: `create` runs against a directory whose `lib/<name>/` already exists (a
+  previous scaffold with the same name), or whose root is already a Next.js project.
+- **Symptom**: the run stops at the preconditions stage with
+  `lib/<name>/ already exists — refusing to overwrite`.
+- **Remedy**: choose a different `--name`, or remove the existing `lib/<name>/`
+  directory. To extend an existing storefront instead of creating one, use
+  `/sf-add-view`. `create-next-app` also refuses to initialize a directory that is
+  already a Next.js project unless it can reuse it; run `create` in an empty directory.
+
+#### Missing or invalid `--preset`
+
+- **Cause**: `--preset` was omitted (in a non-interactive run) or the value is not one
+  of the recognized presets.
+- **Symptom**: the run stops at the input-validation stage with
+  `--preset must be one of: maia, nova, vega, luma, lyra, mira`.
+- **Remedy**: pass `--preset` with one of `maia`, `nova`, `vega`, `luma`, `lyra`,
+  `mira`. In a terminal the wizard preselects `maia`, so the preset is only required
+  on the command line for non-interactive runs.
+
+#### Yarn Plug'n'Play / linker
+
+- **Cause**: a generated project installed with Yarn's default PnP linker.
+- **Symptom**: Next.js 16's Turbopack fails to resolve the Next.js package
+  (`Could not find the Next.js package`).
+- **Remedy**: this is why `create` writes `.yarnrc.yml` with
+  `nodeLinker: node-modules` before installing. If you set up the project manually,
+  add that file and re-run `yarn install` so a real `node_modules/` is materialized.
+  Do not use PnP.
+
+#### Backend not configured
+
+- **Cause**: `MEDUSA_REGION_ID` / `MEDUSA_PUBLISHABLE_KEY` (or a reachable backend) are
+  not set in `.env.local`.
+- **Symptom**: the storefront renders its layout but shows no catalog data.
+- **Remedy**: fill in the variables in [Backend configuration](#backend-configuration)
+  and restart `yarn dev`, or use the `mock` adapter data source during local
+  development.
+
+---
+
+## What gets installed
+
+```
+<project>/.opencode/
+  storefront.json            # { version, installedAt } — what generation is installed
+  commands/
+    sf-add-view.md
+    sf-view.md
+    sf-theme.md
+  skills/
+    sf-view-gen/             # assets/templates/views/, assets/recipes/, scripts/validate.mjs
+    sf-theme-gen/            # assets/
+    nextjs-shadcn/
+    shadcn-theming/
+    shadcn-component-discovery/
+    storefront-best-practices/
+    building-storefronts/
+```
+
+Each skill carries the templates, recipes, and scripts it uses inside its own
+directory. Skills address them by relative path, so nothing needs the package to be
+located on disk at generation time.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/sf-add-view <view>` | Add one view incrementally (`product`, `category`, `checkout`, `user-panel`) |
+| `/sf-view <view> <change>` | Modify an existing view's spec, preserving structure |
+| `/sf-theme` | Customize OKLCH color tokens (light/dark), typography, and identity metadata |
+
+Scaffolding itself is `npx @thorprovider/storefront create <dir>` — there is no
+`/sf-init` command; the wizard lives in the CLI and is deterministic.
+
+## Design guarantees
+
+- **Self-contained**: each skill carries the assets it uses and addresses them by
+  relative path; nothing depends on the Thor Commerce monorepo, on machine-global
+  skills, or on locating the package at generation time.
+- **Consistent by construction**: shared recipes are authored once and generated into
+  each skill; a check fails when a copy drifts, both at build time and before the
+  installer copies anything.
+- **Stack-constrained**: UI comes only from `@thorprovider/blocks`; data only from
+  `@thorprovider/adapters` and `@thorprovider/runtime/commerce`.
+- **Varied output**: a recipe registry lets the skills pick block variants and optional
+  sections (testimonials, FAQ, statistics, logo cloud, pricing) from your description,
+  so sites are not identical.
+
+## Generated project structure
+
+Each view is a self-contained module. Shared files compose whatever the view barrel
+exports and never name a view, so adding one is a copy plus a single registration.
+
+```
+lib/<name>/
+  catalog.ts, registry.tsx, runtime.ts, handlers.ts, state.ts   # shell; compose the barrel
+  mappers.ts                                                   # CardProduct -> FeaturedProduct / CategoryCard
+  spec/index.ts, spec/page-root.ts, spec/types.ts               # routes built from the barrel
+  views/
+    index.ts            # barrel: export const views: ViewModule[] = [home, ...]
+    types.ts            # ViewModule contract
+    sections/*.tsx      # optional-section fragments (testimonials, faq, ...)
+    home/index.tsx      # one folder per view
+    product/index.tsx
+    category/index.tsx
+    checkout/index.tsx
+    user-panel/index.tsx
+```
+
+A view folder ships the package's default block variants; `/sf-add-view` picks the
+intent/variant from your description (validated by the skill's `scripts/validate.mjs`)
+and substitutes only the imported block identifier. The scaffold templates live at
+the package root, and the view templates travel inside the skills that use them:
+
+```
+assets/templates/app/                                 # shell (copied by `create`)
+assets/templates/views/home/                          # home (copied by `create`)
+skills/sf-view-gen/assets/templates/views/<view>/     # the other views (copied by /sf-add-view)
+```
+
+## Development
+
+Testing the package during development does not require `npm pack`. The local
+binary reads the working tree directly:
+
+```bash
+yarn sync-assets && yarn check-assets              # recipes ↔ generated copies are consistent
+yarn test                                          # contract + packaging test suite
+node bin/storefront.js create <tmp> --name my-shop --preset maia   # scaffold into a throwaway project
+node bin/storefront.js doctor <tmp>                # report the recorded version and status
+node scripts/render-templates.mjs <tmp> my-shop    # re-render templates only (no install; fast loop)
+```
+
+`scripts/render-templates.mjs` is the same renderer the `create` action uses for
+stage 6. It copies the templates and substitutes placeholders without touching
+dependencies, so iterating on a template against a persistent project (e.g.
+`projects/<name>/`) costs seconds and no network.
+
+`npm pack` exists to verify a different thing: **what actually ships to npm** —
+the `files` list, and that every asset travels inside its skill. It is only
+meaningful at these moments:
+
+| Moment | Action |
+| --- | --- |
+| Day-to-day development | Nothing — use the local binary above |
+| Changing `files`, moving assets, adding or removing directories | `npm pack --dry-run` to list what would ship |
+| CI, before publishing | `yarn check-assets` + `npm pack --dry-run` as a guard |
+| Publishing a release | `npm pack` / `yarn npm publish` — the real tarball |
+
+A generated `.tgz` goes stale the moment the tree changes, so it is not a
+development tool. Keep it out of the working tree.
+
+## Maintenance
+
+See `VENDOR.md` for how vendored skills are refreshed and how to bump
+templates.
+
+The [Troubleshooting / Known Issues](#troubleshooting--known-issues) entries are part
+of the contract with consumers: revisit them whenever the CLI surface changes
+(flags, actions, validation) or the scaffold's preconditions change (target-directory
+rules, linker, backend variables), and update the corresponding entry in
+`packages/storefront/README.md`. The packaging test suite asserts these
+sections and that every failure-mode entry carries a remedy.

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

@@ -0,0 +1,17 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/app/[[...slug]]/page.tsx)
+
+import { notFound } from 'next/navigation'
+import { __STOREFRONT_CAMEL__App } from '@/lib/__STOREFRONT__/runtime'
+import { StorefrontRenderer } from './renderer'
+
+export const { generateMetadata, generateStaticParams } = __STOREFRONT_CAMEL__App
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>
+}) {
+  const data = await __STOREFRONT_CAMEL__App.getPageData({ params })
+  if (!data) return notFound()
+  return <StorefrontRenderer {...data} />
+}

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

@@ -0,0 +1,10 @@
+'use client'
+
+// Generated by Thor Commerce storefront (template: assets/templates/app/app/[[...slug]]/renderer.tsx)
+
+import { PageRenderer } from '@json-render/next'
+import type { PageData } from '@json-render/next'
+
+export function StorefrontRenderer(data: PageData) {
+  return <PageRenderer {...data} />
+}

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

@@ -0,0 +1,101 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@thorprovider/blocks/styles.css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --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);
+  --font-sans: var(--font-geist-sans);
+}
+
+:root {
+  --background: oklch(0.98 0.002 90);
+  --foreground: oklch(0.15 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.15 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.15 0 0);
+  --primary: oklch(0.15 0 0);
+  --primary-foreground: oklch(0.98 0.002 90);
+  --secondary: oklch(0.96 0.003 90);
+  --secondary-foreground: oklch(0.15 0 0);
+  --muted: oklch(0.94 0.003 90);
+  --muted-foreground: oklch(0.45 0 0);
+  --accent: oklch(0.58 0.16 25);
+  --accent-foreground: oklch(1 0 0);
+  --destructive: oklch(0.55 0.2 25);
+  --destructive-foreground: oklch(0.98 0.002 90);
+  --success: oklch(0.47 0.14 155);
+  --success-foreground: oklch(0.98 0.01 155);
+  --warning: oklch(0.55 0.18 75);
+  --warning-foreground: oklch(0.98 0.02 75);
+  --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;
+}
+
+.dark {
+  --background: oklch(0.15 0 0);
+  --foreground: oklch(0.98 0.002 90);
+  --card: oklch(0.2 0 0);
+  --card-foreground: oklch(0.98 0.002 90);
+  --popover: oklch(0.2 0 0);
+  --popover-foreground: oklch(0.98 0.002 90);
+  --primary: oklch(0.98 0.002 90);
+  --primary-foreground: oklch(0.15 0 0);
+  --secondary: oklch(0.25 0.003 90);
+  --secondary-foreground: oklch(0.98 0.002 90);
+  --muted: oklch(0.25 0.003 90);
+  --muted-foreground: oklch(0.65 0 0);
+  --accent: oklch(0.65 0.15 25);
+  --accent-foreground: oklch(0.15 0 0);
+  --destructive: oklch(0.65 0.2 25);
+  --destructive-foreground: oklch(0.15 0 0);
+  --success: oklch(0.6 0.13 155);
+  --success-foreground: oklch(0.1 0.02 155);
+  --warning: oklch(0.7 0.15 75);
+  --warning-foreground: oklch(0.1 0.02 75);
+  --border: oklch(0.3 0.003 90);
+  --input: oklch(0.3 0.003 90);
+  --ring: oklch(0.85 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}

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

@@ -0,0 +1,35 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/app/layout.tsx)
+
+import type { Metadata } from 'next'
+import { Geist } from 'next/font/google'
+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 './globals.css'
+
+const geist = Geist({
+  variable: '--font-geist-sans',
+  subsets: ['latin'],
+})
+
+const themeCss = themeVarsToCss(themeTokensToVars(DEFAULT_THEME_TOKENS))
+
+export const metadata: Metadata = {
+  title: '__SITE_NAME__',
+  description: 'Tienda online de __SITE_NAME__.',
+}
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="es" className={geist.variable}>
+      <body className="font-sans antialiased">
+        <StorefrontProvider themeCss={themeCss} registry={registry}>
+          {children}
+        </StorefrontProvider>
+      </body>
+    </html>
+  )
+}

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

@@ -0,0 +1,88 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/catalog.ts)
+// Base catalog for the app shell plus every registered view's catalog fragment.
+// View element types live with their view module; the shell owns only chrome.
+
+import { defineCatalog } from '@json-render/core'
+import { schema } from '@json-render/react/schema'
+import { z } from 'zod'
+import { views } from './views'
+
+const ctaSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+const navLinkSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+const footerLinkSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+const footerLinkColumnSchema = z.object({
+  title: z.string(),
+  links: z.array(footerLinkSchema),
+})
+
+// Declared locally so the catalog builder's zod version is the only one in play.
+// Cross-major schema assignment (@thorprovider/blocks ships zod v3) breaks the
+// defineCatalog contract, so the block contract is mirrored here instead.
+const productSchema = z.object({
+  id: z.union([z.string(), z.number()]),
+  title: z.string(),
+  price: z.number(),
+  originalPrice: z.number().optional(),
+  image: z.string().optional(),
+  badge: z.string().optional(),
+})
+
+const baseComponents = {
+  Layout: {
+    props: z.object({}),
+    slots: ['default', 'header', 'footer'],
+    description: 'Page layout shell. Pages render inside its default slot.',
+  },
+  Navbar: {
+    props: z.object({
+      navLinks: z.array(navLinkSchema),
+      logoText: z.string(),
+      logoHref: z.string().optional(),
+      currentPath: z.string().optional(),
+      signIn: ctaSchema.optional(),
+      cta: ctaSchema.optional(),
+      cartCount: z.number().optional(),
+    }),
+    description: 'Top navigation bar.',
+  },
+  ProductCard: {
+    props: z.object({
+      products: z.array(productSchema),
+      heading: z.string().optional(),
+      maxItems: z.number().optional(),
+    }),
+    description: 'Grid of product cards.',
+  },
+  Footer: {
+    props: z.object({
+      brandName: z.string(),
+      brandDescription: z.string().optional(),
+      linkColumns: z.array(footerLinkColumnSchema),
+      newsletter: z
+        .object({ placeholder: z.string().optional(), buttonLabel: z.string().optional() })
+        .optional(),
+    }),
+    description: 'Site footer.',
+  },
+}
+
+const viewComponents = Object.assign({}, ...views.map((view) => view.catalog))
+
+export const catalog = defineCatalog(schema, {
+  components: { ...baseComponents, ...viewComponents },
+  actions: {},
+})
+
+export type StorefrontCatalog = typeof catalog