@axzydev/axzy_ui_system 1.6.0 → 1.7.1

package/src/json-renderer/validation/validate.ts

@@ -0,0 +1,161 @@
+/**
+ * Validación de esquemas con **tres veredictos**.
+ *
+ * Un esquema a medio llegar no es un esquema roto: `partial` significa "válido
+ * hasta donde ha llegado", y es el estado normal mientras un emisor (una IA, por
+ * ejemplo) sigue escribiendo. `invalid` es lo que no se puede pintar ni esperar.
+ */
+
+import { issue, type JsonEngineIssue } from "../shared/errors";
+import { formatPath } from "../shared/paths";
+import type { Catalog } from "../catalog/catalog.props";
+import { axzyCatalog } from "../catalog/axzyCatalog";
+import { resolveNode } from "../catalog/resolve";
+import type { NodeSchema, ScreenSchema } from "../kernel/types";
+import { isNodePending } from "../stream/tolerantParse";
+
+/** Veredicto de la validación. */
+export type ValidationVerdict = "valid" | "partial" | "invalid";
+
+/** Informe de validación. */
+export interface ValidationReport {
+  /** Veredicto global. */
+  verdict: ValidationVerdict;
+  /** Errores que impiden pintar. */
+  errors: JsonEngineIssue[];
+  /** Avisos que no impiden pintar. */
+  warnings: JsonEngineIssue[];
+  /** Nodos que aún no están cerrados. */
+  pendingNodes: number;
+  /** Versión del esquema, si la declara. */
+  version?: number;
+}
+
+/** Opciones de validación. */
+export interface ValidateOptions {
+  /** Catálogo contra el que se validan tipos y props. @default axzyCatalog */
+  catalog?: Catalog;
+  /** Versión máxima admitida del formato. @default 1 */
+  maxVersion?: number;
+}
+
+/** Versión actual del formato de pantalla. */
+export const CURRENT_SCHEMA_VERSION = 1;
+
+/** Recorre el árbol y valida cada nodo contra el catálogo. */
+function validateNodes(
+  node: NodeSchema,
+  path: (string | number)[],
+  catalog: Catalog,
+  errors: JsonEngineIssue[],
+  warnings: JsonEngineIssue[]
+): number {
+  if (!node || typeof node !== "object") {
+    errors.push(issue("JR021", "El nodo no es un objeto.", formatPath(path), { severity: "error" }));
+    return 0;
+  }
+
+  // Un nodo pendiente no es un error: aún no ha llegado.
+  if (isNodePending(node)) return 1;
+
+  const resolved = resolveNode(node, catalog, path);
+  for (const item of resolved.issues) {
+    (item.severity === "error" ? errors : warnings).push(item);
+  }
+
+  let pending = 0;
+  const children = node.children === undefined ? [] : Array.isArray(node.children) ? node.children : [node.children];
+  children.forEach((child, index) => {
+    pending += validateNodes(child, [...path, "children", index], catalog, errors, warnings);
+  });
+  return pending;
+}
+
+/**
+ * Valida un esquema de pantalla.
+ *
+ * No lanza nunca: devuelve un informe con el veredicto y los avisos, cada uno con
+ * su código y su ruta.
+ *
+ * @example
+ * validateSchema({ version: 1, id: "x", content: { type: "ITText", text: "ok" } }).verdict; // "valid"
+ *
+ * @example
+ * validateSchema(parsePartialSchema(tokens).tree).verdict; // "partial" mientras llega
+ */
+export function validateSchema(schema: unknown, options: ValidateOptions = {}): ValidationReport {
+  const catalog = options.catalog ?? axzyCatalog;
+  const maxVersion = options.maxVersion ?? CURRENT_SCHEMA_VERSION;
+  const errors: JsonEngineIssue[] = [];
+  const warnings: JsonEngineIssue[] = [];
+
+  if (schema === null || schema === undefined) {
+    return { verdict: "invalid", errors: [issue("JR020", "No hay esquema que validar.", "")], warnings, pendingNodes: 0 };
+  }
+
+  if (typeof schema !== "object" || Array.isArray(schema)) {
+    return {
+      verdict: "invalid",
+      errors: [issue("JR020", "El esquema debe ser un objeto.", "", { severity: "error" })],
+      warnings,
+      pendingNodes: 0,
+    };
+  }
+
+  const candidate = schema as ScreenSchema;
+
+  // 1. Formato y versión.
+  if (candidate.$schema !== undefined && candidate.$schema !== "axzy/screen") {
+    errors.push(
+      issue("JR020", `El formato declarado no es \`axzy/screen\`.`, "$schema", {
+        severity: "error",
+        hint: "Usa `$schema: \"axzy/screen\"` o quita la propiedad.",
+      })
+    );
+  }
+
+  if (candidate.version === undefined) {
+    errors.push(issue("JR020", "Falta `version` en el esquema.", "version", { severity: "error" }));
+  } else if (typeof candidate.version !== "number" || !Number.isInteger(candidate.version)) {
+    errors.push(issue("JR020", "`version` debe ser un entero.", "version", { severity: "error" }));
+  } else if (candidate.version > maxVersion) {
+    errors.push(
+      issue("JR020", `La versión ${candidate.version} es más nueva que la soportada (${maxVersion}).`, "version", {
+        severity: "error",
+        hint: "Actualiza el motor o migra el esquema.",
+      })
+    );
+  }
+
+  // 2. Identidad del esquema.
+  if (typeof candidate.id !== "string" || candidate.id.trim() === "") {
+    errors.push(issue("JR020", "Falta `id` en el esquema.", "id", { severity: "error" }));
+  }
+
+  // 3. Contenido.
+  if (candidate.content === undefined) {
+    errors.push(issue("JR020", "El esquema no declara `content`.", "content", { severity: "error" }));
+    return { verdict: "invalid", errors, warnings, pendingNodes: 0, version: candidate.version };
+  }
+
+  const content = Array.isArray(candidate.content) ? candidate.content : [candidate.content];
+  if (content.length === 0) {
+    warnings.push(
+      issue("JR021", "`content` está vacío: la pantalla se pinta sin nodos.", "content", { severity: "warning" })
+    );
+  }
+
+  let pendingNodes = 0;
+  content
+    .map((node, index) => ({ node, index }))
+    // Un árbol parcial puede traer huecos: se ignoran, no se reportan.
+    .filter(({ node }) => node !== undefined && node !== null)
+    .forEach(({ node, index }) => {
+      pendingNodes += validateNodes(node, ["content", index], catalog, errors, warnings);
+    });
+
+  // 4. Veredicto: un error real invalida; nodos pendientes solo lo hacen parcial.
+  const verdict: ValidationVerdict = errors.length > 0 ? "invalid" : pendingNodes > 0 ? "partial" : "valid";
+
+  return { verdict, errors, warnings, pendingNodes, version: candidate.version };
+}

