@arroyavecommerce/cms-storefront 0.2.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@arroyavecommerce/cms-storefront",
+  "version": "0.2.0",
+  "description": "Host storefront del CMS de ArroyaveCommerce: contrato defineTemplate y primitivas de render/tema.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./fetchers": "./src/fetchers.ts",
+    "./studio": "./src/studio.ts",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "fetchers": [
+        "./src/fetchers.ts"
+      ],
+      "studio": [
+        "./src/studio.ts"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@arroyavecommerce/cms-core": ">=0.1.0",
+    "@arroyavecommerce/cms-studio": ">=0.1.0",
+    "@puckeditor/core": ">=0.22",
+    "react": ">=19",
+    "react-dom": ">=19",
+    "zod": ">=4.0"
+  },
+  "devDependencies": {
+    "@arroyavecommerce/cms-core": "0.2.0",
+    "@arroyavecommerce/cms-studio": "0.2.0",
+    "@puckeditor/core": "^0.22.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/__fixtures__/template-demo.test.tsx

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest"
+import { cmsPageDataSchema } from "@arroyavecommerce/cms-core"
+import { templateDemo } from "./template-demo"
+
+describe("templateDemo (fixture)", () => {
+  it("declara los dos bloques y un home por defecto válido", () => {
+    expect(Object.keys(templateDemo.blocks)).toEqual(["heroDemo", "avisoDemo"])
+    const parsed = cmsPageDataSchema.safeParse(templateDemo.defaultHomePage)
+    expect(parsed.success).toBe(true)
+  })
+})

package/src/__fixtures__/template-demo.tsx

@@ -0,0 +1,56 @@
+import { z } from "zod"
+import { defineBlocks, type BlockDefinition } from "@arroyavecommerce/cms-core"
+import { defineTemplate, type Template } from "../template"
+
+export type DemoCtx = { destacado: string }
+
+const heroDemo: BlockDefinition<{ titulo: string }, DemoCtx> = {
+  label: "Hero demo",
+  schema: z.object({ titulo: z.string().min(1) }),
+  defaults: { titulo: "Bienvenido" },
+  Component: ({ props, ctx }) => (
+    <section>
+      <h1>{props.titulo}</h1>
+      <p>{ctx.destacado}</p>
+    </section>
+  ),
+}
+
+const avisoDemo: BlockDefinition<{ texto: string }, DemoCtx> = {
+  label: "Aviso demo",
+  schema: z.object({ texto: z.string().min(1) }),
+  defaults: { texto: "Envíos a todo el país" },
+  Component: ({ props }) => <aside>{props.texto}</aside>,
+}
+
+const blocks = defineBlocks<DemoCtx>()({ heroDemo, avisoDemo })
+
+export const templateDemo: Template<DemoCtx> = defineTemplate<DemoCtx>()({
+  meta: { id: "demo", nombre: "Demo", industria: "test" },
+  blocks,
+  puckConfig: { components: {} },
+  theme: {
+    definition: {
+      tokens: {
+        "color-primario": {
+          label: "Primario",
+          tipo: "color",
+          default: "#111111",
+          cssVars: ["--cms-primario"],
+        },
+      },
+      fuentes: {},
+    },
+    defaults: { "color-primario": "#111111" },
+    marca: "Demo",
+  },
+  defaultHomePage: {
+    version: 1,
+    blocks: [
+      { id: "b1", type: "heroDemo", props: blocks.heroDemo.defaults },
+      { id: "b2", type: "avisoDemo", props: blocks.avisoDemo.defaults },
+    ],
+  },
+  reservados: ["store", "checkout"],
+  basePath: "/p",
+})

package/src/fetchers.ts

@@ -0,0 +1,2 @@
+export { createCmsFetchers } from "@arroyavecommerce/cms-core/fetchers"
+export type { CmsFetchersConfig } from "@arroyavecommerce/cms-core/fetchers"

package/src/filter-url.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest"
+import { facetSeleccionados, construirUrlFiltro } from "./filter-url"
+
+describe("facetSeleccionados", () => {
+  it("normaliza un array existente", () => {
+    expect(facetSeleccionados({ talla: ["S", "M"] }, "talla")).toEqual(["S", "M"])
+  })
+  it("devuelve [] si la faceta está ausente", () => {
+    expect(facetSeleccionados({}, "talla")).toEqual([])
+  })
+  it("normaliza un string suelto a array de un elemento", () => {
+    expect(facetSeleccionados({ c: "x" }, "c")).toEqual(["x"])
+  })
+})
+
+describe("construirUrlFiltro", () => {
+  it("agrega el valor cuando la faceta está vacía", () => {
+    const url = construirUrlFiltro({}, { id: "talla", control: "pill" }, "S")
+    expect(url).toContain("talla=S")
+  })
+
+  it("toggle multi (pill): quita el valor si ya estaba seleccionado", () => {
+    const url = construirUrlFiltro({ talla: "S" }, { id: "talla", control: "pill" }, "S")
+    expect(url).not.toContain("talla=S")
+  })
+
+  it("toggle multi (checkbox): agrega el valor conservando el existente", () => {
+    const url = construirUrlFiltro({ talla: "S" }, { id: "talla", control: "checkbox" }, "M")
+    expect(url).toContain("talla=S")
+    expect(url).toContain("talla=M")
+  })
+
+  it("single (dropdown): reemplaza el valor existente", () => {
+    const url = construirUrlFiltro({ orden: "a" }, { id: "orden", control: "dropdown" }, "b")
+    expect(url).toContain("orden=b")
+    expect(url).not.toContain("orden=a")
+  })
+
+  it("range: reemplaza el rango existente", () => {
+    const url = construirUrlFiltro({ precio: "0-100" }, { id: "precio", control: "range" }, "50-200")
+    expect(url).toContain("precio=50-200")
+    expect(url).not.toContain("precio=0-100")
+  })
+
+  it("preserva otras keys del query", () => {
+    const url = construirUrlFiltro({ color: "negro", talla: "S" }, { id: "talla", control: "pill" }, "M")
+    expect(url).toContain("color=negro")
+  })
+
+  it("al togglear el último valor de una faceta, la key desaparece (no queda vacía)", () => {
+    const url = construirUrlFiltro({ talla: "S" }, { id: "talla", control: "pill" }, "S")
+    expect(url).not.toMatch(/talla=(&|$)/)
+    expect(url).not.toContain("talla=")
+  })
+})

package/src/filter-url.ts

@@ -0,0 +1,36 @@
+import type { Facet } from "@arroyavecommerce/cms-core"
+
+export function facetSeleccionados(query: Record<string, string | string[]>, facetId: string): string[] {
+  const v = query[facetId]
+  if (v === undefined) return []
+  return Array.isArray(v) ? v : [v]
+}
+
+export function construirUrlFiltro(
+  query: Record<string, string | string[]>,
+  facet: Pick<Facet, "id" | "control">,
+  valor: string,
+): string {
+  const params = new URLSearchParams()
+  for (const [key, v] of Object.entries(query)) {
+    if (key === facet.id) continue
+    for (const item of Array.isArray(v) ? v : [v]) {
+      params.append(key, item)
+    }
+  }
+
+  const esMulti = facet.control === "pill" || facet.control === "checkbox"
+  if (esMulti) {
+    const actuales = facetSeleccionados(query, facet.id)
+    const nuevos = actuales.includes(valor) ? actuales.filter((x) => x !== valor) : [...actuales, valor]
+    for (const item of nuevos) {
+      params.append(facet.id, item)
+    }
+  } else {
+    // single: dropdown y range/price reemplazan el valor de la faceta
+    params.append(facet.id, valor)
+  }
+
+  const qs = params.toString()
+  return qs ? `?${qs}` : ""
+}

package/src/filters.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest"
+import type { CmsFiltersConfig } from "@arroyavecommerce/cms-core"
+import { resolveFilters } from "./filters"
+
+const config: CmsFiltersConfig = {
+  version: 1,
+  facets: [
+    { id: "rareza", label: "Rareza", control: "pill", source: { type: "tag", tagIds: ["t1", "t2"] }, order: 1 },
+    { id: "cat", label: "Categoría", control: "dropdown", source: { type: "category", parentId: "pcat" }, order: 2 },
+    { id: "precio", label: "Precio", control: "range", source: { type: "price" }, order: 3 },
+    // faceta inválida (price con pill): debe omitirse
+    { id: "malo", label: "Malo", control: "pill", source: { type: "price" }, order: 4 },
+  ],
+}
+
+describe("resolveFilters", () => {
+  it("mapea tag/category a params de Store API (OR dentro de la faceta)", () => {
+    const r = resolveFilters(config, { rareza: ["t1", "t2"], cat: "c9" })
+    expect(r.params.tag_id).toEqual(["t1", "t2"])
+    expect(r.params.category_id).toEqual(["c9"])
+  })
+  it("descarta valores de tag que no están en el bucket", () => {
+    const r = resolveFilters(config, { rareza: ["t1", "ajeno"] })
+    expect(r.params.tag_id).toEqual(["t1"])
+  })
+  it("parsea el rango de precio y omite la faceta inválida", () => {
+    const r = resolveFilters(config, { precio: "10-50", malo: "x" })
+    expect(r.price).toEqual({ min: 10, max: 50 })
+    // 'malo' (price+pill) se omite: no rompe ni agrega params
+    expect(r.params.tag_id).toBeUndefined()
+  })
+  it("ignora keys sin faceta y no incluye arrays vacíos", () => {
+    const r = resolveFilters(config, { inexistente: "z" })
+    expect(r.params).toEqual({})
+    expect(r.price).toBeUndefined()
+  })
+  it("mapea source.type collection a collection_id", () => {
+    const cfg: CmsFiltersConfig = {
+      version: 1,
+      facets: [
+        { id: "col", label: "Colección", control: "pill", source: { type: "collection" }, order: 1 },
+      ],
+    }
+    const r = resolveFilters(cfg, { col: ["cx", "cy"] })
+    expect(r.params.collection_id).toEqual(["cx", "cy"])
+  })
+  it("parsea rangos de precio parciales (solo min o solo max)", () => {
+    const cfg: CmsFiltersConfig = {
+      version: 1,
+      facets: [
+        { id: "precio", label: "Precio", control: "range", source: { type: "price" }, order: 1 },
+      ],
+    }
+    const r1 = resolveFilters(cfg, { precio: "-50" })
+    expect(r1.price).toEqual({ max: 50 })
+    const r2 = resolveFilters(cfg, { precio: "10-" })
+    expect(r2.price).toEqual({ min: 10 })
+  })
+  it("fusiona múltiples facetas tag del mismo source.type y deduplica", () => {
+    const cfg: CmsFiltersConfig = {
+      version: 1,
+      facets: [
+        { id: "a", label: "Tags A", control: "pill", source: { type: "tag", tagIds: ["t1", "t2"] }, order: 1 },
+        { id: "b", label: "Tags B", control: "pill", source: { type: "tag", tagIds: ["t2", "t3"] }, order: 2 },
+      ],
+    }
+    const r = resolveFilters(cfg, { a: ["t1", "t2"], b: ["t2", "t3"] })
+    expect(r.params.tag_id).toHaveLength(3)
+    expect(r.params.tag_id).toEqual(expect.arrayContaining(["t1", "t2", "t3"]))
+  })
+})

package/src/filters.ts

@@ -0,0 +1,70 @@
+import { facetControlEsValido, type CmsFiltersConfig } from "@arroyavecommerce/cms-core"
+
+export type ResolvedFilters = {
+  params: {
+    category_id?: string[]
+    collection_id?: string[]
+    tag_id?: string[]
+  }
+  price?: { min?: number; max?: number }
+}
+
+function comoArray(v: string | string[] | undefined): string[] {
+  if (v === undefined) return []
+  return Array.isArray(v) ? v : [v]
+}
+
+function unicos(xs: string[]): string[] {
+  return [...new Set(xs)]
+}
+
+function parsearPrecio(valor: string): { min?: number; max?: number } | null {
+  const m = /^(\d*)-(\d*)$/.exec(valor.trim())
+  if (!m) return null
+  const out: { min?: number; max?: number } = {}
+  if (m[1] !== "") out.min = Number(m[1])
+  if (m[2] !== "") out.max = Number(m[2])
+  return "min" in out || "max" in out ? out : null
+}
+
+/**
+ * Cruza el config publicado con los parámetros de URL y produce los params de
+ * la Store API de Medusa + el rango de precio (aparte, porque la Store API no
+ * filtra por precio). Tolerante: facetas que violan la matriz control×fuente
+ * se omiten; valores de tag fuera del bucket se descartan; keys sin faceta se
+ * ignoran.
+ */
+export function resolveFilters(
+  config: CmsFiltersConfig,
+  query: Record<string, string | string[]>
+): ResolvedFilters {
+  const params: ResolvedFilters["params"] = {}
+  let price: ResolvedFilters["price"] | undefined
+
+  const push = (key: "category_id" | "collection_id" | "tag_id", vals: string[]) => {
+    if (!vals.length) return
+    params[key] = unicos([...(params[key] ?? []), ...vals])
+  }
+
+  for (const facet of config.facets) {
+    if (!facetControlEsValido(facet)) continue
+    const seleccion = comoArray(query[facet.id])
+    if (facet.source.type === "price") {
+      const val = seleccion[0]
+      if (val) {
+        const r = parsearPrecio(val)
+        if (r) price = { ...price, ...r }
+      }
+      continue
+    }
+    if (!seleccion.length) continue
+    if (facet.source.type === "category") push("category_id", seleccion)
+    else if (facet.source.type === "collection") push("collection_id", seleccion)
+    else if (facet.source.type === "tag") {
+      const permitidos = new Set(facet.source.tagIds)
+      push("tag_id", seleccion.filter((v) => permitidos.has(v)))
+    }
+  }
+
+  return price ? { params, price } : { params }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { defineTemplate } from "./template"
+export type { Template, TemplateTheme, CatalogRegistry } from "./template"
+export { renderTemplatePage, templateThemeCss } from "./render"
+export { assertTemplateDefaults } from "./validate"
+export { resolveFilters } from "./filters"
+export type { ResolvedFilters } from "./filters"
+export { resolvePageConfig } from "./pageconfig"
+export type { PageConfigSetting } from "@arroyavecommerce/cms-core"
+export { facetSeleccionados, construirUrlFiltro } from "./filter-url"

package/src/pageconfig.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "vitest"
+import { resolvePageConfig } from "./pageconfig"
+
+const cfg = { version: 1 as const, selections: { "plp.filtros": "sidebar" } }
+
+describe("resolvePageConfig", () => {
+  it("devuelve la selección si existe", () => {
+    expect(resolvePageConfig(cfg, "plp.filtros", "pills")).toBe("sidebar")
+  })
+  it("devuelve el fallback si falta o config es null", () => {
+    expect(resolvePageConfig(cfg, "pdp.galeria", "grid")).toBe("grid")
+    expect(resolvePageConfig(null, "plp.filtros", "pills")).toBe("pills")
+  })
+})

package/src/pageconfig.ts

@@ -0,0 +1,10 @@
+import type { CmsPageConfig } from "@arroyavecommerce/cms-core"
+
+export function resolvePageConfig(
+  config: CmsPageConfig | null,
+  key: string,
+  fallback: string
+): string {
+  const v = config?.selections?.[key]
+  return typeof v === "string" && v.length > 0 ? v : fallback
+}

package/src/render.test.tsx

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest"
+import { renderToStaticMarkup } from "react-dom/server"
+import { templateDemo } from "./__fixtures__/template-demo"
+import { renderTemplatePage } from "./render"
+
+describe("renderTemplatePage", () => {
+  it("renderiza los bloques del home con el ctx dado", () => {
+    const html = renderToStaticMarkup(
+      renderTemplatePage({
+        template: templateDemo,
+        data: templateDemo.defaultHomePage,
+        ctx: { destacado: "Nuevo drop" },
+      })
+    )
+    expect(html).toContain("Bienvenido")
+    expect(html).toContain("Nuevo drop")
+    expect(html).toContain("Envíos a todo el país")
+  })
+
+  it("omite bloques de tipo desconocido sin romper", () => {
+    const html = renderToStaticMarkup(
+      renderTemplatePage({
+        template: templateDemo,
+        data: { version: 1, blocks: [{ id: "x", type: "inexistente", props: {} }] },
+        ctx: { destacado: "" },
+      })
+    )
+    expect(html).not.toContain("inexistente")
+  })
+})

package/src/render.tsx

@@ -0,0 +1,31 @@
+import { CmsRender, type CmsPageData } from "@arroyavecommerce/cms-core"
+import { themeToCss } from "@arroyavecommerce/cms-core/theme"
+import type { Template } from "./template"
+
+/**
+ * Render genérico de una página CMS con los bloques del template activo.
+ * Tolerante por herencia de `CmsRender`: bloque desconocido o props
+ * inválidas se omiten con warning; la página nunca rompe.
+ */
+export function renderTemplatePage<Ctx>({
+  template,
+  data,
+  ctx,
+}: {
+  template: Template<Ctx>
+  data: CmsPageData
+  ctx: Ctx
+}) {
+  return <CmsRender data={data} blocks={template.blocks} ctx={ctx} />
+}
+
+/**
+ * Tokens publicados → declaraciones CSS para :root, usando la declaración de
+ * tema del template. Silencia warnings (delega en la tolerancia de themeToCss).
+ */
+export function templateThemeCss<Ctx>(
+  template: Template<Ctx>,
+  tokens: Record<string, string>
+): string {
+  return themeToCss(tokens, template.theme.definition, () => {})
+}

package/src/smoke.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest"
+import * as host from "./index"
+
+describe("cms-storefront paquete", () => {
+  it("exporta un barrel importable", () => {
+    expect(typeof host).toBe("object")
+  })
+})

package/src/studio.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { createCmsStudio } from "./studio"
+import { templateDemo } from "./__fixtures__/template-demo"
+
+// Las factories del studio importan estos módulos de Next a nivel de módulo.
+vi.mock("next/headers", () => ({ cookies: vi.fn() }))
+vi.mock("next/navigation", () => ({
+  redirect: vi.fn(() => {
+    throw new Error("NEXT_REDIRECT")
+  }),
+}))
+vi.mock("next/cache", () => ({ revalidateTag: vi.fn() }))
+
+const env = {
+  backendUrl: "http://back",
+  publishableKey: "pk_test",
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe("createCmsStudio", () => {
+  it("expone los cinco grupos de actions con sus funciones", () => {
+    const studio = createCmsStudio(templateDemo, env)
+    expect(typeof studio.auth.loginAction).toBe("function")
+    expect(typeof studio.auth.getStudioToken).toBe("function")
+    expect(typeof studio.auth.getStudioUser).toBe("function")
+    expect(typeof studio.cms.listPagesAction).toBe("function")
+    expect(typeof studio.cms.createHomePageAction).toBe("function")
+    expect(typeof studio.theme.getThemeDraftAction).toBe("function")
+    expect(typeof studio.zones.createZoneAction).toBe("function")
+    expect(typeof studio.pages.createPageAction).toBe("function")
+  })
+
+  it("cablea env.backendUrl en las actions (verificado vía verifyAdminToken)", async () => {
+    const fetchFn = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ user: { id: "u1", email: "a@b.c" } }),
+    })
+    vi.stubGlobal("fetch", fetchFn)
+    const studio = createCmsStudio(templateDemo, env)
+    const user = await studio.auth.verifyAdminToken("tok")
+    expect(user).toEqual({ id: "u1", email: "a@b.c" })
+    expect(fetchFn).toHaveBeenCalledWith(
+      "http://back/admin/users/me",
+      expect.objectContaining({ headers: { authorization: "Bearer tok" } })
+    )
+  })
+})

