@axzydev/axzy_ui_system 1.7.0 → 1.7.1

package/src/json-renderer/kernel/types.ts

@@ -0,0 +1,159 @@
+/**
+ * Contrato de datos del motor de pantallas.
+ *
+ * Un esquema describe **qué** pintar; nunca **cómo** comportarse: no hay código,
+ * ni expresiones, ni URLs. Todo lo que exige autoridad (componentes, props,
+ * datos, acciones, permisos) se resuelve contra registros del host.
+ */
+
+/** Estado de un nodo respecto al stream. */
+export type NodeStatus = "complete" | "pending";
+
+/** Valor de una prop: literal, referencia a datos o texto traducible. */
+export type SchemaValue =
+  | string
+  | number
+  | boolean
+  | null
+  | SchemaValue[]
+  | { [key: string]: SchemaValue };
+
+/** Referencia declarativa a un dato. Ninguna provoca red por sí misma. */
+export interface SchemaReference {
+  /** Valor de una fuente de datos declarada en `data`. */
+  $source?: string;
+  /** Valor del estado de pantalla. */
+  $state?: string;
+  /** Parámetro de la ruta. */
+  $param?: string;
+  /** Campo de la fila actual (dentro de una tabla). */
+  $row?: string;
+  /** Campo del formulario actual (dentro de un `form`). */
+  $form?: string;
+  /** Concatenación de valores ya resueltos. */
+  $concat?: SchemaValue[];
+  /** Proyección de un array: se queda con la clave indicada. */
+  $map?: { $source?: string; $state?: string; $param?: string; pick: string };
+  /** Longitud de un array o número de claves de un objeto. */
+  $count?: SchemaValue;
+  /** Primer valor definido y no nulo. */
+  $coalesce?: SchemaValue[];
+}
+
+/** Condicional declarativo, sin lógica libre. */
+export interface WhenSchema {
+  /** Compara el valor de una fuente o del estado. */
+  state?: string;
+  /** Compara el estado de una fuente de datos. */
+  source?: string;
+  /** Igualdad estricta contra este valor. */
+  equals?: SchemaValue;
+  /** Pertenencia a esta lista. */
+  in?: SchemaValue[];
+  /** Estado de la fuente (`loading` | `empty` | `error` | `ok`). */
+  status?: "loading" | "empty" | "error" | "ok";
+  /** Capacidad del host que debe estar presente. */
+  capability?: string;
+  /** Niega la condición. */
+  not?: WhenSchema;
+  /** Todas deben cumplirse. */
+  all?: WhenSchema[];
+  /** Al menos una debe cumplirse. */
+  any?: WhenSchema[];
+}
+
+/** Efecto declarativo que ejecuta el motor tras una acción. */
+export interface EffectSchema {
+  /** Acción registrada por el host. */
+  action?: string;
+  /** Argumentos explícitos del efecto. */
+  args?: Record<string, SchemaValue>;
+  /** Aviso al usuario. */
+  toast?: { variant?: "success" | "error" | "info" | "warning"; message: SchemaValue };
+  /** Navegación a otra ruta. */
+  navigate?: string;
+  /** Abre un overlay declarado en `overlays`. */
+  openOverlay?: string;
+  /** Cierra el overlay indicado, o el que esté abierto si se omite. */
+  closeOverlay?: string;
+  /** Refresca una fuente de datos. */
+  refresh?: string;
+}
+
+/** Acción declarada en un nodo: nombre registrado + argumentos + reacciones. */
+export interface ActionSchema extends EffectSchema {
+  /** Confirmación previa obligatoria. */
+  confirm?: { title: SchemaValue; message?: SchemaValue };
+  /** Efectos que se ejecutan si la acción termina bien. */
+  then?: EffectSchema[];
+  /** Efectos que se ejecutan si la acción falla. */
+  onError?: EffectSchema;
+}
+
+/** Nodo del esquema. */
+export interface NodeSchema {
+  /** Tipo de componente del catálogo (`ITCard`, `ITButton`…) o nodo del motor (`form`, `table`). */
+  type: string;
+  /** Identificador opcional, para depuración y binding. */
+  id?: string;
+  /** Props del componente, ya filtradas por el catálogo. */
+  props?: Record<string, SchemaValue>;
+  /** Hijos: nodo, lista de nodos o nada. */
+  children?: NodeSchema | NodeSchema[];
+  /**
+   * Atajo de contenido para componentes textuales (`ITText`, `ITButton`…).
+   * Admite una referencia (`{ i18n: "clave" }`), que el host resuelve.
+   */
+  text?: SchemaValue;
+  /** Capacidad o capacidades que exige el nodo. */
+  requires?: string | string[];
+  /** Qué pintar cuando falla o no hay permiso. */
+  fallback?: NodeSchema;
+  /** Condición para pintar el nodo. */
+  when?: WhenSchema;
+  /**
+   * Estado respecto al stream. Lo rellena el parser tolerante; el autor no lo
+   * escribe.
+   */
+  $status?: NodeStatus;
+}
+
+/** Definición de una fuente de datos. El host aporta el `handler`. */
+export interface DataSourceSchema {
+  /** Nombre de un handler registrado por el host. Nunca una URL. */
+  handler: string;
+  /** Parámetros, normalmente con referencias. */
+  params?: Record<string, SchemaValue>;
+  /** Fuentes o acciones que invalidan esta fuente. */
+  refreshOn?: string[];
+}
+
+/** Esquema de pantalla completo. */
+export interface ScreenSchema {
+  /** Identificador del formato. */
+  $schema?: "axzy/screen";
+  /** Versión del formato; obligatoria para poder migrar. */
+  version: number;
+  /** Identificador de la pantalla. */
+  id: string;
+  /** Título, normalmente traducible. */
+  title?: SchemaValue;
+  /** Descripción corta de la pantalla, para la cabecera que ponga el host. */
+  description?: SchemaValue;
+  /** Capacidades que exige la pantalla completa. */
+  requires?: string | string[];
+  /** Fuentes de datos que el host resolverá. */
+  data?: Record<string, DataSourceSchema>;
+  /** Estado local de la pantalla. */
+  state?: Record<string, SchemaValue>;
+  /** Contenido raíz. */
+  content: NodeSchema | NodeSchema[];
+}
+
+/** Resultado de un intento de pintar un nodo. */
+export interface NodeOutcome {
+  /** Si el nodo se pudo resolver. */
+  ok: boolean;
+  /** Motivo cuando no se pudo. */
+  reason?: string;
+}