package/src/json-renderer/validation/validation.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from "vitest";
+import { axzyCatalog } from "../catalog/axzyCatalog";
+import { parsePartialSchema } from "../stream/tolerantParse";
+import type { ScreenSchema } from "../kernel/types";
+import { CURRENT_SCHEMA_VERSION, validateSchema } from "./validate";
+import { migrateSchema, type MigrationRegistry } from "./migrate";
+import { buildVocabularyContract, formatVocabularyForPrompt } from "../vocabulary/buildContract";
+
+const screen = (content: ScreenSchema["content"]): ScreenSchema => ({ version: 1, id: "test", content });
+
+describe("validateSchema", () => {
+  it("da por válido un esquema correcto", () => {
+    const report = validateSchema(screen({ type: "ITText", text: "Hola" }));
+    expect(report.verdict).toBe("valid");
+    expect(report.errors).toHaveLength(0);
+    expect(report.warnings).toHaveLength(0);
+  });
+
+  it("declara partial un esquema a medias y sin errores", () => {
+    const full = JSON.stringify(screen([{ type: "ITText", text: "uno" }, { type: "ITCard", props: { title: "dos" } }]));
+    const cut = full.indexOf('"title"') + 4;
+    const partial = parsePartialSchema(full.slice(0, cut));
+    const report = validateSchema(partial.tree);
+
+    expect(report.verdict).toBe("partial");
+    expect(report.errors).toHaveLength(0);
+    expect(report.pendingNodes).toBeGreaterThan(0);
+  });
+
+  it("invalida un esquema sin versión", () => {
+    const report = validateSchema({ id: "x", content: { type: "ITText", text: "x" } });
+    expect(report.verdict).toBe("invalid");
+    expect(report.errors.some((e) => e.code === "JR020" && e.path === "version")).toBe(true);
+  });
+
+  it("invalida una versión futura", () => {
+    const report = validateSchema({ version: 99, id: "x", content: { type: "ITText", text: "x" } });
+    expect(report.verdict).toBe("invalid");
+    expect(report.errors[0]?.message).toContain("99");
+  });
+
+  it("invalida un esquema sin id o sin content", () => {
+    expect(validateSchema({ version: 1, content: { type: "ITText" } }).verdict).toBe("invalid");
+    expect(validateSchema({ version: 1, id: "x" }).verdict).toBe("invalid");
+  });
+
+  it("separa errores de avisos: prop desconocida es aviso, tipo desconocido es error", () => {
+    const report = validateSchema(
+      screen([
+        { type: "ITText", text: "ok", props: { inventada: 1 } },
+        { type: "ITNope" },
+      ] as ScreenSchema["content"])
+    );
+    expect(report.verdict).toBe("invalid");
+    expect(report.errors.some((e) => e.code === "JR010")).toBe(true);
+    expect(report.warnings.some((w) => w.code === "JR011")).toBe(true);
+  });
+
+  it("no se cae con un esquema parcial sin content", () => {
+    const { tree } = parsePartialSchema('{"version":1,"id":"x"');
+    const report = validateSchema(tree);
+    expect(() => validateSchema(tree)).not.toThrow();
+    // Sin content todavía: no es un error del esquema, es un stream a medias.
+    expect(report.errors.some((e) => e.path === "content")).toBe(true);
+  });
+
+  it("no lanza con entradas absurdas", () => {
+    for (const value of [null, undefined, 42, "texto", [], [1, 2]]) {
+      expect(() => validateSchema(value)).not.toThrow();
+      expect(validateSchema(value).verdict).toBe("invalid");
+    }
+  });
+
+  it("acepta el formato completo con $schema", () => {
+    const report = validateSchema({
+      $schema: "axzy/screen",
+      version: CURRENT_SCHEMA_VERSION,
+      id: "demo",
+      content: { type: "ITCard", props: { title: "ok" }, children: [{ type: "ITText", text: "x" }] },
+    });
+    expect(report.verdict).toBe("valid");
+  });
+});
+
+describe("migrateSchema", () => {
+  it("no migra si ya está en la versión objetivo", () => {
+    const result = migrateSchema(screen({ type: "ITText", text: "x" }), 1);
+    expect(result.migrated).toBe(false);
+    expect(result.issues).toHaveLength(0);
+  });
+
+  it("avisa cuando falta la migración (JR070)", () => {
+    const result = migrateSchema({ ...screen({ type: "ITText", text: "x" }), version: 1 }, 2, {});
+    expect(result.migrated).toBe(false);
+    expect(result.issues[0]?.code).toBe("JR070");
+  });
+
+  it("aplica migraciones en cadena", () => {
+    const migrations: MigrationRegistry = {
+      1: (schema) => ({ ...schema, id: `${schema.id}-v2` }),
+      2: (schema) => ({ ...schema, id: `${schema.id}-v3` }),
+    };
+    const result = migrateSchema({ ...screen({ type: "ITText", text: "x" }), version: 1 }, 3, migrations);
+    expect(result.migrated).toBe(true);
+    expect(result.to).toBe(3);
+    expect(result.schema.version).toBe(3);
+    expect(result.schema.id).toBe("test-v2-v3");
+  });
+
+  it("no permite degradar un esquema", () => {
+    const result = migrateSchema({ ...screen({ type: "ITText", text: "x" }), version: 3 }, 1);
+    expect(result.migrated).toBe(false);
+    expect(result.issues[0]?.code).toBe("JR020");
+  });
+});
+
+describe("contrato de vocabulario", () => {
+  const contract = buildVocabularyContract();
+
+  it("cubre todos los tipos del catálogo", () => {
+    expect(contract.components).toHaveLength(Object.keys(axzyCatalog.entries).length);
+    expect(contract.components.map((c) => c.type)).toContain("ITCard");
+  });
+
+  it("publica props con tipo y obligatoriedad", () => {
+    const card = contract.components.find((c) => c.type === "ITCard");
+    expect(card?.props.some((p) => p.name === "title" && p.kind === "string")).toBe(true);
+    expect(card?.props.find((p) => p.name === "title")?.required).toBe(false);
+
+    const image = contract.components.find((c) => c.type === "ITImage");
+    expect(image?.props.find((p) => p.name === "src")?.required).toBe(true);
+  });
+
+  it("incluye enums y valores admitidos", () => {
+    const alert = contract.components.find((c) => c.type === "ITAlert");
+    const variant = alert?.props.find((p) => p.name === "variant");
+    expect(variant?.values).toEqual(["info", "success", "warning", "error"]);
+  });
+
+  it("da un nodo mínimo que funciona para cada componente", () => {
+    for (const component of contract.components) {
+      const report = validateSchema(screen(component.minimal as never));
+      expect(report.errors, `mínimo inválido para ${component.type}`).toHaveLength(0);
+    }
+  });
+
+  it("publica las exclusiones con su motivo", () => {
+    expect(contract.excluded.ITWysiwyg).toContain("HTML");
+    expect(contract.excluded.ITJsonRenderer).toContain("Recursión");
+  });
+
+  it("las reglas mencionan las prohibiciones clave", () => {
+    const rules = contract.rules.join(" ");
+    expect(rules).toContain("i18n");
+    expect(rules).toContain("HTML");
+    expect(rules).toContain("action");
+  });
+
+  it("se serializa para el prompt con todos los componentes", () => {
+    const text = formatVocabularyForPrompt(contract);
+    expect(text).toContain("ITCard");
+    expect(text).toContain("props:");
+    expect(text.split("\n").length).toBeGreaterThan(contract.components.length);
+  });
+});