package/src/studio.ts

@@ -0,0 +1,71 @@
+import {
+  makeAuthActions,
+  makeCmsActions,
+  makeThemeActions,
+  makeZoneActions,
+  makePageManagerActions,
+} from "@arroyavecommerce/cms-studio/actions"
+import type { Template } from "./template"
+
+/** Valores de entorno/infra de la instancia (no del template). */
+export type StudioEnv = {
+  backendUrl: string
+  publishableKey: string
+  cookieName?: string
+  studioPath?: string
+}
+
+/**
+ * Instancia todas las server-action factories del studio desde un Template y
+ * el entorno, con un único `getStudioToken` compartido. Reemplaza el cuerpo
+ * repetido de los archivos de wiring de la tienda.
+ *
+ * SEGURIDAD: este módulo NO lleva "use server". Devuelve
+ * `auth.getStudioToken`/`auth.getStudioUser` (helpers server-only); la tienda
+ * debe extraerlos SOLO en un módulo `server-only` (p. ej. su session.ts) y
+ * NUNCA re-exportarlos desde un módulo `"use server"`.
+ *
+ * Uso típico en la tienda (session.ts, server-only):
+ *   const studio = createCmsStudio(miTemplate, { backendUrl, publishableKey })
+ *   export const getStudioToken = studio.auth.getStudioToken
+ * y en cada shim "use server":
+ *   export const { listPagesAction, saveDraftAction } = studio.cms
+ */
+export function createCmsStudio<Ctx>(template: Template<Ctx>, env: StudioEnv) {
+  const auth = makeAuthActions({
+    backendUrl: env.backendUrl,
+    cookieName: env.cookieName,
+    studioPath: env.studioPath,
+  })
+  const getStudioToken = auth.getStudioToken
+
+  const cms = makeCmsActions({
+    backendUrl: env.backendUrl,
+    getStudioToken,
+    defaultHomePage: template.defaultHomePage,
+  })
+
+  const theme = makeThemeActions({
+    backendUrl: env.backendUrl,
+    getStudioToken,
+    theme: {
+      defaults: template.theme.defaults,
+      tokens: template.theme.definition.tokens,
+      fuentes: template.theme.definition.fuentes,
+    },
+  })
+
+  const zones = makeZoneActions({
+    backendUrl: env.backendUrl,
+    publishableKey: env.publishableKey,
+    getStudioToken,
+  })
+
+  const pages = makePageManagerActions({
+    backendUrl: env.backendUrl,
+    getStudioToken,
+    reservados: template.reservados,
+  })
+
+  return { auth, cms, theme, zones, pages }
+}