package/src/json-renderer/shared/errors.ts

@@ -0,0 +1,92 @@
+/**
+ * Errores y avisos del motor de pantallas declarativas.
+ *
+ * Todo lo que el motor detecta (nodo desconocido, prop prohibida, acción no
+ * registrada, permiso insuficiente…) se expresa con un **código estable** y el
+ * `path` exacto dentro del esquema. Los códigos son contrato público: están
+ * documentados en `docs/json-renderer/PLAN-IMPLEMENTACION.md` §11 y no cambian
+ * sin migración.
+ */
+
+/** Gravedad de un aviso del motor. */
+export type JsonEngineSeverity = "error" | "warning" | "info";
+
+/** Códigos de aviso del motor. Contrato estable. */
+export type JsonEngineCode =
+  | "JR010" // type fuera del catálogo
+  | "JR011" // prop prohibida o no declarada
+  | "JR012" // el componente lanzó durante el render (aislado)
+  | "JR013" // presupuesto de nodos/profundidad excedido
+  | "JR014" // el `id` del nodo no llegó al DOM (el componente no reenvía props)
+  | "JR020" // esquema inválido (estructura o versión)
+  | "JR021" // nodo inválido (forma o `type` ausente)
+  | "JR030" // fuente de datos sin handler registrado
+  | "JR031" // el esquema intenta provocar red (prohibido)
+  | "JR040" // acción no registrada
+  | "JR041" // acción excedió su timeout
+  | "JR042" // encadenado de efectos demasiado profundo
+  | "JR050" // guard de ruta inválido o que lanzó
+  | "JR060" // capacidad insuficiente para un nodo
+  | "JR061" // capacidad insuficiente para una acción
+  | "JR070" // migración de versión ausente
+  | "JR080" // stream cortado sin cerrar
+  | "JR081"; // trabajo por fragmento excedido
+
+/** Aviso del motor: lo que pasó, dónde y qué hacer. */
+export interface JsonEngineIssue {
+  /** Código estable (`JR010`…). */
+  code: JsonEngineCode;
+  /** Gravedad: `error` impide pintar el nodo, `warning` lo pinta con reservas. */
+  severity: JsonEngineSeverity;
+  /** Mensaje legible, ya traducido por el motor. */
+  message: string;
+  /** Ruta exacta dentro del esquema (`content[0].children[2].props.onClick`). */
+  path: string;
+  /** Sugerencia accionable, cuando la hay. */
+  hint?: string;
+}
+
+/** Error interno del motor: siempre lleva código y ruta. */
+export class JsonEngineError extends Error {
+  /** Código estable del catálogo de avisos. */
+  readonly code: JsonEngineCode;
+  /** Ruta del esquema donde se produjo. */
+  readonly path: string;
+  /** Sugerencia accionable. */
+  readonly hint?: string;
+
+  constructor(code: JsonEngineCode, message: string, path: string, hint?: string) {
+    super(`${code} ${path ? `en ${path}: ` : ""}${message}`);
+    this.name = "JsonEngineError";
+    this.code = code;
+    this.path = path;
+    this.hint = hint;
+  }
+
+  /** Convierte el error en el aviso que consume la interfaz y el informe. */
+  toIssue(severity: JsonEngineSeverity = "error"): JsonEngineIssue {
+    return {
+      code: this.code,
+      severity,
+      message: this.message.replace(/^JR\d{3}\s?(en .*?: )?/, ""),
+      path: this.path,
+      hint: this.hint,
+    };
+  }
+}
+
+/** Crea un aviso sin lanzar excepción (para flujos tolerantes). */
+export function issue(
+  code: JsonEngineCode,
+  message: string,
+  path = "",
+  options: { severity?: JsonEngineSeverity; hint?: string } = {}
+): JsonEngineIssue {
+  return {
+    code,
+    severity: options.severity ?? "error",
+    message,
+    path,
+    hint: options.hint,
+  };
+}