package/src/json-renderer/vocabulary/buildContract.ts

@@ -0,0 +1,158 @@
+/**
+ * Contrato de vocabulario para el emisor.
+ *
+ * Para que un modelo (o un backend) acierte con el esquema, necesita saber qué
+ * `type` existen, qué props acepta cada uno, qué valores admiten los enums y cuál
+ * es el nodo mínimo que funciona. Ese contrato **se genera desde el catálogo**,
+ * no se escribe a mano: así el prompt nunca se desincroniza del motor.
+ *
+ * Se publica como artefacto versionado (`pnpm docs:json-renderer`) y se puede
+ * entregar tal cual en el prompt del sistema.
+ */
+
+import type { Catalog, CatalogEntry, PropKind, PropSpec } from "../catalog/catalog.props";
+import { axzyCatalog } from "../catalog/axzyCatalog";
+import { CURRENT_SCHEMA_VERSION } from "../validation/validate";
+
+/** Descripción de una prop en el contrato. */
+export interface PropContract {
+  /** Nombre de la prop. */
+  name: string;
+  /** Tipo admitido. */
+  kind: PropKind;
+  /** `true` si el componente no funciona sin ella. */
+  required: boolean;
+  /** Valores admitidos en los enums. */
+  values?: string[];
+  /** Valor por defecto que aplica el motor. */
+  default?: unknown;
+  /** Nota para el emisor. */
+  doc?: string;
+}
+
+/** Descripción de un componente en el contrato. */
+export interface ComponentContract {
+  /** Tipo a emitir (`ITCard`). */
+  type: string;
+  /** Para qué sirve, en una línea. */
+  summary?: string;
+  /** `true` si admite `children`. */
+  children: boolean;
+  /** `true` si admite el atajo `text`. */
+  text: boolean;
+  /** Props permitidas. */
+  props: PropContract[];
+  /** Props prohibidas (los nodos React no viajan en JSON). */
+  forbidden: string[];
+  /** Nodo mínimo que se puede emitir y funciona. */
+  minimal: Record<string, unknown>;
+}
+
+/** Contrato completo, listo para serializar. */
+export interface VocabularyContract {
+  /** Identificador del formato. */
+  $schema: "axzy/vocabulary";
+  /** Versión del formato de pantalla al que corresponde. */
+  schemaVersion: number;
+  /** Reglas que el emisor debe respetar. */
+  rules: string[];
+  /** Componentes disponibles, ordenados por nombre. */
+  components: ComponentContract[];
+  /** Tipos excluidos y su motivo (el emisor no debe usarlos). */
+  excluded: Record<string, string>;
+}
+
+/** Reglas fijas que acompañan al contrato. */
+const RULES: string[] = [
+  "Emite SOLO JSON válido con la forma: { $schema: \"axzy/screen\", version, id, content }.",
+  "`content` es un nodo o un array de nodos; cada nodo necesita `type` del catálogo.",
+  "Usa solo props declaradas para ese `type`; el resto se ignora y se avisa.",
+  "Los hijos se expresan con `children` (nodos) y los textos con `text`, nunca con props de nodo React.",
+  "Las acciones se declaran por nombre: `\"onClick\": { \"action\": \"nombre.registrado\" }`. No hay código en el JSON.",
+  "Prohibido: HTML crudo, URLs, fetch, expresiones JS y props como icon/actions/render.",
+  "Los textos visibles deben ser claves de i18n: { \"i18n\": \"namespace.clave\" }.",
+];
+
+/** Construye el nodo mínimo que funciona para una entrada del catálogo. */
+function buildMinimal(entry: CatalogEntry): Record<string, unknown> {
+  const props: Record<string, unknown> = {};
+  for (const [name, spec] of Object.entries(entry.props ?? {})) {
+    if (!spec.required) continue;
+    props[name] = sampleValue(name, spec);
+  }
+  const node: Record<string, unknown> = { type: entry.type };
+  if (Object.keys(props).length > 0) node.props = props;
+  if (entry.text) node.text = "Texto";
+  return node;
+}
+
+/** Genera un valor de ejemplo para una prop obligatoria. */
+function sampleValue(name: string, spec: PropSpec): unknown {
+  if (spec.values?.length) return spec.values[0];
+  if (spec.kind === "number" || spec.kind === "integer") return 1;
+  if (spec.kind === "boolean") return false;
+  if (spec.kind === "i18n") return { i18n: `ejemplo.${name}` };
+  return name === "src" ? "/imagen.png" : `${name}`;
+}
+
+/** Deriva el contrato de vocabulario de un catálogo. */
+export function buildVocabularyContract(
+  catalog: Catalog = axzyCatalog,
+  schemaVersion: number = CURRENT_SCHEMA_VERSION
+): VocabularyContract {
+  const components = Object.values(catalog.entries)
+    .map<ComponentContract>((entry) => ({
+      type: entry.type,
+      summary: entry.summary,
+      children: Boolean(entry.children),
+      text: Boolean(entry.text),
+      props: Object.entries(entry.props ?? {}).map(([name, spec]) => ({
+        name,
+        kind: spec.kind,
+        required: Boolean(spec.required),
+        values: spec.values ? [...spec.values] : undefined,
+        default: spec.default,
+        doc: spec.doc,
+      })),
+      forbidden: [...(entry.forbidden ?? [])],
+      minimal: buildMinimal(entry),
+    }))
+    .sort((a, b) => a.type.localeCompare(b.type));
+
+  return {
+    $schema: "axzy/vocabulary",
+    schemaVersion,
+    rules: RULES,
+    components,
+    excluded: catalog.excluded ?? {},
+  };
+}
+
+/** Serializa el contrato como texto compacto para el prompt. */
+export function formatVocabularyForPrompt(contract: VocabularyContract): string {
+  const lines: string[] = [
+    `# Contrato de vocabulario AXZY (formato v${contract.schemaVersion})`,
+    "",
+    "Reglas:",
+    ...contract.rules.map((rule) => `- ${rule}`),
+    "",
+    "Componentes:",
+  ];
+
+  for (const component of contract.components) {
+    const props = component.props
+      .map((prop) => {
+        const parts = [`${prop.name}:${prop.kind}${prop.required ? "*" : ""}`];
+        if (prop.values?.length) parts.push(`(${prop.values.join("|")})`);
+        return parts.join(" ");
+      })
+      .join(", ");
+    lines.push(`- ${component.type}${component.summary ? ` — ${component.summary}` : ""}`);
+    if (props) lines.push(`  props: ${props}`);
+    if (component.children) lines.push("  children: sí");
+    if (component.text) lines.push("  text: sí");
+    lines.push(`  mínimo: ${JSON.stringify(component.minimal)}`);
+  }
+
+  return lines.join("\n");
+}

