@bacano/sdk 1.1.17 → 1.1.18

package/README.md

@@ -118,6 +118,14 @@ official `BacanoForm` renderer or consume the same typed definition through
 `useBacanoForm()` without GraphQL, HTML stored in the database or a rebuild
 after each publication.
 
+Every visible region sourced from a Bacano `ContentEntry` must expose the
+entry-level marker defined in
+[`STOREFRONT_CONTENT_LOCATOR.md`](./STOREFRONT_CONTENT_LOCATOR.md). Use
+`getContentEntryLocatorAttributes(entry)` on the outer section or card so an
+authorized internal browser tool can show the entry name and open its Bacano
+editor. This contract identifies entries only; it does not expose field-level
+editing or grant backoffice access.
+
 Static and hybrid stores must also follow
 [`STOREFRONT_PERFORMANCE.md`](./STOREFRONT_PERFORMANCE.md). It defines the
 official build bootstrap, live-state refresh, responsive media and request

package/STOREFRONT_CONTENT_LOCATOR.md

@@ -0,0 +1,111 @@
+# Localizador de entradas de Content
+
+Este documento define el contrato público V1 que permite reconocer desde el
+navegador qué entrada de Bacano Content produce una región visible de una web.
+El objetivo es únicamente **identificar la entrada y abrir su editor**. No es
+edición inline y no identifica campos individuales.
+
+## Contrato obligatorio
+
+Toda región visual cuyo contenido editorial provenga de un `ContentEntry` debe
+marcar su elemento DOM exterior significativo con:
+
+```html
+<section
+  data-bacano-content-entry="v1"
+  data-bacano-entry-key="seccion-de-servicios"
+  data-bacano-entry-name="Sección de servicios"
+  data-bacano-entry-locale="es-CO"
+>
+  <!-- contenido visible -->
+</section>
+```
+
+Usar el helper oficial evita diferencias en nombres, versión y normalización:
+
+```tsx
+import {
+  getContentEntryLocatorAttributes,
+  type ContentEntry,
+} from "@bacano/sdk";
+
+function ServicesSection({ entry }: { entry: ContentEntry }) {
+  return (
+    <section {...getContentEntryLocatorAttributes(entry)}>
+      {/* La sección puede consumir un view model derivado de entry. */}
+    </section>
+  );
+}
+```
+
+El helper falla si la entrada no tiene una `key` estable o un `locale`. Una
+región que no puede abrir una entrada inequívoca no debe aparentar que sí puede.
+
+## Granularidad
+
+- Marcar una vez el bloque visual administrable: `section`, `article`, banner,
+  tarjeta o contenedor equivalente.
+- No marcar títulos, párrafos, botones ni campos individuales dentro del mismo
+  bloque.
+- Si una tarjeta visible usa otra entrada referenciada, la tarjeta recibe su
+  propio marcador anidado. El espacio restante conserva el marcador de la
+  entrada contenedora.
+- Si una entrada produce varias regiones independientes, cada región puede
+  repetir el mismo marcador.
+- No marcar texto perteneciente al código/i18n, productos del catálogo,
+  configuración pública ni documentos legales como si fueran Content.
+
+Los mappers pueden transformar `contentJson`, pero deben conservar el origen
+editorial necesario para llamar el helper. Por ejemplo:
+
+```ts
+const section = {
+  locator: getContentEntryLocatorAttributes(entry),
+  title: readTitle(entry.contentJson),
+};
+```
+
+```tsx
+<section {...section.locator}>{section.title}</section>
+```
+
+## Responsabilidades del consumidor
+
+Una extensión o herramienta de inspección:
+
+1. busca `[data-bacano-content-entry="v1"]`;
+2. muestra `data-bacano-entry-name` al usuario;
+3. usa `data-bacano-entry-key` y `data-bacano-entry-locale` para construir la
+   navegación hacia el backoffice;
+4. deja autenticación, empresa y permisos bajo control de Bacano.
+
+El SDK no publica una URL de administración ni abre ventanas. Ese destino
+pertenece a la herramienta interna y puede cambiar entre ambientes.
+
+## Seguridad y salida estática
+
+Los cuatro atributos contienen exclusivamente identidad editorial ya pública:
+versión, key, nombre y locale de una entrada publicada. Nunca incluir tokens,
+URLs administrativas firmadas, secretos, IDs de usuarios ni datos privados.
+
+Los marcadores no conceden permisos. El backoffice debe autenticar y autorizar
+cualquier lectura o modificación. En exports estáticos los atributos quedan
+materializados junto con el contenido publicado y se actualizan en el siguiente
+build.
+
+## Verificación
+
+Antes de publicar una web que usa Bacano Content:
+
+- inventariar las entradas que producen regiones visibles;
+- inspeccionar el HTML final, no solo JSX o componentes;
+- comprobar que cada región tiene exactamente la key, nombre y locale de su
+  entrada fuente;
+- probar marcadores anidados cuando una entrada contenedora renderiza entradas
+  referenciadas;
+- comprobar que activar una herramienta de localización no altera navegación,
+  layout ni accesibilidad cuando vuelve a desactivarse.
+
+Una región editorial sin marcador o con una key distinta de su fuente es un
+fallo de integración, porque impide localizar de manera confiable el contenido
+que la web declara administrable.