package/src/template.test.tsx

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest"
+import { z } from "zod"
+import { defineBlocks, type BlockDefinition } from "@arroyavecommerce/cms-core"
+import { defineTemplate, type Template } from "./template"
+
+type Ctx = { saludo: string }
+
+const holaBlock: BlockDefinition<{ texto: string }, Ctx> = {
+  label: "Hola",
+  schema: z.object({ texto: z.string().min(1) }),
+  defaults: { texto: "Hola" },
+  Component: ({ props }) => <p>{props.texto}</p>,
+}
+
+describe("defineTemplate", () => {
+  it("devuelve el mismo objeto (identidad) y preserva su forma", () => {
+    const blocks = defineBlocks<Ctx>()({ hola: holaBlock })
+    const input = {
+      meta: { id: "demo", nombre: "Demo", industria: "test" },
+      blocks,
+      puckConfig: { components: {} },
+      theme: { definition: { tokens: {}, fuentes: {} }, defaults: {} },
+      defaultHomePage: { version: 1, blocks: [] },
+      reservados: ["store"],
+      basePath: "/p",
+    } satisfies Template<Ctx>
+    const template = defineTemplate<Ctx>()(input)
+    // identidad: devuelve exactamente el mismo objeto (por referencia)
+    expect(template).toBe(input)
+    expect(template.meta.id).toBe("demo")
+    expect(template.blocks.hola.label).toBe("Hola")
+    // el tipo se preserva: acceso tipado a una clave concreta del registro
+    const _t: Template<Ctx> = template
+    expect(_t.reservados).toEqual(["store"])
+  })
+})