package/src/json-renderer/shared/limits.ts

@@ -0,0 +1,87 @@
+/**
+ * Presupuestos del motor.
+ *
+ * Un esquema puede venir de un modelo que alucina o de un backend con un bug: el
+ * motor no puede confiar en que el árbol sea razonable. Estos techos son la red
+ * que evita que una pantalla congele el hilo o agote la memoria.
+ */
+
+/** Techos de trabajo del motor. */
+export interface EngineLimits {
+  /** Número máximo de nodos que se pintan en una pantalla. @default 5000 */
+  maxNodes: number;
+  /** Profundidad máxima de anidación. @default 40 */
+  maxDepth: number;
+  /** Milisegundos de trabajo por fragmento de stream antes de diferir al siguiente frame. @default 8 */
+  maxMsPerChunk: number;
+  /** Milisegundos máximos de una acción antes de considerarla colgada. @default 15000 */
+  actionTimeoutMs: number;
+  /** Profundidad máxima de encadenado de efectos (`then`/`onError`). @default 5 */
+  maxEffectChain: number;
+}
+
+/** Presupuesto por defecto. */
+export const DEFAULT_LIMITS: EngineLimits = {
+  maxNodes: 5000,
+  maxDepth: 40,
+  maxMsPerChunk: 8,
+  actionTimeoutMs: 15000,
+  maxEffectChain: 5,
+};
+
+/** Resuelve un presupuesto parcial sobre los valores por defecto. */
+export function resolveLimits(overrides: Partial<EngineLimits> = {}): EngineLimits {
+  const merged: EngineLimits = { ...DEFAULT_LIMITS, ...overrides };
+  for (const [key, value] of Object.entries(merged) as [keyof EngineLimits, number][]) {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new RangeError(`Límite inválido: ${key} = ${String(value)}`);
+    }
+  }
+  return merged;
+}
+
+/** Consumidor de presupuesto: cuenta nodos y profundidad y avisa al agotarse. */
+export interface LimitTracker {
+  /** Registra un nodo en la profundidad indicada. `false` si ya no cabe. */
+  visit(depth: number): boolean;
+  /** Nodos contados hasta ahora. */
+  readonly nodes: number;
+  /** Profundidad máxima vista. */
+  readonly deepest: number;
+  /** `true` cuando se agotó el presupuesto y se recortó el árbol. */
+  readonly exceeded: boolean;
+}
+
+/**
+ * Crea un consumidor de presupuesto para un render.
+ *
+ * @example
+ * const tracker = createLimitTracker({ maxNodes: 100 });
+ * tracker.visit(0); // true
+ */
+export function createLimitTracker(limits: EngineLimits = DEFAULT_LIMITS): LimitTracker {
+  let nodes = 0;
+  let deepest = 0;
+  let exceeded = false;
+
+  return {
+    visit(depth: number) {
+      if (depth > deepest) deepest = depth;
+      if (nodes >= limits.maxNodes || depth > limits.maxDepth) {
+        exceeded = true;
+        return false;
+      }
+      nodes += 1;
+      return true;
+    },
+    get nodes() {
+      return nodes;
+    },
+    get deepest() {
+      return deepest;
+    },
+    get exceeded() {
+      return exceeded;
+    },
+  };
+}