package/src/sandbox/AxzyLogo.tsx

@@ -0,0 +1,139 @@
+/**
+ * Marca axzydev para el sitio (sandbox + portafolio).
+ *
+ * Vive en `src/sandbox/` a propósito: es chrome del sitio, **no** un componente
+ * publicado. Los assets son los SVG del kit (`axzydev-brand-kit/logos/svg`)
+ * copiados a `public/brand/`; no hay dependencias nuevas ni animaciones Lottie.
+ *
+ * El wordmark elige su variante según el tema resuelto: `logo-color` (tinta
+ * navy sobre claro) o `logo-dark` (texto claro sobre oscuro), de modo que el
+ * logo se lee en ambos modos sin recolorear nada a mano.
+ *
+ * @example
+ * ```tsx
+ * <AxzyLogo variante="icono" tamano={24} />            // navbar / topbar
+ * <AxzyLogo variante="wordmark" tamano={260} />        // hero / footer
+ * <AxzyLogo variante="loader" tamano={40} etiqueta="Cargando" />
+ * ```
+ */
+
+import { useITThemeSafe } from "@/theme/theme-context";
+
+/** Forma del logo: solo ícono, wordmark completo o loader de marca. */
+export type AxzyLogoVariante = "icono" | "wordmark" | "loader";
+
+/** Props de `AxzyLogo`. */
+export interface AxzyLogoProps {
+  /** Forma del logo. @default "wordmark" */
+  variante?: AxzyLogoVariante;
+  /** Ancho en píxeles. El alto se calcula solo por la proporción del SVG. @default 28 (icono/loader) · 240 (wordmark) */
+  tamano?: number;
+  /** Fuerza el tono del wordmark en lugar de seguir el tema. */
+  tono?: "claro" | "oscuro";
+  /**
+   * Texto alternativo del logo. Por defecto `"axzydev"` para el wordmark y
+   * `""` (decorativo) para el ícono, que suele ir acompañado del nombre.
+   */
+  etiqueta?: string;
+  /** Clases del elemento raíz. */
+  className?: string;
+  /** Anima el ícono con un latido suave cuando `variante="loader"`. Respeta `prefers-reduced-motion`. */
+  latido?: boolean;
+}
+
+/** Ruta del asset según la forma y el tono. */
+const ASSETS: Record<AxzyLogoVariante, { claro: string; oscuro: string }> = {
+  icono: { claro: "/brand/icon.svg", oscuro: "/brand/icon.svg" },
+  wordmark: { claro: "/brand/logo-color.svg", oscuro: "/brand/logo-dark.svg" },
+  loader: { claro: "/brand/icon.svg", oscuro: "/brand/icon.svg" },
+};
+
+/** Alto por defecto según la forma (el wordmark es 621×208). */
+const ALTO_POR_TAMANO: Record<AxzyLogoVariante, number> = {
+  icono: 28,
+  wordmark: 240,
+  loader: 40,
+};
+
+/**
+ * Marca axzydev del sitio: SVG del kit, conmutada por tema y sin dependencias.
+ *
+ * @example
+ * ```tsx
+ * <AxzyLogo variante="icono" tamano={24} />
+ * <AxzyLogo variante="wordmark" tamano={260} className="mb-6" />
+ * ```
+ */
+export const AxzyLogo = ({
+  variante = "wordmark",
+  tamano,
+  tono,
+  etiqueta,
+  className = "",
+  latido = true,
+}: AxzyLogoProps) => {
+  const contexto = useITThemeSafe();
+  const modo = tono ?? (contexto?.resolvedTheme === "dark" ? "oscuro" : "claro");
+  const ancho = tamano ?? ALTO_POR_TAMANO[variante];
+
+  // El ícono mide 128×128; el wordmark, 621×208. El alto sale de la proporción.
+  const alto = variante === "icono" || variante === "loader" ? ancho : Math.round((ancho * 208) / 621);
+  const decorativo = etiqueta === "" || (etiqueta === undefined && variante !== "wordmark");
+  const alt = etiqueta ?? (variante === "wordmark" ? "axzydev" : "");
+
+  return (
+    <img
+      src={ASSETS[variante][modo]}
+      width={ancho}
+      height={alto}
+      alt={alt}
+      aria-hidden={decorativo || undefined}
+      draggable={false}
+      className={[
+        "select-none",
+        variante === "loader" && latido ? "it-logo-latido" : "",
+        className,
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      style={{ width: ancho, height: alto }}
+    />
+  );
+};
+
+/**
+ * Loader de marca: el ícono latiendo con un rótulo mono al lado.
+ *
+ * Es la versión estática del `loader` del kit (que allí es una animación Lottie)
+ * y se apoya en `ITLoader` para la etiqueta y el rol accesible.
+ *
+ * @example
+ * ```tsx
+ * <AxzyLoader etiqueta="Cargando componentes" />
+ * ```
+ */
+export const AxzyLoader = ({
+  etiqueta,
+  tamano = 32,
+  className = "",
+}: {
+  /** Texto que acompaña al ícono. */
+  etiqueta?: string;
+  /** Ancho del ícono en píxeles. @default 32 */
+  tamano?: number;
+  /** Clases del contenedor. */
+  className?: string;
+}) => (
+  <span
+    role="status"
+    aria-live="polite"
+    className={`inline-flex items-center gap-3 ${className}`}
+  >
+    <AxzyLogo variante="loader" tamano={tamano} />
+    {etiqueta ? (
+      <span className="font-mono text-[11px] uppercase tracking-[0.14em] text-slate-500 dark:text-slate-400">
+        {etiqueta}
+      </span>
+    ) : null}
+  </span>
+);

package/src/sandbox/axzyConfig.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_AXZY_CONFIG, mergeAxzyConfig } from "./axzyConfig";
+
+describe("axzy.json", () => {
+  it("sin archivo devuelve los defaults", () => {
+    expect(mergeAxzyConfig(null)).toEqual(DEFAULT_AXZY_CONFIG);
+    expect(mergeAxzyConfig(undefined)).toEqual(DEFAULT_AXZY_CONFIG);
+  });
+
+  it("acepta los valores válidos", () => {
+    const config = mergeAxzyConfig({ radius: 0, density: 1.4, shadow: 3, appearance: "flat", showFab: true });
+    expect(config.radius).toBe(0);
+    expect(config.density).toBe(1.4);
+    expect(config.shadow).toBe(3);
+    expect(config.appearance).toBe("flat");
+    expect(config.showFab).toBe(true);
+  });
+
+  it("recorta fuera de rango en vez de romper", () => {
+    const config = mergeAxzyConfig({ density: 9, radius: 99, shadow: -3 });
+    expect(config.density).toBe(1.5);
+    expect(config.radius).toBe(24);
+    expect(config.shadow).toBe(0);
+  });
+
+  it("ignora tipos raros y conserva el resto", () => {
+    const config = mergeAxzyConfig({ density: "alta", radius: null, appearance: "neón", theme: { primary: 42, danger: "#000" } });
+    expect(config.density).toBe(DEFAULT_AXZY_CONFIG.density);
+    expect(config.radius).toBe(DEFAULT_AXZY_CONFIG.radius);
+    expect(config.appearance).toBe("soft");
+    expect(config.theme).toEqual({ danger: "#000" });
+  });
+
+  it("mezcla la paleta con los defaults sin perder claves", () => {
+    const config = mergeAxzyConfig({ theme: { primary: "#111", table: { rowBg: "#fff" } } });
+    expect(config.theme.primary).toBe("#111");
+    expect(config.theme.table).toEqual({ rowBg: "#fff" });
+    expect(config.theme.danger).toBeUndefined();
+  });
+});