package/src/template.ts

@@ -0,0 +1,56 @@
+import type { ComponentType } from "react"
+import type { Config } from "@puckeditor/core"
+import type {
+  BlockRegistry,
+  ChromeRegistry,
+  CmsPageConfig,
+  CmsPageData,
+  PageConfigSetting,
+} from "@arroyavecommerce/cms-core"
+import type { ThemeDefinition } from "@arroyavecommerce/cms-core/theme"
+
+/** Contrato de tema de un template: declaración + defaults + texto de muestra. */
+export type TemplateTheme = {
+  definition: ThemeDefinition
+  defaults: Record<string, string>
+  marca?: string
+}
+
+/**
+ * Contrato del catálogo (PLP/PDP) de un template: los componentes que
+ * renderizan listado/detalle (ya resolviendo su propia config internamente)
+ * más el descriptor de settings de página (`pageConfigSettings`) que el
+ * editor de config de página usa para construir su UI.
+ */
+export type CatalogRegistry<Ctx> = {
+  plp: ComponentType<{ ctx: Ctx; pageConfig: CmsPageConfig | null }>
+  pdp: ComponentType<{ ctx: Ctx; pageConfig: CmsPageConfig | null }>
+  pageConfigSettings: { plp: PageConfigSetting[]; pdp: PageConfigSetting[] }
+}
+
+/**
+ * Un template-paquete auto-contenido. Agrupa todo lo que hoy cada tienda
+ * cablea a mano, para que el host lo monte con solo registrarlo.
+ * Ctx es el contexto de datos de industria (lo compone el template desde
+ * las primitivas del host — ver sub-proyecto 1b).
+ */
+export type Template<Ctx> = {
+  meta: { id: string; nombre: string; industria: string }
+  blocks: BlockRegistry<Ctx>
+  puckConfig: Config
+  theme: TemplateTheme
+  chrome?: ChromeRegistry<Ctx>
+  defaultHomePage: CmsPageData
+  reservados: string[]
+  basePath: string
+  catalogo?: CatalogRegistry<Ctx>
+}
+
+/**
+ * Helper de identidad *curried*: fija Ctx y deja que TypeScript infiera la
+ * forma exacta del template (mismo truco que `defineBlocks`).
+ * `defineTemplate<MiCtx>()({ ... })`.
+ */
+export function defineTemplate<Ctx>() {
+  return <T extends Template<Ctx>>(template: T): T => template
+}