package/STOREFRONT_FORMS.md

@@ -81,6 +81,47 @@ El renderer personalizado puede cambiar componentes y estilos, pero debe usar
 los campos, keys, opciones y validaciones entregados por el SDK. No debe crear
 un segundo cliente, resolver el website nuevamente ni usar GraphQL directo.
 
+## Honeypot y confirmación de persistencia
+
+`honeypot` es un campo trampa contra bots, no un token de seguridad. No es una
+marca de tiempo, un UUID, un número aleatorio ni un identificador del visitante.
+Un usuario real debe enviarlo siempre vacío.
+
+- `BacanoForm` administra el honeypot internamente. El storefront no debe crear
+  otro ni asignarle un valor.
+- Un renderer personalizado debe omitir `honeypot` en
+  `client.forms.submitResponse(...)` salvo que implemente deliberadamente un
+  input trampa oculto. El SDK lo enviará como cadena vacía por defecto.
+- Si se implementa el input trampa, debe quedar fuera del flujo visual y del
+  teclado, con autocompletado desactivado. Nunca debe reutilizar un campo real ni
+  recibir sugerencias del navegador o de un gestor de contraseñas.
+- Bacano responde de manera deliberadamente genérica ante un honeypot lleno:
+  `accepted: true` y `responseId: null`. La respuesta no se persiste y el bot no
+  descubre que fue detectado.
+- Para una prueba funcional o aprobación de producción, el envío debe devolver
+  `accepted: true` y un UUID en `responseId`, y debe aparecer una sola vez en
+  Respuestas dentro de Bacano.
+
+No uses `responseId: null` para mostrar información distinta al visitante. Es
+una señal técnica para pruebas y observabilidad segura, no un mensaje que deba
+revelar la protección antispam.
+
+## Tipos semánticos de contacto
+
+La etiqueta y la key no sustituyen el tipo del campo. Si un dato representa un
+correo o un teléfono, el formulario debe definirlo como `email` o `phone`:
+
+- Bacano valida el formato según el tipo declarado.
+- Las respuestas conservan todos los valores, pero solo los campos `email` y
+  `phone` alimentan los datos de contacto normalizados de la respuesta.
+- Un campo `text` llamado `correo`, `email`, `telefono` o similar continúa
+  siendo texto libre. No debe dependerse de su nombre para CRM, leads o futuras
+  automatizaciones.
+
+Antes de publicar, revisa que los campos destinados a identificar o contactar a
+la persona tengan el tipo correcto. Cambiar únicamente su etiqueta no corrige el
+contrato de datos.
+
 ## Next.js y Static First
 
 Obtén la definición durante el build o desde un Server Component usando el
@@ -127,15 +168,32 @@ consultarlo.
   validación del navegador mejora la experiencia, pero no es autoritativa.
 - URL, referidor y atribución se sanean. Las respuestas y datos personales no
   se escriben en logs.