package/src/json-renderer/shared/paths.ts

@@ -0,0 +1,66 @@
+/**
+ * Rutas dentro de un esquema.
+ *
+ * Un aviso del motor tiene que poder señalar **exactamente** dónde está el
+ * problema: `content[2].children[0].props.onClick`. Estas utilidades construyen,
+ * leen y renderizan esas rutas sin depender de nada externo.
+ */
+
+/** Un segmento de ruta: clave de objeto o índice de array. */
+export type PathSegment = string | number;
+
+/** Ruta de un nodo o valor dentro del esquema. */
+export type SchemaPath = readonly PathSegment[];
+
+/** Añade un segmento a una ruta sin mutarla. */
+export function pushPath(path: SchemaPath, segment: PathSegment): SchemaPath {
+  return [...path, segment];
+}
+
+/** Renderiza una ruta en la forma legible `content[0].children[2].props`. */
+export function formatPath(path: SchemaPath): string {
+  let out = "";
+  for (const segment of path) {
+    if (typeof segment === "number") out += `[${segment}]`;
+    else out += out ? `.${segment}` : segment;
+  }
+  return out;
+}
+
+/** Parsea una ruta renderizada (`content[0].children`) de vuelta a segmentos. */
+export function parsePath(rendered: string): PathSegment[] {
+  if (!rendered) return [];
+  return rendered
+    .split(/\.(?![^[]*])/)
+    .flatMap((part) => {
+      const match = part.match(/^([^[\]]*)((?:\[\d+\])*)$/);
+      if (!match) return [part];
+      const [, key, indexes] = match;
+      const segments: PathSegment[] = key ? [key] : [];
+      for (const index of indexes.match(/\d+/g) ?? []) segments.push(Number(index));
+      return segments;
+    });
+}
+
+/** Lee un valor del esquema siguiendo una ruta. Devuelve `undefined` si no existe. */
+export function readPath(source: unknown, path: SchemaPath): unknown {
+  let cursor: unknown = source;
+  for (const segment of path) {
+    if (cursor === null || typeof cursor !== "object") return undefined;
+    cursor = (cursor as Record<PathSegment, unknown>)[segment];
+  }
+  return cursor;
+}
+
+/** `true` cuando la ruta apunta a un valor que existe (aunque sea `null`). */
+export function hasPath(source: unknown, path: SchemaPath): boolean {
+  if (path.length === 0) return true;
+  const parent = readPath(source, path.slice(0, -1));
+  if (parent === null || typeof parent !== "object") return false;
+  return Object.prototype.hasOwnProperty.call(parent, path[path.length - 1]);
+}
+
+/** Añade el sufijo de una prop a la ruta de un nodo. */
+export function propPath(nodePath: SchemaPath, prop: string): SchemaPath {
+  return pushPath(pushPath(nodePath, "props"), prop);
+}

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

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { formatPath, hasPath, parsePath, propPath, pushPath, readPath } from "./paths";
+import { createLimitTracker, DEFAULT_LIMITS, resolveLimits } from "./limits";
+import { JsonEngineError, issue } from "./errors";
+
+describe("paths", () => {
+  it("renderiza rutas en la forma legible del contrato", () => {
+    expect(formatPath(["content", 0, "children", 2, "props"])).toBe("content[0].children[2].props");
+    expect(formatPath([])).toBe("");
+    expect(formatPath([0])).toBe("[0]");
+  });
+
+  it("parsea de vuelta a segmentos", () => {
+    expect(parsePath("content[0].children[2].props")).toEqual(["content", 0, "children", 2, "props"]);
+    expect(parsePath("")).toEqual([]);
+    expect(parsePath("version")).toEqual(["version"]);
+    expect(parsePath("a[0][1].b")).toEqual(["a", 0, 1, "b"]);
+  });
+
+  it("ida y vuelta estable", () => {
+    const segments = ["content", 1, "children", 0, "props", "onClick"] as const;
+    expect(parsePath(formatPath([...segments]))).toEqual([...segments]);
+  });
+
+  it("lee y comprueba existencia", () => {
+    const schema = { content: [{ type: "ITCard" }] };
+    expect(readPath(schema, ["content", 0, "type"])).toBe("ITCard");
+    expect(readPath(schema, ["content", 5])).toBeUndefined();
+    expect(readPath(schema, ["content", 0, "type", "x"])).toBeUndefined();
+    expect(hasPath(schema, ["content", 0, "type"])).toBe(true);
+    expect(hasPath(schema, ["content", 0, "missing"])).toBe(false);
+    expect(hasPath(schema, [])).toBe(true);
+  });
+
+  it("no muta la ruta original", () => {
+    const base = ["content"] as const;
+    expect(pushPath(base, 0)).toEqual(["content", 0]);
+    expect(base).toEqual(["content"]);
+  });
+
+  it("compone la ruta de una prop", () => {
+    expect(propPath(["content", 0], "title")).toEqual(["content", 0, "props", "title"]);
+  });
+});
+
+describe("limits", () => {
+  it("trae presupuestos por defecto razonables", () => {
+    expect(DEFAULT_LIMITS.maxNodes).toBeGreaterThan(100);
+    expect(DEFAULT_LIMITS.maxDepth).toBeGreaterThan(5);
+    expect(DEFAULT_LIMITS.maxEffectChain).toBeLessThanOrEqual(10);
+  });
+
+  it("resuelve overrides", () => {
+    expect(resolveLimits({ maxNodes: 10 }).maxNodes).toBe(10);
+    expect(resolveLimits({}).maxNodes).toBe(DEFAULT_LIMITS.maxNodes);
+  });
+
+  it("rechaza límites inválidos", () => {
+    expect(() => resolveLimits({ maxNodes: -1 })).toThrow(RangeError);
+    expect(() => resolveLimits({ maxDepth: Number.NaN })).toThrow(RangeError);
+  });
+
+  it("corta al llegar al techo de nodos", () => {
+    const tracker = createLimitTracker(resolveLimits({ maxNodes: 3 }));
+    expect(tracker.visit(0)).toBe(true);
+    expect(tracker.visit(1)).toBe(true);
+    expect(tracker.visit(1)).toBe(true);
+    expect(tracker.visit(1)).toBe(false);
+    expect(tracker.exceeded).toBe(true);
+    expect(tracker.nodes).toBe(3);
+  });
+
+  it("corta al pasar la profundidad máxima", () => {
+    const tracker = createLimitTracker(resolveLimits({ maxDepth: 2 }));
+    expect(tracker.visit(0)).toBe(true);
+    expect(tracker.visit(2)).toBe(true);
+    expect(tracker.visit(3)).toBe(false);
+    expect(tracker.exceeded).toBe(true);
+    expect(tracker.deepest).toBe(3);
+  });
+});
+
+describe("errors", () => {
+  it("el error lleva código, ruta y sugerencia", () => {
+    const error = new JsonEngineError("JR010", "tipo desconocido", "content[0]", "Revisa el catálogo");
+    expect(error.code).toBe("JR010");
+    expect(error.path).toBe("content[0]");
+    expect(error.hint).toBe("Revisa el catálogo");
+    expect(error.message).toContain("content[0]");
+    expect(error.message).toContain("tipo desconocido");
+  });
+
+  it("se convierte en aviso sin duplicar el prefijo", () => {
+    const aviso = new JsonEngineError("JR011", "prop prohibida", "content[1].props.children").toIssue("warning");
+    expect(aviso).toEqual({
+      code: "JR011",
+      severity: "warning",
+      message: "prop prohibida",
+      path: "content[1].props.children",
+      hint: undefined,
+    });
+  });
+
+  it("crea avisos sueltos con gravedad por defecto", () => {
+    expect(issue("JR080", "stream cortado").severity).toBe("error");
+    expect(issue("JR080", "stream cortado", "content", { severity: "warning" }).severity).toBe("warning");
+  });
+});