package/src/theme.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest"
+import { templateDemo } from "./__fixtures__/template-demo"
+import { templateThemeCss } from "./render"
+
+describe("templateThemeCss", () => {
+  it("emite la variable CSS del token publicado", () => {
+    const css = templateThemeCss(templateDemo, { "color-primario": "#ff0000" })
+    expect(css).toContain("--cms-primario: #ff0000")
+  })
+
+  it("omite tokens desconocidos sin romper (tolerante)", () => {
+    const css = templateThemeCss(templateDemo, { "token-inexistente": "#fff" })
+    expect(css).toBe("")
+    expect(css).not.toContain("token-inexistente")
+  })
+})

package/src/validate.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest"
+import { z } from "zod"
+import {
+  defineBlocks,
+  defineChrome,
+  type BlockDefinition,
+  type ChromeVariantDef,
+} from "@arroyavecommerce/cms-core"
+import { type Template } from "./template"
+import { templateDemo } from "./__fixtures__/template-demo"
+import { assertTemplateDefaults } from "./validate"
+
+describe("assertTemplateDefaults", () => {
+  it("no reporta problemas cuando todos los defaults pasan su schema", () => {
+    expect(assertTemplateDefaults(templateDemo)).toEqual([])
+  })
+
+  it("reporta el type del bloque cuyo default no pasa su schema", () => {
+    const malo: BlockDefinition<{ n: number }, unknown> = {
+      label: "Malo",
+      schema: z.object({ n: z.number() }),
+      // @ts-expect-error default inválido a propósito
+      defaults: { n: "no-es-numero" },
+      Component: () => null,
+    }
+    // @ts-expect-error spreading templateDemo with different context type
+    const t: Template<unknown> = {
+      ...templateDemo,
+      blocks: defineBlocks<unknown>()({ malo }),
+    }
+    expect(assertTemplateDefaults(t)).toEqual(["malo"])
+  })
+
+  it("reporta chrome:header:<key> y chrome:footer:<key> cuando sus defaults no pasan su schema", () => {
+    const headerMalo: ChromeVariantDef<{ n: number }, unknown> = {
+      label: "Header malo",
+      schema: z.object({ n: z.number() }),
+      // @ts-expect-error default inválido a propósito
+      defaults: { n: "no-es-numero" },
+      Component: () => null,
+    }
+    const footerMalo: ChromeVariantDef<{ n: number }, unknown> = {
+      label: "Footer malo",
+      schema: z.object({ n: z.number() }),
+      // @ts-expect-error default inválido a propósito
+      defaults: { n: "no-es-numero" },
+      Component: () => null,
+    }
+    const chrome = defineChrome<unknown>()({
+      headers: { malo: headerMalo },
+      footers: { malo: footerMalo },
+    })
+    // @ts-expect-error spreading templateDemo with different context type
+    const t: Template<unknown> = { ...templateDemo, chrome }
+    expect(assertTemplateDefaults(t)).toEqual(["chrome:header:malo", "chrome:footer:malo"])
+  })
+})