-- Una falla futura de correo, CRM o automatización no revierte la respuesta.
-- `CAPTURE_LEAD` se procesa en una fase posterior. Toda respuesta se conserva
-  primero y de forma independiente.
+- `pageUrl`, `referrerUrl` y la URL de atribución aceptan únicamente HTTP o
+  HTTPS. No envíes protocolos locales, ejecutables o de datos.
+- Los teléfonos admiten un `+` inicial y separadores habituales; Bacano los
+  normaliza antes de resolver identidad y rechaza letras o signos mal ubicados.
+- Los números usan notación decimal o científica explícita. Valores ambiguos
+  como `0x10` o `3 unidades` se rechazan aunque JavaScript pudiera convertirlos.
+- Un checkbox opcional omitido se conserva como `null`; uno requerido debe
+  enviarse expresamente como `true`.
+- Una falla de correo, CRM o automatización no revierte la respuesta.
+- `STORE_RESPONSE` conserva la respuesta sin crear un lead.
+- `CAPTURE_LEAD` conserva primero la respuesta y después resuelve internamente
+  la identidad canónica. Reutiliza un lead o cliente existente, crea un lead
+  cuando corresponde y manda a revisión las coincidencias contradictorias de
+  correo y teléfono sin fusionarlas automáticamente.
+- El resultado público continúa siendo deliberadamente genérico. El storefront
+  no recibe ni debe inferir si Bacano creó un lead, encontró un cliente o marcó
+  una identidad para revisión.
 
 ## Checklist mínimo del storefront
 
 - Usar un solo `BacanoProvider` y el cliente global ya inicializado.
 - Renderizar con `BacanoForm` o con `useBacanoForm`; nunca copiar la definición
   a un esquema local ni consultar GraphQL directamente.
+- Pueden coexistir varios `BacanoForm` en una página. El renderer oficial aísla
+  los identificadores de sus controles; no construyas IDs globales solo con la
+  key del campo.
 - Entregar `initialForm` cuando la página se genera de forma estática.
 - Respetar `ACTIVE`, `PAUSED`, versión y `definitionHash` sin inferir estados.
 - Mantener una `idempotencyKey` estable durante los reintentos del mismo envío.
@@ -143,5 +201,11 @@ consultarlo.
   reintento idempotente y error de red.
 - Confirmar en Bacano que una respuesta real quedó persistida antes de aprobar
   el flujo; no basta con mostrar el mensaje de éxito del navegador.
-- No prometer correo, lead, solicitud o automatización mientras la capacidad no
-  esté implementada y activa en Bacano.
+- Probar autocompletado del navegador y gestores de contraseñas: ningún campo
+  real puede llenar el honeypot. Un envío real debe devolver un UUID como
+  `responseId`; `null` no demuestra persistencia.
+- Verificar que correos y teléfonos utilicen los tipos `email` y `phone`, no
+  campos de texto con una etiqueta parecida.
+- No prometer correo, cupón, solicitud ni automatización mientras la capacidad
+  no esté implementada y activa en Bacano. Aunque `CAPTURE_LEAD` esté activo,
+  el mensaje público no debe afirmar qué identidad interna se creó o reutilizó.

package/content-entry-locator.d.ts

@@ -0,0 +1,16 @@
+import type { ContentEntry } from "./types";
+export declare const CONTENT_ENTRY_LOCATOR_VERSION: "v1";
+export declare const CONTENT_ENTRY_LOCATOR_SELECTOR: "[data-bacano-content-entry=\"v1\"]";
+export type ContentEntryLocatorSource = Pick<ContentEntry, "key" | "locale" | "name">;
+export interface ContentEntryLocatorAttributes {
+    "data-bacano-content-entry": typeof CONTENT_ENTRY_LOCATOR_VERSION;
+    "data-bacano-entry-key": string;
+    "data-bacano-entry-locale": string;
+    "data-bacano-entry-name": string;
+}
+/**
+ * Adds the public, non-authoritative marker consumed by Bacano's content
+ * locator. Spread the result only on the outermost meaningful DOM element
+ * whose visible editorial content is owned by the entry.
+ */
+export declare function getContentEntryLocatorAttributes(entry: ContentEntryLocatorSource): ContentEntryLocatorAttributes;

package/index.cjs

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthError: () => AuthError,
+  CONTENT_ENTRY_LOCATOR_SELECTOR: () => CONTENT_ENTRY_LOCATOR_SELECTOR,
+  CONTENT_ENTRY_LOCATOR_VERSION: () => CONTENT_ENTRY_LOCATOR_VERSION,
   CheckoutError: () => CheckoutError,
   GraphQLRequestError: () => GraphQLRequestError,
   MARKETING_SCHEMA_VERSION: () => MARKETING_SCHEMA_VERSION,
@@ -38,6 +40,7 @@ __export(index_exports, {
   createWebsiteMarketingRuntime: () => createWebsiteMarketingRuntime,
   formatMediaSrcSet: () => formatMediaSrcSet,
   getAllowedMarketingParameters: () => getAllowedMarketingParameters,
+  getContentEntryLocatorAttributes: () => getContentEntryLocatorAttributes,
   getPrimaryProductImage: () => getPrimaryProductImage,
   getProductDetailVariants: () => getProductDetailVariants,
   getProductImages: () => getProductImages,
@@ -6904,3 +6907,23 @@ function createBacanoClient(config) {
     }
   };
 }