package/src/json-renderer/stream/tolerantParse.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+import { parsePartialSchema } from "./tolerantParse";
+import type { NodeSchema, ScreenSchema } from "../kernel/types";
+
+/** Esquema de ejemplo con nodos anidados: cubre objetos, arrays y literales. */
+const SCHEMA_TEXT = `{
+  "$schema": "axzy/screen",
+  "version": 1,
+  "id": "usuarios.lista",
+  "requires": "usuarios.leer",
+  "state": { "page": 1, "q": "" },
+  "data": {
+    "usuarios": { "handler": "usuarios.listar", "params": { "page": { "$state": "page" } } }
+  },
+  "content": [
+    { "type": "ITPageHeader", "props": { "title": { "i18n": "usuarios.titulo" } } },
+    {
+      "type": "ITDataTable",
+      "id": "tabla",
+      "props": {
+        "columns": [
+          { "field": "nombre", "header": { "i18n": "usuarios.nombre" }, "sortable": true },
+          { "field": "correo", "header": { "i18n": "usuarios.correo" } }
+        ],
+        "loading": false,
+        "emptyTitle": { "i18n": "usuarios.vacio" }
+      }
+    }
+  ]
+}`;
+
+/** Cuenta nodos con `$status: "pending"` en un árbol. */
+function countPending(value: unknown): number {
+  if (Array.isArray(value)) return value.reduce<number>((total, item) => total + countPending(item), 0);
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const own = record.$status === "pending" ? 1 : 0;
+    return Object.values(record).reduce<number>((total, nested) => total + countPending(nested), own);
+  }
+  return 0;
+}
+
+/** Cuenta nodos con `type` en un árbol (nodos de esquema reales). */
+function countTypedNodes(value: unknown): number {
+  if (Array.isArray(value)) return value.reduce<number>((total, item) => total + countTypedNodes(item), 0);
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const own = typeof record.type === "string" ? 1 : 0;
+    return Object.values(record).reduce<number>((total, nested) => total + countTypedNodes(nested), own);
+  }
+  return 0;
+}
+
+describe("parsePartialSchema", () => {
+  it("parsea el esquema completo y lo marca como cerrado", () => {
+    const result = parsePartialSchema(SCHEMA_TEXT);
+    expect(result.status).toBe("complete");
+    expect(result.broken).toBe(false);
+    expect(result.pendingNodes).toBe(0);
+
+    const tree = result.tree as ScreenSchema;
+    expect(tree.id).toBe("usuarios.lista");
+    expect(tree.version).toBe(1);
+    expect(Array.isArray(tree.content)).toBe(true);
+    expect((tree.content as NodeSchema[])[1].type).toBe("ITDataTable");
+  });
+
+  it("no se rompe ni lanza con texto vacío", () => {
+    const result = parsePartialSchema("");
+    expect(result.tree).toBeNull();
+    expect(result.status).toBe("pending");
+    expect(result.broken).toBe(false);
+  });
+
+  it("marca como no recuperable la basura al principio", () => {
+    const result = parsePartialSchema("@@@ no es json");
+    expect(result.broken).toBe(true);
+  });
+
+  it("trata como pendiente una cadena sin cerrar", () => {
+    const result = parsePartialSchema('{"id": "usuarios');
+    expect(result.status).toBe("pending");
+  });
+
+  it("trata como pendiente un número al final (puede seguir creciendo)", () => {
+    const result = parsePartialSchema('{"version": 1');
+    expect(result.status).toBe("pending");
+  });
+
+  it("acepta un documento completo con espacio final", () => {
+    expect(parsePartialSchema('{"version": 1}  \n').status).toBe("complete");
+  });
+
+  it("marca pendiente el nodo cuyo valor está a medias", () => {
+    const result = parsePartialSchema('{"content": [{"type": "ITCard", "props": {"title": "Ho');
+    const content = (result.tree as ScreenSchema | null)?.content as NodeSchema[] | undefined;
+    expect(result.status).toBe("pending");
+    // El nodo existe (tiene `type` cerrado) pero su prop quedó a medias.
+    expect(content?.[0]?.type).toBe("ITCard");
+  });
+
+  // ── El criterio de aceptación de la fase 0: truncar en CADA posición ──────────
+  describe("truncado exhaustivo", () => {
+    const truncations = Array.from({ length: SCHEMA_TEXT.length + 1 }, (_, index) => index);
+
+    it(`no lanza y siempre avanza en las ${truncations.length} truncaciones`, () => {
+      let previousTyped = 0;
+
+      for (const cut of truncations) {
+        const text = SCHEMA_TEXT.slice(0, cut);
+        const result = parsePartialSchema(text);
+
+        // 1. Nunca lanza y siempre devuelve un resultado coherente.
+        expect(result.offset).toBeGreaterThanOrEqual(0);
+        expect(["complete", "pending"]).toContain(result.status);
+
+        // 2. Solo el texto completo puede darse por cerrado.
+        if (cut < SCHEMA_TEXT.length) {
+          expect(result.status).toBe("pending");
+        }
+
+        // 3. El árbol no retrocede: al cortar más tarde nunca hay menos nodos.
+        const typed = result.tree ? countTypedNodes(result.tree) : 0;
+        expect(typed).toBeGreaterThanOrEqual(previousTyped);
+        previousTyped = typed;
+
+        // 4. Si hay árbol, es un objeto con la forma de un esquema.
+        if (result.tree) {
+          expect(typeof result.tree).toBe("object");
+        }
+      }
+    });
+
+    it("termina con los dos nodos de contenido y sin pendientes", () => {
+      const result = parsePartialSchema(SCHEMA_TEXT);
+      expect(countTypedNodes(result.tree)).toBe(2);
+      expect(countPending(result.tree)).toBe(0);
+    });
+
+    it("a mitad de la tabla ya ha pintado la cabecera de página", () => {
+      // Corte justo antes de cerrar el segundo nodo de `content`.
+      const cut = SCHEMA_TEXT.indexOf('"loading": false');
+      const result = parsePartialSchema(SCHEMA_TEXT.slice(0, cut));
+      const content = (result.tree as ScreenSchema | null)?.content as NodeSchema[] | undefined;
+
+      expect(result.status).toBe("pending");
+      expect(content?.[0]?.type).toBe("ITPageHeader");
+      // El segundo nodo está a medias: existe pero marcado como pendiente.
+      expect(content?.[1]?.type).toBe("ITDataTable");
+    });
+  });
+});