package/src/validate.ts

@@ -0,0 +1,30 @@
+import type { Template } from "./template"
+
+/**
+ * Verifica el contrato de un template: cada bloque (y, si existe, cada
+ * variante de chrome) debe tener `defaults` que pasen su propio `schema`.
+ * Devuelve las claves que fallan (vacío = sano) — `type` para bloques,
+ * `chrome:header:<key>`/`chrome:footer:<key>` para chrome. Útil como test
+ * de contrato de cada template-paquete.
+ */
+export function assertTemplateDefaults<Ctx>(template: Template<Ctx>): string[] {
+  const fallidos: string[] = []
+  for (const [type, def] of Object.entries(template.blocks)) {
+    if (!def.schema.safeParse(def.defaults).success) {
+      fallidos.push(type)
+    }
+  }
+  if (template.chrome) {
+    for (const [key, def] of Object.entries(template.chrome.headers)) {
+      if (!def.schema.safeParse(def.defaults).success) {
+        fallidos.push(`chrome:header:${key}`)
+      }
+    }
+    for (const [key, def] of Object.entries(template.chrome.footers)) {
+      if (!def.schema.safeParse(def.defaults).success) {
+        fallidos.push(`chrome:footer:${key}`)
+      }
+    }
+  }
+  return fallidos
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"]
+}