+
+// libs/sdk/src/content-entry-locator.ts
+var CONTENT_ENTRY_LOCATOR_VERSION = "v1";
+var CONTENT_ENTRY_LOCATOR_SELECTOR = `[data-bacano-content-entry="${CONTENT_ENTRY_LOCATOR_VERSION}"]`;
+function getContentEntryLocatorAttributes(entry) {
+  const key = entry.key?.trim();
+  if (!key) {
+    throw new Error("A Bacano Content locator requires a stable entry key.");
+  }
+  const locale = entry.locale.trim();
+  if (!locale) {
+    throw new Error("A Bacano Content locator requires an entry locale.");
+  }
+  return {
+    "data-bacano-content-entry": CONTENT_ENTRY_LOCATOR_VERSION,
+    "data-bacano-entry-key": key,
+    "data-bacano-entry-locale": locale,
+    "data-bacano-entry-name": entry.name.trim() || key
+  };
+}

package/index.d.ts

@@ -1,5 +1,7 @@
 export type { BacanoClient } from "./client";
 export { createBacanoClient } from "./client";
+export type { ContentEntryLocatorAttributes, ContentEntryLocatorSource, } from "./content-entry-locator";
+export { CONTENT_ENTRY_LOCATOR_SELECTOR, CONTENT_ENTRY_LOCATOR_VERSION, getContentEntryLocatorAttributes, } from "./content-entry-locator";
 export { AuthError, CheckoutError, GraphQLRequestError, NotInitializedError, RateLimitError, WebsiteError, } from "./errors";
 export type { WebsiteAdvertisingConsent, WebsiteMarketingAttribution, WebsiteMarketingBrowserEvent, WebsiteMarketingBrowserEventName, WebsiteMarketingContactPlacement, WebsiteMarketingDiagnostic, WebsiteMarketingItem, WebsiteMarketingRuntime, WebsiteMarketingRuntimeOptions, WebsiteMarketingScriptLoadStrategy, WebsiteMarketingTouchpoint, } from "./marketing";
 export { captureWebsiteMarketingAttribution, createWebsiteMarketingRuntime, getAllowedMarketingParameters, getWebsiteMarketingAttribution, MARKETING_SCHEMA_VERSION, sanitizeMarketingUrl, WEBSITE_MARKETING_CONTACT_PLACEMENTS, } from "./marketing";

package/index.js

@@ -6850,8 +6850,30 @@ function createBacanoClient(config) {
     }
   };
 }
