@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/skills/sf-view-gen/assets/templates/views/sections/schema.products.ts

@@ -0,0 +1,39 @@
+// Optional section fragment: products (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the resolved Products section props, shared by the server catalog
+// (products.tsx) and the client registry (products.client.tsx). The product list
+// reuses the canonical presentation contract owned by @thorprovider/blocks so the
+// section renders exactly what the host mapped from the catalog result.
+
+import { z } from 'zod'
+import { productPresentationSchema } from '@thorprovider/blocks'
+
+// The per-instance resolution status the host loader computes for a data-bound
+// section. `ready`/`empty` carry resolved products; the remaining states carry no
+// products and render an actionable, truthful message instead.
+export const productsStatusSchema = z.enum([
+  'unconfigured',
+  'ready',
+  'empty',
+  'invalid-query',
+  'unsupported-query',
+  'unmounted-capability',
+  'data-error',
+])
+
+export const productsPropsSchema = z.object({
+  sectionId: z.string().min(1).optional(),
+  sectionType: z.string().min(1).optional(),
+  variant: z.string().optional(),
+  // Defensive defaults: a missing resolved state (e.g. the view loader could not
+  // run) degrades to a truthful error instead of crashing the render.
+  status: productsStatusSchema.default('data-error'),
+  products: z.array(productPresentationSchema).default([]),
+  heading: z.string().optional(),
+  description: z.string().optional(),
+  objective: z.string().optional(),
+  ctaLabel: z.string().optional(),
+  ctaHref: z.string().optional(),
+})
+
+export type ProductsProps = z.infer<typeof productsPropsSchema>
+export type ProductsStatus = z.infer<typeof productsStatusSchema>

package/skills/sf-view-gen/assets/templates/views/sections/schema.statistics.ts

@@ -0,0 +1,25 @@
+// Optional section fragment: statistics (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the StatisticItem/Statistic1Props block contracts, shared by
+// the server catalog (statistics.tsx) and the client registry
+// (statistics.client.tsx). The block expects `icon` as a Lucide component;
+// specs ship the icon NAME, so it is a string here and the client registry
+// resolves it via resolveIcon.
+
+import { z } from 'zod'
+
+export const statisticItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  value: z.string(),
+  description: z.string(),
+  progress: z.number(),
+  progressLabel: z.string(),
+  icon: z.string().optional(),
+})
+
+export const statisticsPropsSchema = z.object({
+  title: z.string().optional(),
+  badge: z.string().optional(),
+  description: z.string().optional(),
+  items: z.array(statisticItemSchema),
+})

package/skills/sf-view-gen/assets/templates/views/sections/schema.testimonials.ts

@@ -0,0 +1,23 @@
+// Optional section fragment: testimonials (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the Testimonial1Item/Testimonial1Props block contracts, shared
+// by the server catalog (testimonials.tsx) and the client registry
+// (testimonials.client.tsx).
+
+import { z } from 'zod'
+
+export const testimonialItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  role: z.string(),
+  avatar: z.string(),
+  content: z.string(),
+  rating: z.number(),
+})
+
+export const testimonialsPropsSchema = z.object({
+  title: z.string().optional(),
+  prevLabel: z.string().optional(),
+  nextLabel: z.string().optional(),
+  slideAriaLabel: z.string().optional(),
+  items: z.array(testimonialItemSchema),
+})

package/skills/sf-view-gen/assets/templates/views/sections/statistics.client.tsx

@@ -4,15 +4,23 @@
 // The matching server-side catalog entry lives in statistics.tsx.
 
 import { Statistic1 as StatisticBlock } from '@thorprovider/blocks'
+import { statisticsPropsSchema } from './schema.statistics'
+import { resolveIcon } from '../../icon-map'
 import type { ViewRegistry } from '../types'
 
 export const registry: ViewRegistry = {
-  Statistics: ({ props }) => (
-    <StatisticBlock
-      badge={props.badge as string}
-      title={(props.title as string) ?? 'Números que nos respaldan'}
-      description={props.description as string}
-      items={props.items as never}
-    />
-  ),
+  Statistics: ({ props }) => {
+    const parsed = statisticsPropsSchema.parse(props)
+    return (
+      <StatisticBlock
+        badge={parsed.badge}
+        title={parsed.title ?? 'Números que nos respaldan'}
+        description={parsed.description}
+        items={parsed.items.map((item) => ({
+          ...item,
+          icon: resolveIcon(item.icon),
+        }))}
+      />
+    )
+  },
 }