+
+// libs/sdk/src/content-entry-locator.ts
+var CONTENT_ENTRY_LOCATOR_VERSION = "v1";
+var CONTENT_ENTRY_LOCATOR_SELECTOR = `[data-bacano-content-entry="${CONTENT_ENTRY_LOCATOR_VERSION}"]`;
+function getContentEntryLocatorAttributes(entry) {
+  const key = entry.key?.trim();
+  if (!key) {
+    throw new Error("A Bacano Content locator requires a stable entry key.");
+  }
+  const locale = entry.locale.trim();
+  if (!locale) {
+    throw new Error("A Bacano Content locator requires an entry locale.");
+  }
+  return {
+    "data-bacano-content-entry": CONTENT_ENTRY_LOCATOR_VERSION,
+    "data-bacano-entry-key": key,
+    "data-bacano-entry-locale": locale,
+    "data-bacano-entry-name": entry.name.trim() || key
+  };
+}
 export {
   AuthError,
+  CONTENT_ENTRY_LOCATOR_SELECTOR,
+  CONTENT_ENTRY_LOCATOR_VERSION,
   CheckoutError,
   GraphQLRequestError,
   MARKETING_SCHEMA_VERSION,
@@ -6869,6 +6891,7 @@ export {
   createWebsiteMarketingRuntime,
   formatMediaSrcSet,
   getAllowedMarketingParameters,
+  getContentEntryLocatorAttributes,
   getPrimaryProductImage,
   getProductDetailVariants,
   getProductImages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacano/sdk",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "description": "TypeScript SDK for building websites on the Bacano ERP",
   "main": "./index.cjs",
   "module": "./index.js",

package/react/form-field-control.d.ts

@@ -3,6 +3,7 @@ import type { BacanoFormValues } from "./forms";
 type BacanoFormValue = BacanoFormValues[string];
 export declare function BacanoFormFieldControl(props: {
     field: WebsiteFormField;
+    id?: string;
     className?: string;
     value: BacanoFormValue;
     onChange(value: BacanoFormValue): void;

package/react/forms.cjs

@@ -30,8 +30,9 @@ var import_react3 = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
 function BacanoFormFieldControl(props) {
   const { field, className, value, onChange } = props;
+  const controlId = props.id ?? field.key;
   const common = {
-    id: field.key,
+    id: controlId,
     name: field.key,
     required: field.required,
     className
@@ -71,7 +72,7 @@ function BacanoFormFieldControl(props) {
     );
   }
   if (field.type === "radio") {
-    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { role: "radiogroup", "aria-labelledby": `${field.key}-label`, children: (field.options ?? []).map((option) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { children: [
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { role: "radiogroup", "aria-labelledby": `${controlId}-label`, children: (field.options ?? []).map((option) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { children: [
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
         "input",
         {
@@ -210,13 +211,14 @@ function useBacanoForm(formKey, options) {
 }
 function FormFields(props) {
   return props.fields.map((field) => {
+    const controlId = `${props.idPrefix}-${field.key}`;
     const value = props.values[field.key] ?? (field.type === "checkbox" ? false : field.type === "multi_select" ? [] : "");
     return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: props.classNames?.field, children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
         "label",
         {
-          id: `${field.key}-label`,
-          htmlFor: field.type === "radio" ? void 0 : field.key,
+          id: `${controlId}-label`,
+          htmlFor: field.type === "radio" ? void 0 : controlId,
           className: props.classNames?.label,
           children: field.label
         }
@@ -225,6 +227,7 @@ function FormFields(props) {
         BacanoFormFieldControl,
         {
           field,
+          id: controlId,
           value,
           className: props.classNames?.input,
           onChange: (nextValue) => props.onChange(field.key, nextValue)
@@ -242,6 +245,7 @@ function FormSections(props) {
       FormFields,
       {
         fields: section.fields,
+        idPrefix: props.idPrefix,
         values: props.values,
         classNames: props.classNames,
         onChange: props.onChange
@@ -250,6 +254,8 @@ function FormSections(props) {
   ] }, section.key));
 }
 function BacanoForm(props) {
+  const reactId = (0, import_react3.useId)();
+  const idPrefix = `${props.formKey}-${reactId.replace(/:/g, "")}`;
   const { client } = useBacanoState();
   const { form, loading, error } = useBacanoForm(props.formKey, {
     initialForm: props.initialForm
@@ -382,6 +388,7 @@ function BacanoForm(props) {
             FormFields,
             {
               fields: activeStep.fields,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -391,6 +398,7 @@ function BacanoForm(props) {
             FormSections,
             {
               sections: activeStep.sections,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -401,6 +409,7 @@ function BacanoForm(props) {
             FormFields,
             {
               fields,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -410,6 +419,7 @@ function BacanoForm(props) {
             FormSections,
             {
               sections,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue

package/react/forms.js

@@ -2,6 +2,7 @@
 import {
   useCallback as useCallback2,
   useEffect as useEffect2,
+  useId,
   useMemo,
   useRef as useRef2,
   useState as useState2
@@ -11,8 +12,9 @@ import {
 import { jsx, jsxs } from "react/jsx-runtime";
 function BacanoFormFieldControl(props) {
   const { field, className, value, onChange } = props;
+  const controlId = props.id ?? field.key;
   const common = {
-    id: field.key,
+    id: controlId,
     name: field.key,
     required: field.required,
     className
@@ -52,7 +54,7 @@ function BacanoFormFieldControl(props) {
     );
   }
   if (field.type === "radio") {
-    return /* @__PURE__ */ jsx("div", { role: "radiogroup", "aria-labelledby": `${field.key}-label`, children: (field.options ?? []).map((option) => /* @__PURE__ */ jsxs("label", { children: [
+    return /* @__PURE__ */ jsx("div", { role: "radiogroup", "aria-labelledby": `${controlId}-label`, children: (field.options ?? []).map((option) => /* @__PURE__ */ jsxs("label", { children: [
       /* @__PURE__ */ jsx(
         "input",
         {
@@ -191,13 +193,14 @@ function useBacanoForm(formKey, options) {
 }
 function FormFields(props) {
   return props.fields.map((field) => {
+    const controlId = `${props.idPrefix}-${field.key}`;
     const value = props.values[field.key] ?? (field.type === "checkbox" ? false : field.type === "multi_select" ? [] : "");
     return /* @__PURE__ */ jsxs2("div", { className: props.classNames?.field, children: [
       /* @__PURE__ */ jsx2(
         "label",
         {
-          id: `${field.key}-label`,
-          htmlFor: field.type === "radio" ? void 0 : field.key,
+          id: `${controlId}-label`,
+          htmlFor: field.type === "radio" ? void 0 : controlId,
           className: props.classNames?.label,
           children: field.label
         }
@@ -206,6 +209,7 @@ function FormFields(props) {
         BacanoFormFieldControl,
         {
           field,
+          id: controlId,
           value,
           className: props.classNames?.input,
           onChange: (nextValue) => props.onChange(field.key, nextValue)
@@ -223,6 +227,7 @@ function FormSections(props) {
       FormFields,
       {
         fields: section.fields,
+        idPrefix: props.idPrefix,
         values: props.values,
         classNames: props.classNames,
         onChange: props.onChange
@@ -231,6 +236,8 @@ function FormSections(props) {
   ] }, section.key));
 }
 function BacanoForm(props) {
+  const reactId = useId();
+  const idPrefix = `${props.formKey}-${reactId.replace(/:/g, "")}`;
   const { client } = useBacanoState();
   const { form, loading, error } = useBacanoForm(props.formKey, {
     initialForm: props.initialForm
@@ -363,6 +370,7 @@ function BacanoForm(props) {
             FormFields,
             {
               fields: activeStep.fields,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -372,6 +380,7 @@ function BacanoForm(props) {
             FormSections,
             {
               sections: activeStep.sections,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -382,6 +391,7 @@ function BacanoForm(props) {
             FormFields,
             {
               fields,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue
@@ -391,6 +401,7 @@ function BacanoForm(props) {
             FormSections,
             {
               sections,
+              idPrefix,
               values,
               classNames: props.classNames,
               onChange: setFieldValue

package/skills/bacano-figma-web/SKILL.md

@@ -91,6 +91,11 @@ Figma, desde Bacano Content o desde ambas fuentes.
   los contratos específicos del SDK.
 - No usar GraphQL directo, endpoints internos ni lógica comercial duplicada.
 - No codificar textos editables si pertenecen a Bacano Content.
+- Marcar obligatoriamente cada región visual proveniente de un `ContentEntry`
+  con `getContentEntryLocatorAttributes(entry)`. El marcador identifica la
+  entrada completa, nunca campos individuales. Conservar esta identidad al
+  transformar Content en view models y seguir
+  `STOREFRONT_CONTENT_LOCATOR.md`.
 - No alterar Baby Rex u otra referencia salvo que ese sea el proyecto indicado.
 
 Si Content todavía no existe, generar un blueprint de entrega y fixtures
@@ -147,6 +152,9 @@ proyecto.
 Antes de aprobar producción, comprobar que la fuente editorial efectiva sea
 Bacano Content. Un fixture, placeholder o fallback temporal accesible en el
 build de producción es un bloqueo, aunque visualmente coincida con Figma.
+Inspeccionar además el HTML final: toda región alimentada por una entrada debe
+conservar su marcador V1 con la key, nombre y locale correctos. Una región
+editorial sin marcador bloquea la aprobación.
 
 Al finalizar, invocar `$bacano-web` si está disponible para la auditoría de
 producción completa. Esta skill valida fidelidad y correcta integración desde

package/skills/bacano-figma-web/references/bacano-mapping.md

@@ -7,9 +7,9 @@ negocio.
 
 Antes de programar, registrar por ruta:
 
-| Ruta | Frame | Componente | Fuente | Content | Responsive | Preview | Estado |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `/` | Home desktop/mobile | `Hero` | Content | `hero_inicio` | 2 frames | activa | pendiente |
+| Ruta | Frame | Componente | Fuente | Content | Localizador | Responsive | Preview | Estado |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `/` | Home desktop/mobile | `Hero` | Content | `hero_inicio` | entrada V1 | 2 frames | activa | pendiente |
 
 Fuentes posibles: Content, catálogo estático, live state, public config,
 checkout, auth u otra operación documentada del SDK.
@@ -18,6 +18,8 @@ checkout, auth u otra operación documentada del SDK.
 
 - Usar componentes y tokens existentes antes de crear otros.
 - Mapear textos/imágenes editoriales a Content cuando deban ser administrables.
+- Para cada fuente `ContentEntry`, conservar y renderizar el marcador de entrada
+  definido en `STOREFRONT_CONTENT_LOCATOR.md`; no bajar a nivel de campo.
 - Si el equipo de Content y desarrollo trabajan en tiempos distintos, seguir
   [content-workflow.md](content-workflow.md) y mantener un único contrato de
   datos entre fixtures temporales y Bacano real.

package/skills/bacano-figma-web/references/content-workflow.md

@@ -35,6 +35,10 @@ reduzca duplicación real.
   consumidores.
 - No hacer depender la UI del shape crudo de Content: fixture y mapper real
   deben converger en el mismo view model.
+- Conservar en ese view model los atributos producidos por
+  `getContentEntryLocatorAttributes(entry)`. Toda región visual administrada
+  por una entrada debe exponerlos en su contenedor DOM exterior; no se marcan
+  campos individuales.
 
 ## 2. Elegir el punto de partida
 
@@ -138,6 +142,10 @@ Bacano mapper ─┘
 El cambio de fuente debe ocurrir en el loader o repositorio de contenido, nunca
 mediante condicionales repartidos por los componentes.
 
+Los fixtures pueden simular el view model, pero no deben inventar marcadores de
+entrada en producción. El marcador definitivo se deriva del `ContentEntry`
+real para que nombre, key y locale no diverjan.
+
 ## 5. Entrega al equipo de Content
 
 Entregar una tabla legible con:
@@ -167,7 +175,9 @@ Antes de retirar el fixture:
 2. Validar campos requeridos, media y contenido largo.
 3. Comparar la página con Figma usando Content real.
 4. Verificar preview si la capacidad está activa.
-5. Eliminar el fixture del camino de ejecución, no necesariamente de los tests.
+5. Inspeccionar el HTML y confirmar los marcadores definidos en
+   `STOREFRONT_CONTENT_LOCATOR.md` para cada región editorial.
+6. Eliminar el fixture del camino de ejecución, no necesariamente de los tests.
 
 En producción no se permite fallback silencioso a fixtures. Si una página
 depende de contenido temporal, reportar `❌ NO LISTO` con las rutas y secciones

package/skills/bacano-figma-web/references/implementation-quality.md

@@ -58,6 +58,18 @@ no aceptar una ruta arbitraria solo porque coincide con una cadena. Preview
 reutiliza componentes y mappers de producción, permanece fuera del sitemap y
 no habilita funciones transaccionales o marketing.
 
+## Trazabilidad editorial
+
+Al mapear un `ContentEntry`, conservar los atributos retornados por
+`getContentEntryLocatorAttributes(entry)` hasta el componente visual. Aplicar
+el spread al `section`, `article`, banner o tarjeta exterior que representa la
+entrada. No repetirlo en cada título o párrafo. Si una tarjeta proviene de otra
+entrada referenciada, esa tarjeta lleva su propio marcador anidado.
+
+La salida final debe cumplir `STOREFRONT_CONTENT_LOCATOR.md`. Verificar el HTML
+generado; encontrar la llamada al helper en TypeScript no demuestra que el
+marcador haya llegado al DOM.
+
 ## Diagnóstico antes de cambiar código
 
 Un `ORIGIN_NOT_ALLOWED` o un `403` al resolver la configuración durante el

package/skills/bacano-web/SKILL.md

@@ -47,7 +47,8 @@ Después leer solo:
 Si `@bacano/sdk` está disponible, leer sus contratos canónicos aplicables antes
 de proponer cambios. Como mínimo revisar `STOREFRONT_LEGAL.md`,
 `STOREFRONT_MARKETING.md`, `STOREFRONT_PERFORMANCE.md` y
-`STOREFRONT_PREVIEW.md`; añadir
+`STOREFRONT_PREVIEW.md`; si el sitio renderiza Bacano Content, leer también y
+aplicar obligatoriamente `STOREFRONT_CONTENT_LOCATOR.md`; añadir
 `AUTHENTICATION.md`, `STOREFRONT_LEADS.md`, `STOREFRONT_CLARITY.md` y
 otros contratos únicamente cuando esas capacidades existan. Leer
 `STOREFRONT_CONSTRUCTION.md` cuando el website permita ocultarse temporalmente.
@@ -70,6 +71,8 @@ ejecutar compras/pagos sin autorización explícita.
 5. Comparar router, salida del build y sitemap; ninguna ruta pública debe
    omitirse silenciosamente.
 6. Inspeccionar HTML generado, metadata, JSON-LD, media y enlaces internos.
+   Si existe Content, comparar las entradas renderizadas con los marcadores V1
+   presentes en ese HTML; revisar únicamente el JSX no es evidencia suficiente.
 7. Si existe un dominio o una aplicación ejecutable, auditar sus rutas reales,
    la consola y un trace de red con nombres y conteos de operaciones GraphQL.
 8. Probar vistas representativas desktop y mobile.

package/skills/bacano-web/references/common.md

@@ -29,6 +29,13 @@ función apagada en un bloqueo artificial.
 - Comprobar que preview, callbacks, cuenta, checkout y respuestas de pago no se
   indexen cuando corresponda.
 - Validar estados vacío, loading, error y ausencia de Content opcional.
+- `P0`: toda región visual cuya fuente sea un `ContentEntry` expone en el HTML
+  final el marcador de `STOREFRONT_CONTENT_LOCATOR.md`, con la key, nombre y
+  locale de la entrada fuente. El control es por entrada completa, no por campo.
+- Comparar inventario de entradas y regiones. Permitir marcadores repetidos si
+  una entrada aparece en varios lugares y marcadores anidados cuando una tarjeta
+  proviene de otra entrada referenciada. No exigirlos a código/i18n, catálogo,
+  `publicConfig` ni documentos legales.
 
 ## SEO y compartición
 

package/skills/bacano-web/references/forms.md

@@ -23,12 +23,25 @@ desde Bacano. Leer también `STOREFRONT_FORMS.md` completo desde el paquete SDK.
 
 - Enviar mediante `client.forms.submitResponse()` o el envío interno de
   `BacanoForm`.
+- `honeypot` es un campo trampa, no un nonce, timestamp, UUID ni dato del
+  visitante. `BacanoForm` lo administra. En un renderer manual, omitirlo salvo
+  que exista un input trampa realmente oculto; para una persona siempre debe
+  permanecer vacío y el autocompletado no debe llenarlo.
+- `accepted: true` con `responseId: null` es una aceptación silenciosa antispam:
+  no demuestra que la respuesta fue guardada. La verificación funcional exige
+  un UUID y la respuesta visible una sola vez en Bacano.
+- Los datos de contacto deben conservar su semántica: usar campos `email` y
+  `phone`. Un campo `text` llamado correo o teléfono se guarda como texto libre
+  y no alimenta los datos de contacto normalizados para CRM o automatizaciones.
 - Conservar una `idempotencyKey` durante reintentos del mismo intento lógico.
 - Enviar la versión y `definitionHash` exactos de la definición renderizada.
 - Respetar estados `ACTIVE` y `PAUSED`; no renderizar borradores o archivados.
 - No escribir respuestas o PII en consola, analítica, URLs o logs del storefront.
-- No afirmar que se creó un lead, se envió un correo o se abrió una solicitud si
-  esa acción aún no está implementada y verificada en Bacano.
+- En `CAPTURE_LEAD`, Bacano conserva primero la respuesta y resuelve la identidad
+  internamente. No afirmar al visitante que se creó un lead o que ya era cliente:
+  la respuesta pública es genérica y no expone ese resultado.
+- No afirmar que se envió un correo, se entregó un cupón o se abrió una solicitud
+  si esa acción aún no está implementada y verificada en Bacano.
 - Una brecha del SDK se reporta; nunca se resuelve con GraphQL directo ni una API
   paralela del storefront.
 
@@ -41,6 +54,10 @@ desde Bacano. Leer también `STOREFRONT_FORMS.md` completo desde el paquete SDK.
 - Error de red: estado recuperable sin promesa falsa de recepción.
 - Persistencia: la respuesta aparece una sola vez en Bacano con versión, origen y
   snapshot correctos.
+- Autocompletado: completar datos con el navegador o un gestor de contraseñas no
+  llena el honeypot ni produce `responseId: null`.
+- Semántica: correo y teléfono usan `email` y `phone`; no se infieren por label o
+  key.
 - Accesibilidad: label asociado, foco, teclado, mensajes de error y progreso de
   pasos comprensibles.
 - Static First: el HTML exportado conserva el formulario cuando corresponde.

package/types.d.ts

@@ -224,11 +224,15 @@ export interface WebsiteFormResponseInput {
     idempotencyKey: string;
     values: Record<string, WebsiteFormResponseValue>;
     source?: WebsiteFormResponseSource;
-    /** Bot-trap field. Storefronts should render it visually hidden and leave it empty. */
+    /**
+     * Bot-trap field, not a token or nonce. Omit it unless a real hidden trap is
+     * rendered; legitimate visitors must always submit an empty value.
+     */
     honeypot?: string;
 }
 export interface WebsiteFormResponseResult {
     accepted: boolean;
+    /** A null value is not proof of persistence (for example, an anti-bot response). */
     responseId: string | null;
     message: string;
 }