package/skills/sf-view-gen/assets/templates/views/sections/statistics.tsx

@@ -2,18 +2,13 @@
 // Server-side part: element type + zod catalog entry. The component mappings
 // live in statistics.client.tsx ('use client').
 
-import { z } from 'zod'
+import { statisticsPropsSchema } from './schema.statistics'
 
 export const statisticsSection = {
   elementType: 'Statistics',
   catalog: {
     Statistics: {
-      props: z.object({
-        title: z.string().optional(),
-        badge: z.string().optional(),
-        description: z.string().optional(),
-        items: z.array(z.record(z.string(), z.unknown())),
-      }),
+      props: statisticsPropsSchema,
       description: 'Key metrics or trust statistics.',
     },
   },

package/skills/sf-view-gen/assets/templates/views/sections/testimonials.client.tsx

@@ -4,16 +4,20 @@
 // The matching server-side catalog entry lives in testimonials.tsx.
 
 import { Testimonial1 as TestimonialBlock } from '@thorprovider/blocks'
+import { testimonialsPropsSchema } from './schema.testimonials'
 import type { ViewRegistry } from '../types'
 
 export const registry: ViewRegistry = {
-  Testimonials: ({ props }) => (
-    <TestimonialBlock
-      title={(props.title as string) ?? 'Lo que dicen nuestros clientes'}
-      items={props.items as never}
-      prevLabel={(props.prevLabel as string) ?? 'Anterior'}
-      nextLabel={(props.nextLabel as string) ?? 'Siguiente'}
-      slideAriaLabel={(props.slideAriaLabel as string) ?? 'Testimonio'}
-    />
-  ),
+  Testimonials: ({ props }) => {
+    const parsed = testimonialsPropsSchema.parse(props)
+    return (
+      <TestimonialBlock
+        title={parsed.title ?? 'Lo que dicen nuestros clientes'}
+        items={parsed.items}
+        prevLabel={parsed.prevLabel ?? 'Anterior'}
+        nextLabel={parsed.nextLabel ?? 'Siguiente'}
+        slideAriaLabel={parsed.slideAriaLabel ?? 'Testimonio'}
+      />
+    )
+  },
 }

package/skills/sf-view-gen/assets/templates/views/sections/testimonials.tsx

@@ -2,16 +2,13 @@
 // Server-side part: element type + zod catalog entry. The component mappings
 // live in testimonials.client.tsx ('use client').
 
-import { z } from 'zod'
+import { testimonialsPropsSchema } from './schema.testimonials'
 
 export const testimonialsSection = {
   elementType: 'Testimonials',
   catalog: {
     Testimonials: {
-      props: z.object({
-        title: z.string().optional(),
-        items: z.array(z.record(z.string(), z.unknown())),
-      }),
+      props: testimonialsPropsSchema,
       description: 'Customer testimonials or social proof.',
     },
   },

package/skills/{json-render-core/SKILL.md → sf-view-gen/references/json-render-core.md}

@@ -1,38 +1,15 @@
----
-name: core
-description: Core package for defining schemas, catalogs, and AI prompt generation for json-render. Use when working with @json-render/core, defining schemas, creating catalogs, or building JSON specs for UI/video generation.
----
+# @json-render/core reference
 
-# @json-render/core
-
-Core package for schema definition, catalog creation, and spec streaming.
+Reference material for the `sf-view-gen` skill: schema definition, catalog
+creation, and spec shape for `@json-render/core`.
 
 ## Key Concepts
 
 - **Schema**: Defines the structure of specs and catalogs (use `defineSchema`)
 - **Catalog**: Maps component/action names to their definitions (use `defineCatalog`)
-- **Spec**: JSON output from AI that conforms to the schema
+- **Spec**: JSON output that conforms to the schema
 - **SpecStream**: JSONL streaming format for progressive spec building
 
-## Experimental Decision-Model Composition
-
-For decision-model composition, import `experimental_composeSpec` and `experimental_createEvaluator` from `@json-render/core`. These APIs are unreleased; use a source build until published, then pin exact versions. Experimental exports and `Experimental_` types can change in any release.
-
-- Run the Gateway evaluator server-side with `{ model: "typesafe-ai/jev", apiKey: process.env.AI_GATEWAY_API_KEY! }`. A plain model identifier is required; Jev is the current example; do not import a provider constructor.
-- Call `experimental_composeSpec({ catalog, candidates, prompt, evaluate, initialState, signal })`. It is an async generator; stream `step.spec` snapshots to your existing renderer and inspect `complete.stopReason` (`finish`, `limit`, `unavailable`). Errors and cancellation throw; retain the last snapshot as partial UI.
-- New trees default to `strategy: "batch"`: one evaluation selects root/membership, then a second arranges the selected elements when needed. The first snapshot contains selected content in catalog order under the root's default/first slot. Resource variants share one exclusive question; repeated counts include the root. Root selection takes precedence over conflicting speculative membership for that recipe/resource. Equal sibling positions retain catalog order. Combined layouts are validated before publication; cycles or excessive depth throw. `maxElements` caps batched creation (default 32). Limit-truncated selections or a missing required layout call return `limit`. Use `strategy: "sequential"` for legacy `next`/`parent` adapters or sequential creation. Edits stay sequential.
-- Batched trace steps use `choice: "select" | "layout"` and an `answers` record. Count each trace as one evaluation, including its tokens and latency once. Custom evaluators must answer every offered question; names/choices are opaque and include `root`/`select_*`, then `parent_*`/`order_*` for batches.
-- For follow-up edits, pass the selected version as `initialSpec`. It is cloned and validated; the evaluator may add, replace, remove non-root subtrees, or move/reorder them. Unchanged IDs, bindings, and state are preserved. Optional `elementDescriptions` shares identifying descriptions without exposing raw props/state. `initialState` overrides the seed state. Seeds must be valid trees within the catalog, expression subset, and depth limit. Matching recipes consume usage/resource limits; removals/replacements release them. Replacements/moves use two evaluations (select target, then recipe/destination), each counted against the budget. Treat operation and position keys as opaque.
-- Supply atomic candidates with `{ id, description, element: { type, props, on?, visible? }, root?, maxUses?, resource? }`. Catalog alone is insufficient: the app must supply values and binding recipes. Jev chooses elements and parent slots, never free-form text or code. It never executes actions.
-- Candidates are configured component instances, not page templates. Build them from current app records/operations or bind props to `initialState`; offer explicit alternatives for chart types, field configurations, and layout variants. The model chooses grouping and order within those options. Name required sections in prompts; structural validity does not imply semantic completeness.
-- V1 supports flat Spec catalogs, named slots, literals, `$state`, `$bindState`, and state visibility. No prebuilt children, repeat/watch, computed/template/conditional props, or custom directives. Success/error callbacks must reference allowed actions. Events must be declared in the component catalog.
-- Props and action params are validated against initial state without applying schema transforms/defaults. Supply valid initial values and validate/authorize action calls at runtime. Built-ins without parameter schemas get name validation only.
-- `root` defaults true, `maxUses` defaults one, shared `resource` values make alternatives mutually exclusive. Defaults: 32 evaluations (terminal calls included; no extra finish call for batches), depth eight, 10-second Gateway timeout per call. Supply an overall abort signal.
-- Candidate descriptions, prompt, instructions, topology, and explicit `context` are sent to the evaluator. Initial state and raw props/binding values are not sent automatically.
-- For custom providers implement `Experimental_CompositionEvaluator`: accept `{ state, questions, signal }`, return `{ answers: { [question]: { choice, confidence? } }, usage?: { inputTokens? } }`. Only return offered criteria keys.
-
-See `packages/core/README.md` and `/docs/jev` for app integration and source-build instructions. The web playground is an example consumer, not a dependency of the API.
-
 ## Defining a Schema
 
 ```typescript

package/skills/{json-render-next/SKILL.md → sf-view-gen/references/json-render-next.md}

@@ -1,17 +1,14 @@
----
-name: next
-description: Next.js renderer for json-render that turns JSON specs into full Next.js applications with routes, layouts, SSR, and metadata. Use when working with @json-render/next, building Next.js apps from JSON specs, or creating AI-generated multi-page applications.
----
+# @json-render/next reference
 
-# @json-render/next
+Reference material for the `sf-view-gen` skill: the Next.js rendering shape that
+converts the json-render spec into routes, layouts, SSR, and metadata.
 
 Next.js renderer that converts JSON specs into full Next.js applications with routes, pages, layouts, metadata, and SSR support.
 
 ## Quick Start
 
-```bash
-npm install @json-render/core @json-render/react @json-render/next
-```
+`@json-render/core`, `@json-render/react`, and `@json-render/next` are already
+dependencies of the generated storefront; no install step is needed.
 
 ### 1. Define Your Spec
 

package/skills/{json-render-react/SKILL.md → sf-view-gen/references/json-render-react.md}

@@ -1,9 +1,7 @@
----
-name: react
-description: React renderer for json-render that turns JSON specs into React components. Use when working with @json-render/react, building React UIs from JSON, creating component catalogs, or rendering AI-generated specs.
----
+# @json-render/react reference
 
-# @json-render/react
+Reference material for the `sf-view-gen` skill: registry mapping, providers,
+bindings, and action wiring for the React renderer.
 
 React renderer that converts JSON specs into React component trees.
 

package/skills/{json-render-shadcn/SKILL.md → sf-view-gen/references/json-render-shadcn.md}

@@ -1,9 +1,7 @@
----
-name: shadcn
-description: Pre-built shadcn/ui components for json-render. Use when working with @json-render/shadcn, adding standard UI components to a catalog, or building web UIs with Radix UI + Tailwind CSS components.
----
+# @json-render/shadcn reference
 
-# @json-render/shadcn
+Reference material for the `sf-view-gen` skill: the standard shadcn/ui component
+definitions and implementations available to a catalog.
 
 Pre-built shadcn/ui component definitions and implementations for json-render. Provides 36 components built on Radix UI + Tailwind CSS.
 

package/skills/sf-view-gen/references/views.md

@@ -1,15 +1,22 @@
-# View templates
+# View modules reference
 
-Each folder here is a self-contained view module. `npx @thorprovider/storefront create`
-copies `home/` at init; `/sf-add-view` copies one folder per added view.
+Reference material for the `sf-view-gen` skill. Each view is a self-contained
+module the CLI generates into `lib/<name>/views/<view>/`. The CLI — not the
+agent — writes the barrel and every derived file; `npx @thorprovider/storefront
+view add <view>` generates one view's derived files and reconciles the barrel.
+
+The available views are whatever `npx @thorprovider/storefront views --json`
+reports; this file names none of them as the authoritative set.
 
 ## Module shape
 
-Each view is the **two-file split** (RSC):
+Each view is the **three-file split** (RSC):
 
 - `views/<view>/index.tsx` — pure Server Component module: name, elements,
   zod catalog, route, loader. Never imports values from `@json-render/react`
-  or `@thorprovider/blocks`.
+  or `@thorprovider/blocks`. **Derived — the CLI writes it; never hand-edit it.**
+- `views/<view>/schema.ts` — pure Zod schemas mirroring the block contracts
+  the view renders (props only). No React, no `'use client'`, no Next imports.
 - `views/<view>/registry.tsx` — `'use client'`: exports
   `registry: ViewRegistry`, the component mappings
   (`Record<string, (ctx: BaseComponentProps<Record<string, unknown>>) => ReactNode>`).
@@ -39,31 +46,49 @@ view never edits them.
 
 ## Registering a view
 
-Add **one import and one entry** to `lib/<name>/views/index.ts`:
-
-```ts
-import { home } from './home'
-import { product } from './product'
-
-export const views: ViewModule[] = [home, product]
-```
-
-## Variant substitution convention
-
-Every slot imports its block variant under a **stable alias** and ships the
-recipe's default variant:
-
-```ts
-import { ProductOverview1 as ProductOverviewBlock } from '@thorprovider/blocks'
-```
-
-To apply a different (recipe-allowed) variant, replace **only the imported
-identifier** — never the alias, never the props:
-
-```ts
-import { ProductOverview5 as ProductOverviewBlock } from '@thorprovider/blocks'
-```
-
-The alias is the element type's contract; the identifier is the presentation
-choice. Keeping props identical across variants is why the catalog declares the
-stable subset of each element's props.
+The barrel `lib/<name>/views/index.ts` (server) and `lib/<name>/views/registry.ts`
+(client) are **generated from the manifest by the CLI** on every reconcile. Do
+not hand-edit them; add or remove a view with
+`npx @thorprovider/storefront view add|remove <name>`. The CLI emits one import
+and one entry per installed view, so a view removed from the manifest cannot
+reappear through folder scanning.
+
+## Variants
+
+A slot's variant is a presentation choice recorded in the manifest and applied by
+the reconciler. Change it through the CLI — `view add`/`remove` with
+`--variant slot=Name` (a supported variant the registry reports), or a
+`section.add` / `section.reorder` operation for editorial sections. Do not
+hand-edit a derived `index.tsx` or registry to swap an imported identifier; the
+next `sync` would overwrite it and the manifest would disagree with the files.
+
+## Data contracts and icons
+
+Two rules that keep generated views from crashing at render time:
+
+1. **Mappers are applied at loaders, never in registries.** Adapter canon does
+   not match block props 1:1 (e.g. a category may carry `productCount?: number`
+   or no count at all, and some count props are optional). The view's loader maps
+   adapter data through `lib/<name>/mappers.ts` before it reaches state.
+   Registries receive already-mapped, block-shaped props. When a value is unknown
+   (e.g. no category count), **omit** it — never fabricate a `0` default, which
+   would render a false "0 items". A genuine `0` from a richer source is
+   preserved.
+
+2. **Icons cross registries as components, via `icon-map`.** Several blocks type
+   icon props as `LucideIcon` (a component). A string like `'truck'` bound
+   directly renders a literal `<truck>` tag in the DOM. Registries resolve icon
+   names through `lib/<name>/icon-map.ts` (`resolveIcon(name)`, kebab-case →
+   `LucideIcon`, neutral `Circle` fallback). When adding a view that uses a new
+   icon, extend `icon-map.ts` with an entry — never inline a string where a
+   component is expected.
+
+Supporting rules for the same goal:
+
+- View schemas live in `views/<view>/schema.ts` and **mirror the block's Zod
+  contracts locally** — never import schemas from `@thorprovider/blocks` (the
+  scaffold runs Zod v4 while blocks ships v3; cross-major schema assignment
+  breaks `defineCatalog`).
+- Registries **parse props through the view schema** (`schema.parse(props)`)
+  instead of casting bindings (`as never` / `as any` are forbidden in scaffold
+  code). Type errors on `parse` are the contract check.

package/skills/sf-view-gen/scripts/catalog.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Semantic executable catalog: the single contract that states, per view slot
+// and candidate block variant, whether the variant is `executable` or `held`,
+// the block it renders, the canonical data shape it consumes, the events it
+// emits, its controlled/uncontrolled state, its requirements, and an optional
+// prop bridge from the canonical shape to the block props.
+//
+// The published shape lives in `recipes/catalog.schema.json`; this module loads
+// that same artifact and adds only the invariants the supported schema subset
+// cannot express (a held entry must carry a reason; a slot's default must be a
+// declared variant; an unverified capability must name its owning change). It
+// does not classify the initial set, derive `supported`, or wire any
+// generator/introspection — those are owned by later tasks.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validateAgainstSchema, validateSchemaSupported } from '../scripts/schema-validate.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// Layout-agnostic catalog location: at the package root the catalog lives beside
+// this module (`recipes/`); in an installed skill it is distributed under
+// `skills/sf-view-gen/assets/recipes/` and addressed by relative path. Either
+// layout holds the same synced artifact, so there is one catalog source. The
+// `../scripts/schema-validate.mjs` import resolves to the package `scripts/` at
+// the root and to the skill's own `scripts/` once distributed (same directory).
+const catalogDir = existsSync(join(here, 'catalog.json'))
+  ? here
+  : join(here, '..', 'assets', 'recipes')
+
+export const CATALOG_VERSION = 1
+export const CATALOG_SCHEMA_ID = 'https://thorcommerce.dev/storefront/catalog.schema.json'
+
+const catalogSchema = JSON.parse(readFileSync(join(catalogDir, 'catalog.schema.json'), 'utf8'))
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+export function loadCatalogSchema() {
+  return catalogSchema
+}
+
+/**
+ * Load the published semantic catalog document (`recipes/catalog.json`) — the
+ * single source of the executable/held classification. Callers validate it with
+ * `validateCatalog`; classification is data, not logic (E1 task 1.2).
+ */
+export function loadCatalog() {
+  return JSON.parse(readFileSync(join(catalogDir, 'catalog.json'), 'utf8'))
+}
+
+/**
+ * The slot variant entry schema, read from the published catalog schema so the
+ * per-entry contract has exactly one source. Throws loudly if the schema is
+ * reshaped, rather than silently validating against nothing.
+ */
+function variantEntrySchema() {
+  const entry =
+    catalogSchema?.properties?.slots?.additionalProperties?.properties?.variants
+      ?.additionalProperties
+  if (!isPlainObject(entry)) {
+    throw new Error('catalog.schema.json does not declare a slot variant entry schema.')
+  }
+  return entry
+}
+
+/**
+ * Validate one slot variant entry against the published contract.
+ * Returns { ok, errors }.
+ */
+export function validateCatalogEntry(entry) {
+  const errors = validateAgainstSchema(entry, variantEntrySchema(), 'catalog entry')
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * Validate a complete catalog document against the published contract plus the
+ * invariants the schema subset cannot express. Returns { ok, errors }.
+ */
+export function validateCatalog(catalog) {
+  if (!isPlainObject(catalog)) {
+    return { ok: false, errors: ['Catalog must be a JSON object.'] }
+  }
+  const errors = validateSchemaSupported(catalogSchema)
+  errors.push(...validateAgainstSchema(catalog, catalogSchema, 'catalog'))
+
+  const slots = isPlainObject(catalog.slots) ? catalog.slots : {}
+  for (const [slotId, slot] of Object.entries(slots)) {
+    if (!isPlainObject(slot)) continue
+    const variants = isPlainObject(slot.variants) ? slot.variants : {}
+    if (Object.keys(variants).length === 0) {
+      errors.push(`Slot "${slotId}" must declare at least one variant.`)
+    }
+    if (typeof slot.default === 'string' && !hasOwn(variants, slot.default)) {
+      errors.push(`Slot "${slotId}" default "${slot.default}" is not a declared variant.`)
+    }
+    for (const [variantName, entry] of Object.entries(variants)) {
+      if (!isPlainObject(entry)) continue
+      if (entry.status === 'held' && !(typeof entry.reason === 'string' && entry.reason.length > 0)) {
+        errors.push(`Held variant "${slotId}.${variantName}" must declare a non-empty reason.`)
+      }
+    }
+  }
+
+  // An unverified capability is held: it must name the change that owns its
+  // implementation, so a consumer can see that the capability is not available
+  // and who will make it available. This is the honest gate the schema subset
+  // cannot express (E1 task 4.2 / CU-04).
+  const capabilities = isPlainObject(catalog.capabilities) ? catalog.capabilities : {}
+  for (const [capabilityId, capability] of Object.entries(capabilities)) {
+    if (!isPlainObject(capability)) continue
+    if (
+      capability.verification === 'unverified' &&
+      !(typeof capability.owner === 'string' && capability.owner.length > 0)
+    ) {
+      errors.push(
+        `Unverified capability "${capabilityId}" must declare the owning change in "owner".`
+      )
+    }
+  }
+  return { ok: errors.length === 0, errors }
+}