@velumo/core 0.1.0-beta.0

package/src/layout-validation.ts

@@ -0,0 +1,1385 @@
+import type { ValidationIssue } from "./types.js";
+import { describeType, issue } from "./validation-issue.js";
+
+type IndexedRecord = Record<string, unknown>;
+
+const FORBIDDEN_RENDERER_KEYS = new Set(["style", "className", "element"]);
+const RENDERER_EVENT_HANDLER_PATTERN = /^on[A-Z]/;
+const STACK_KEYS = new Set([
+  "kind",
+  "children",
+  "direction",
+  "align",
+  "gap",
+  "justify",
+  "meta",
+]);
+const GRID_KEYS = new Set(["kind", "children", "columns", "rows", "meta"]);
+const SPLIT_KEYS = new Set(["kind", "children", "weights", "meta"]);
+const HERO_KEYS = new Set(["kind", "children", "meta"]);
+const FRAME_KEYS = new Set(["kind", "children", "meta", "tone"]);
+const HEADING_KEYS = new Set([
+  "kind",
+  "text",
+  "size",
+  "level",
+  "transform",
+  "decoration",
+  "glow",
+  "tone",
+]);
+const HEADING_SIZE_VALUES = ["default", "display", "hero"] as const;
+const TEXT_KEYS = new Set([
+  "kind",
+  "text",
+  "variant",
+  "transform",
+  "decoration",
+  "glow",
+  "tone",
+]);
+const MEDIA_KEYS = new Set(["kind", "src", "alt", "fit"]);
+const CALLOUT_KEYS = new Set(["kind", "children", "tone"]);
+const LAYOUT_META_KEYS = new Set(["safeArea", "depth", "cameraHint"]);
+const SAFE_AREA_VALUES = ["default", "full-bleed", "title-safe"] as const;
+const CAMERA_HINT_VALUES = ["static", "push", "pan", "orbit"] as const;
+const STACK_DIRECTION_VALUES = ["vertical", "horizontal"] as const;
+const STACK_ALIGN_VALUES = ["start", "center", "end", "stretch"] as const;
+const STACK_JUSTIFY_VALUES = ["start", "center", "between", "end"] as const;
+const TEXT_VARIANT_VALUES = ["body", "lead", "caption"] as const;
+const TEXT_TRANSFORM_VALUES = ["uppercase", "lowercase", "capitalize"] as const;
+const TEXT_DECORATION_VALUES = ["underline", "line-through"] as const;
+const TEXT_TONE_VALUES = [
+  "default",
+  "muted",
+  "accent",
+  "danger",
+  "magenta",
+  "cyan",
+  "purple",
+  "green",
+] as const;
+const MEDIA_FIT_VALUES = ["contain", "cover", "fill"] as const;
+const CALLOUT_TONE_VALUES = [
+  "info",
+  "warning",
+  "success",
+  "danger",
+  "quote",
+] as const;
+const CANVAS_KEYS = new Set(["kind", "items", "meta"]);
+const CANVAS_ITEM_KEYS = new Set(["x", "y", "width", "height", "child"]);
+export const ANIMATION_NAME_VALUES = [
+  "rise",
+  "fade",
+  "zoom",
+  "draw",
+  "in-left",
+  "in-right",
+  "glow",
+  "blink",
+  "pulse",
+  "sweep",
+] as const;
+const ANIMATE_KEYS = new Set([
+  "kind",
+  "name",
+  "delay",
+  "duration",
+  "easing",
+  "child",
+]);
+const CODE_TOKEN_KIND_VALUES = [
+  "keyword",
+  "function",
+  "string",
+  "number",
+  "property",
+  "comment",
+  "punctuation",
+  "plain",
+] as const;
+const CODE_KEYS = new Set(["kind", "lines"]);
+const CODE_TOKEN_KEYS = new Set(["text", "kind"]);
+const ICON_KEYS = new Set(["kind", "name", "tone", "label"]);
+const ICON_NAME_VALUES = [
+  "check",
+  "cross",
+  "dash",
+  "ring",
+  "dot",
+  "arrow",
+] as const;
+const TABLE_KEYS = new Set(["kind", "columns", "rows", "meta"]);
+const TABLE_COLUMN_KEYS = new Set(["header", "weight", "align", "emphasis"]);
+const TABLE_ALIGN_VALUES = ["start", "center", "end"] as const;
+const CONNECTOR_KEYS = new Set([
+  "kind",
+  "from",
+  "to",
+  "control",
+  "arrow",
+  "dashed",
+  "tone",
+]);
+const CONNECTOR_POINT_KEYS = new Set(["x", "y"]);
+const CONNECTOR_ARROW_VALUES = ["none", "end", "start", "both"] as const;
+const BADGE_KEYS = new Set(["kind", "text", "tone", "variant", "dot", "mono"]);
+const BADGE_VARIANT_VALUES = ["outline", "soft", "solid"] as const;
+const RULE_KEYS = new Set([
+  "kind",
+  "length",
+  "thickness",
+  "tone",
+  "gradient",
+  "radius",
+]);
+const LAYOUT_KINDS =
+  "stack, grid, split, hero, frame, canvas, animate, heading, text, media, callout, code, icon, table, connector, badge, rule";
+
+function isRecord(value: unknown): value is IndexedRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isPositiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function isPercent(value: unknown): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    value >= 0 &&
+    value <= 100
+  );
+}
+
+function isAllowedString<TValue extends string>(
+  value: unknown,
+  allowed: readonly TValue[],
+): value is TValue {
+  return typeof value === "string" && allowed.includes(value as TValue);
+}
+
+function requiredIssue(path: string, message: string): ValidationIssue {
+  return issue(path, "required", message, {
+    suggestion: `Provide a value for \`${path}\`.`,
+  });
+}
+
+function typeIssue(
+  path: string,
+  message: string,
+  expected: string,
+  received: unknown,
+): ValidationIssue {
+  return issue(path, "wrong_type", message, {
+    expected,
+    received: describeType(received),
+  });
+}
+
+function enumIssue(
+  path: string,
+  message: string,
+  allowed: readonly string[],
+  received: unknown,
+): ValidationIssue {
+  return issue(path, "invalid_enum", message, {
+    expected: allowed.join(", "),
+    received: typeof received === "string" ? received : describeType(received),
+    suggestion: `Use one of: ${allowed.join(", ")}.`,
+  });
+}
+
+function valueIssue(
+  path: string,
+  message: string,
+  received: unknown,
+): ValidationIssue {
+  return issue(path, "invalid_value", message, {
+    received:
+      typeof received === "number" ? String(received) : describeType(received),
+  });
+}
+
+function validateSerializableValue(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (typeof value === "function") {
+    return [
+      issue(path, "not_serializable", `${path} must be JSON-serializable`, {
+        received: "function",
+        suggestion: "Remove functions from manifest data; it must be JSON.",
+      }),
+    ];
+  }
+
+  if (value === undefined) {
+    return [
+      issue(path, "not_serializable", `${path} must not be undefined`, {
+        received: "undefined",
+      }),
+    ];
+  }
+
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return [
+      issue(path, "not_serializable", `${path} must be a finite JSON number`, {
+        received: String(value),
+      }),
+    ];
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      issues.push(...validateSerializableValue(item, `${path}[${index}]`));
+    });
+    return issues;
+  }
+
+  if (isRecord(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      issues.push(...validateSerializableValue(child, `${path}.${key}`));
+    }
+  }
+
+  return issues;
+}
+
+function validateRendererNeutralFields(
+  node: IndexedRecord,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  for (const key of Object.keys(node)) {
+    if (
+      FORBIDDEN_RENDERER_KEYS.has(key) ||
+      RENDERER_EVENT_HANDLER_PATTERN.test(key)
+    ) {
+      issues.push(
+        issue(
+          `${path}.${key}`,
+          "renderer_specific",
+          `${path}.${key} is renderer-specific and not allowed`,
+          {
+            suggestion:
+              "Keep manifest data renderer-neutral; move renderer concerns into the renderer.",
+          },
+        ),
+      );
+    }
+  }
+
+  issues.push(...validateSerializableValue(node, path));
+
+  return issues;
+}
+
+function validateLayoutMeta(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (value === undefined) {
+    return issues;
+  }
+
+  if (!isRecord(value)) {
+    return [typeIssue(path, `${path} must be an object`, "object", value)];
+  }
+
+  for (const key of Object.keys(value)) {
+    if (!LAYOUT_META_KEYS.has(key)) {
+      issues.push(
+        issue(
+          `${path}.${key}`,
+          "unknown_field",
+          `${path}.${key} is not allowed`,
+          {
+            suggestion: `Remove \`${key}\`; allowed meta fields are safeArea, depth, cameraHint.`,
+          },
+        ),
+      );
+    }
+  }
+
+  if (
+    value.safeArea !== undefined &&
+    !isAllowedString(value.safeArea, SAFE_AREA_VALUES)
+  ) {
+    issues.push(
+      enumIssue(
+        `${path}.safeArea`,
+        `${path}.safeArea must be default, full-bleed, or title-safe`,
+        SAFE_AREA_VALUES,
+        value.safeArea,
+      ),
+    );
+  }
+
+  if (
+    value.depth !== undefined &&
+    (typeof value.depth !== "number" || !Number.isFinite(value.depth))
+  ) {
+    issues.push(
+      valueIssue(
+        `${path}.depth`,
+        `${path}.depth must be a finite JSON number`,
+        value.depth,
+      ),
+    );
+  }
+
+  if (
+    value.cameraHint !== undefined &&
+    !isAllowedString(value.cameraHint, CAMERA_HINT_VALUES)
+  ) {
+    issues.push(
+      enumIssue(
+        `${path}.cameraHint`,
+        `${path}.cameraHint must be static, push, pan, or orbit`,
+        CAMERA_HINT_VALUES,
+        value.cameraHint,
+      ),
+    );
+  }
+
+  return issues;
+}
+
+function validateLayoutChildren(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!Array.isArray(value)) {
+    return [typeIssue(path, `${path} must be an array`, "array", value)];
+  }
+
+  value.forEach((child, index) => {
+    issues.push(...validateLayoutNode(child, `${path}[${index}]`));
+  });
+
+  return issues;
+}
+
+function validateKnownFields(
+  node: IndexedRecord,
+  allowedKeys: ReadonlySet<string>,
+  path: string,
+): readonly ValidationIssue[] {
+  return Object.keys(node)
+    .filter((key) => !allowedKeys.has(key))
+    .map((key) =>
+      issue(
+        `${path}.${key}`,
+        "unknown_field",
+        `${path}.${key} is not allowed`,
+        {
+          expected: [...allowedKeys].join(", "),
+          suggestion: `Remove \`${key}\`; it is not a recognized field here.`,
+        },
+      ),
+    );
+}
+
+function validateConnectorPoint(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!isRecord(value)) {
+    return [
+      typeIssue(path, `${path} must be an object {x, y}`, "object", value),
+    ];
+  }
+  const issues: ValidationIssue[] = [];
+  for (const axis of ["x", "y"] as const) {
+    if (value[axis] === undefined) {
+      issues.push(
+        requiredIssue(`${path}.${axis}`, `${path}.${axis} is required`),
+      );
+    } else if (!isPercent(value[axis])) {
+      issues.push(
+        valueIssue(
+          `${path}.${axis}`,
+          `${path}.${axis} must be a percentage 0-100`,
+          value[axis],
+        ),
+      );
+    }
+  }
+  issues.push(...validateKnownFields(value, CONNECTOR_POINT_KEYS, path));
+  return issues;
+}
+
+function validateCanvasItems(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!Array.isArray(value)) {
+    if (value === undefined) {
+      return [requiredIssue(path, `${path} is required`)];
+    }
+    return [typeIssue(path, `${path} must be an array`, "array", value)];
+  }
+
+  const issues: ValidationIssue[] = [];
+  value.forEach((item, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!isRecord(item)) {
+      issues.push(
+        typeIssue(itemPath, `${itemPath} must be an object`, "object", item),
+      );
+      return;
+    }
+
+    issues.push(...validateKnownFields(item, CANVAS_ITEM_KEYS, itemPath));
+
+    for (const axis of ["x", "y"] as const) {
+      if (item[axis] === undefined) {
+        issues.push(
+          requiredIssue(
+            `${itemPath}.${axis}`,
+            `${itemPath}.${axis} is required`,
+          ),
+        );
+      } else if (!isPercent(item[axis])) {
+        issues.push(
+          valueIssue(
+            `${itemPath}.${axis}`,
+            `${itemPath}.${axis} must be a percentage 0-100`,
+            item[axis],
+          ),
+        );
+      }
+    }
+
+    for (const dim of ["width", "height"] as const) {
+      if (item[dim] !== undefined && !isPercent(item[dim])) {
+        issues.push(
+          valueIssue(
+            `${itemPath}.${dim}`,
+            `${itemPath}.${dim} must be a percentage 0-100`,
+            item[dim],
+          ),
+        );
+      }
+    }
+
+    if (item.child === undefined) {
+      issues.push(
+        requiredIssue(`${itemPath}.child`, `${itemPath}.child is required`),
+      );
+    } else {
+      issues.push(...validateLayoutNode(item.child, `${itemPath}.child`));
+    }
+  });
+  return issues;
+}
+
+function validateAnimate(
+  node: IndexedRecord,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  issues.push(...validateKnownFields(node, ANIMATE_KEYS, path));
+
+  if (node.name === undefined) {
+    issues.push(requiredIssue(`${path}.name`, `${path}.name is required`));
+  } else if (!isAllowedString(node.name, ANIMATION_NAME_VALUES)) {
+    issues.push(
+      enumIssue(
+        `${path}.name`,
+        `${path}.animate.name must be one of: ${ANIMATION_NAME_VALUES.join(", ")}`,
+        ANIMATION_NAME_VALUES,
+        node.name,
+      ),
+    );
+  }
+
+  if (
+    node.delay !== undefined &&
+    !(
+      typeof node.delay === "number" &&
+      Number.isFinite(node.delay) &&
+      node.delay >= 0
+    )
+  ) {
+    issues.push(
+      valueIssue(
+        `${path}.delay`,
+        `${path}.animate.delay must be a number >= 0`,
+        node.delay,
+      ),
+    );
+  }
+
+  if (
+    node.duration !== undefined &&
+    !(
+      typeof node.duration === "number" &&
+      Number.isFinite(node.duration) &&
+      node.duration > 0
+    )
+  ) {
+    issues.push(
+      valueIssue(
+        `${path}.duration`,
+        `${path}.animate.duration must be a number > 0`,
+        node.duration,
+      ),
+    );
+  }
+
+  if (node.easing !== undefined) {
+    if (typeof node.easing !== "string") {
+      issues.push(
+        typeIssue(
+          `${path}.easing`,
+          `${path}.animate.easing must be a string`,
+          "string",
+          node.easing,
+        ),
+      );
+    } else if (node.easing.trim().length === 0) {
+      issues.push(
+        requiredIssue(
+          `${path}.easing`,
+          `${path}.animate.easing must not be empty`,
+        ),
+      );
+    }
+  }
+
+  if (node.child === undefined) {
+    issues.push(
+      requiredIssue(`${path}.child`, `${path}.animate.child is required`),
+    );
+  } else {
+    issues.push(...validateLayoutNode(node.child, `${path}.child`));
+  }
+
+  return issues;
+}
+
+function validateTextStyle(
+  node: IndexedRecord,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (
+    node.transform !== undefined &&
+    !isAllowedString(node.transform, TEXT_TRANSFORM_VALUES)
+  ) {
+    issues.push(
+      enumIssue(
+        `${path}.transform`,
+        `${path}.transform must be uppercase, lowercase, or capitalize`,
+        TEXT_TRANSFORM_VALUES,
+        node.transform,
+      ),
+    );
+  }
+  if (
+    node.decoration !== undefined &&
+    !isAllowedString(node.decoration, TEXT_DECORATION_VALUES)
+  ) {
+    issues.push(
+      enumIssue(
+        `${path}.decoration`,
+        `${path}.decoration must be underline or line-through`,
+        TEXT_DECORATION_VALUES,
+        node.decoration,
+      ),
+    );
+  }
+  if (node.glow !== undefined && typeof node.glow !== "boolean") {
+    issues.push(
+      typeIssue(
+        `${path}.glow`,
+        `${path}.glow must be a boolean`,
+        "boolean",
+        node.glow,
+      ),
+    );
+  }
+  if (
+    node.tone !== undefined &&
+    !isAllowedString(node.tone, TEXT_TONE_VALUES)
+  ) {
+    issues.push(
+      enumIssue(
+        `${path}.tone`,
+        `${path}.tone must be default, muted, accent, or danger`,
+        TEXT_TONE_VALUES,
+        node.tone,
+      ),
+    );
+  }
+  return issues;
+}
+
+function validateCodeToken(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!isRecord(value)) {
+    return [typeIssue(path, `${path} must be an object`, "object", value)];
+  }
+  const issues: ValidationIssue[] = [];
+  issues.push(...validateKnownFields(value, CODE_TOKEN_KEYS, path));
+  if (typeof value.text !== "string") {
+    issues.push(
+      value.text === undefined
+        ? requiredIssue(`${path}.text`, `${path}.text is required`)
+        : typeIssue(
+            `${path}.text`,
+            `${path}.text must be a string`,
+            "string",
+            value.text,
+          ),
+    );
+  }
+  if (
+    value.kind !== undefined &&
+    !isAllowedString(value.kind, CODE_TOKEN_KIND_VALUES)
+  ) {
+    issues.push(
+      enumIssue(
+        `${path}.kind`,
+        `${path}.code token kind must be a known token kind`,
+        CODE_TOKEN_KIND_VALUES,
+        value.kind,
+      ),
+    );
+  }
+  return issues;
+}
+
+function validateCodeLines(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!Array.isArray(value)) {
+    if (value === undefined) {
+      return [requiredIssue(path, `${path} is required`)];
+    }
+    return [typeIssue(path, `${path} must be an array`, "array", value)];
+  }
+  const issues: ValidationIssue[] = [];
+  value.forEach((line, lineIndex) => {
+    const linePath = `${path}[${lineIndex}]`;
+    if (!Array.isArray(line)) {
+      issues.push(
+        typeIssue(linePath, `${linePath} must be an array`, "array", line),
+      );
+      return;
+    }
+    line.forEach((tok, tokenIndex) => {
+      issues.push(...validateCodeToken(tok, `${linePath}[${tokenIndex}]`));
+    });
+  });
+  return issues;
+}
+
+function validateTableColumns(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!Array.isArray(value)) {
+    return [typeIssue(path, `${path} must be an array`, "array", value)];
+  }
+  if (value.length === 0) {
+    return [
+      issue(path, "constraint", `${path} must contain at least one column`, {
+        suggestion: "Add a column, or use a different layout.",
+      }),
+    ];
+  }
+  const issues: ValidationIssue[] = [];
+  value.forEach((column, index) => {
+    const cPath = `${path}[${index}]`;
+    if (!isRecord(column)) {
+      issues.push(
+        typeIssue(cPath, `${cPath} must be an object`, "object", column),
+      );
+      return;
+    }
+    issues.push(...validateKnownFields(column, TABLE_COLUMN_KEYS, cPath));
+    if (column.header !== undefined) {
+      issues.push(...validateLayoutNode(column.header, `${cPath}.header`));
+    }
+    if (
+      column.weight !== undefined &&
+      (typeof column.weight !== "number" ||
+        !Number.isFinite(column.weight) ||
+        column.weight <= 0)
+    ) {
+      issues.push(
+        valueIssue(
+          `${cPath}.weight`,
+          `${cPath}.weight must be a number > 0`,
+          column.weight,
+        ),
+      );
+    }
+    if (
+      column.align !== undefined &&
+      !isAllowedString(column.align, TABLE_ALIGN_VALUES)
+    ) {
+      issues.push(
+        enumIssue(
+          `${cPath}.align`,
+          `${cPath}.align must be start, center, or end`,
+          TABLE_ALIGN_VALUES,
+          column.align,
+        ),
+      );
+    }
+    if (column.emphasis !== undefined && typeof column.emphasis !== "boolean") {
+      issues.push(
+        typeIssue(
+          `${cPath}.emphasis`,
+          `${cPath}.emphasis must be a boolean`,
+          "boolean",
+          column.emphasis,
+        ),
+      );
+    }
+  });
+  return issues;
+}
+
+function validateTableRows(
+  value: unknown,
+  columnCount: number,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!Array.isArray(value)) {
+    return [typeIssue(path, `${path} must be an array`, "array", value)];
+  }
+  const issues: ValidationIssue[] = [];
+  value.forEach((row, rowIndex) => {
+    const rPath = `${path}[${rowIndex}]`;
+    if (!Array.isArray(row)) {
+      issues.push(
+        typeIssue(rPath, `${rPath} must be an array of cells`, "array", row),
+      );
+      return;
+    }
+    if (row.length !== columnCount) {
+      issues.push(
+        issue(
+          rPath,
+          "constraint",
+          `${rPath} must have ${columnCount} cells to match the columns; got ${row.length}`,
+          { suggestion: `Provide exactly ${columnCount} cells per row.` },
+        ),
+      );
+    }
+    row.forEach((cell, cellIndex) => {
+      issues.push(...validateLayoutNode(cell, `${rPath}[${cellIndex}]`));
+    });
+  });
+  return issues;
+}
+
+export function validateLayoutNode(
+  node: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!isRecord(node)) {
+    return [typeIssue(path, `${path} must be an object`, "object", node)];
+  }
+
+  issues.push(...validateRendererNeutralFields(node, path));
+
+  switch (node.kind) {
+    case "stack":
+      issues.push(...validateKnownFields(node, STACK_KEYS, path));
+      issues.push(...validateLayoutChildren(node.children, `${path}.children`));
+      if (
+        node.direction !== undefined &&
+        !isAllowedString(node.direction, STACK_DIRECTION_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.direction`,
+            `${path}.stack.direction must be vertical or horizontal`,
+            STACK_DIRECTION_VALUES,
+            node.direction,
+          ),
+        );
+      }
+      if (
+        node.align !== undefined &&
+        !isAllowedString(node.align, STACK_ALIGN_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.align`,
+            `${path}.stack.align must be start, center, end, or stretch`,
+            STACK_ALIGN_VALUES,
+            node.align,
+          ),
+        );
+      }
+      if (
+        node.justify !== undefined &&
+        !isAllowedString(node.justify, STACK_JUSTIFY_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.justify`,
+            `${path}.stack.justify must be start, center, between, or end`,
+            STACK_JUSTIFY_VALUES,
+            node.justify,
+          ),
+        );
+      }
+      if (node.gap !== undefined && typeof node.gap !== "string") {
+        issues.push(
+          typeIssue(
+            `${path}.gap`,
+            `${path}.stack.gap must be a string`,
+            "string",
+            node.gap,
+          ),
+        );
+      }
+      issues.push(...validateLayoutMeta(node.meta, `${path}.meta`));
+      break;
+
+    case "grid":
+      issues.push(...validateKnownFields(node, GRID_KEYS, path));
+      issues.push(...validateLayoutChildren(node.children, `${path}.children`));
+      if (node.columns !== undefined && !isPositiveInteger(node.columns)) {
+        issues.push(
+          valueIssue(
+            `${path}.columns`,
+            `${path}.grid.columns must be a positive integer`,
+            node.columns,
+          ),
+        );
+      }
+      if (node.rows !== undefined && !isPositiveInteger(node.rows)) {
+        issues.push(
+          valueIssue(
+            `${path}.rows`,
+            `${path}.grid.rows must be a positive integer`,
+            node.rows,
+          ),
+        );
+      }
+      issues.push(...validateLayoutMeta(node.meta, `${path}.meta`));
+      break;
+
+    case "split":
+      issues.push(...validateKnownFields(node, SPLIT_KEYS, path));
+      issues.push(...validateLayoutChildren(node.children, `${path}.children`));
+      if (Array.isArray(node.children) && node.children.length < 2) {
+        issues.push(
+          issue(
+            `${path}.children`,
+            "constraint",
+            `${path}.split must have at least two children`,
+            { suggestion: "A split needs two or more children." },
+          ),
+        );
+      }
+      if (node.weights !== undefined) {
+        if (!Array.isArray(node.weights)) {
+          issues.push(
+            typeIssue(
+              `${path}.weights`,
+              `${path}.split.weights must be an array`,
+              "array",
+              node.weights,
+            ),
+          );
+        } else {
+          if (
+            Array.isArray(node.children) &&
+            node.weights.length !== node.children.length
+          ) {
+            issues.push(
+              issue(
+                `${path}.weights`,
+                "constraint",
+                `${path}.split.weights length must match children`,
+                {
+                  suggestion:
+                    "Provide one weight per child, or omit weights entirely.",
+                },
+              ),
+            );
+          }
+          node.weights.forEach((weight, index) => {
+            if (
+              typeof weight !== "number" ||
+              !Number.isFinite(weight) ||
+              weight <= 0
+            ) {
+              issues.push(
+                valueIssue(
+                  `${path}.weights[${index}]`,
+                  `${path}.split.weights[${index}] must be a positive number`,
+                  weight,
+                ),
+              );
+            }
+          });
+        }
+      }
+      issues.push(...validateLayoutMeta(node.meta, `${path}.meta`));
+      break;
+
+    case "hero":
+      issues.push(...validateKnownFields(node, HERO_KEYS, path));
+      issues.push(...validateLayoutChildren(node.children, `${path}.children`));
+      if (Array.isArray(node.children) && node.children.length < 1) {
+        issues.push(
+          issue(
+            `${path}.children`,
+            "constraint",
+            `${path}.hero must have one or more children`,
+            { suggestion: "Add at least one child to the hero." },
+          ),
+        );
+      }
+      issues.push(...validateLayoutMeta(node.meta, `${path}.meta`));
+      break;
+
+    case "frame":
+      issues.push(...validateKnownFields(node, FRAME_KEYS, path));
+      issues.push(...validateLayoutChildren(node.children, `${path}.children`));
+      issues.push(...validateLayoutMeta(node.meta, `${path}.meta`));
+      if (
+        node.tone !== undefined &&
+        !isAllowedString(node.tone, TEXT_TONE_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.tone`,
+            `${path}.frame.tone must be a known tone`,
+            TEXT_TONE_VALUES,
+            node.tone,
+          ),
+        );
+      }
+      break;
+
+    case "heading":
+      issues.push(...validateKnownFields(node, HEADING_KEYS, path));
+      if (!isNonEmptyString(node.text)) {
+        issues.push(
+          requiredIssue(`${path}.text`, `${path}.heading.text is required`),
+        );
+      }
+      if (
+        node.size !== undefined &&
+        !isAllowedString(node.size, HEADING_SIZE_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.size`,
+            `${path}.heading.size must be default, display, or hero`,
+            HEADING_SIZE_VALUES,
+            node.size,
+          ),
+        );
+      }
+      if (
+        node.level !== undefined &&
+        (typeof node.level !== "number" ||
+          !Number.isInteger(node.level) ||
+          node.level < 1 ||
+          node.level > 6)
+      ) {
+        issues.push(
+          valueIssue(
+            `${path}.level`,
+            `${path}.heading.level must be between 1 and 6`,
+            node.level,
+          ),
+        );
+      }
+      issues.push(...validateTextStyle(node, path));
+      break;
+
+    case "text":
+      issues.push(...validateKnownFields(node, TEXT_KEYS, path));
+      if (typeof node.text !== "string") {
+        issues.push(
+          requiredIssue(`${path}.text`, `${path}.text.text is required`),
+        );
+      }
+      if (
+        node.variant !== undefined &&
+        !isAllowedString(node.variant, TEXT_VARIANT_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.variant`,
+            `${path}.text.variant must be body, lead, or caption`,
+            TEXT_VARIANT_VALUES,
+            node.variant,
+          ),
+        );
+      }
+      issues.push(...validateTextStyle(node, path));
+      break;
+
+    case "media":
+      issues.push(...validateKnownFields(node, MEDIA_KEYS, path));
+      if (!isNonEmptyString(node.src)) {
+        issues.push(
+          requiredIssue(`${path}.src`, `${path}.media.src is required`),
+        );
+      }
+      if (!isNonEmptyString(node.alt)) {
+        issues.push(
+          requiredIssue(`${path}.alt`, `${path}.media.alt is required`),
+        );
+      }
+      if (
+        node.fit !== undefined &&
+        !isAllowedString(node.fit, MEDIA_FIT_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.fit`,
+            `${path}.media.fit must be contain, cover, or fill`,
+            MEDIA_FIT_VALUES,
+            node.fit,
+          ),
+        );
+      }
+      break;
+
+    case "callout":
+      issues.push(...validateKnownFields(node, CALLOUT_KEYS, path));
+      issues.push(...validateLayoutChildren(node.children, `${path}.children`));
+      if (
+        node.tone !== undefined &&
+        !isAllowedString(node.tone, CALLOUT_TONE_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.tone`,
+            `${path}.callout.tone must be info, warning, success, danger, or quote`,
+            CALLOUT_TONE_VALUES,
+            node.tone,
+          ),
+        );
+      }
+      break;
+
+    case "canvas":
+      issues.push(...validateKnownFields(node, CANVAS_KEYS, path));
+      issues.push(...validateCanvasItems(node.items, `${path}.items`));
+      issues.push(...validateLayoutMeta(node.meta, `${path}.meta`));
+      break;
+
+    case "animate":
+      issues.push(...validateAnimate(node, path));
+      break;
+
+    case "code":
+      issues.push(...validateKnownFields(node, CODE_KEYS, path));
+      issues.push(...validateCodeLines(node.lines, `${path}.lines`));
+      break;
+
+    case "icon":
+      issues.push(...validateKnownFields(node, ICON_KEYS, path));
+      if (!isAllowedString(node.name, ICON_NAME_VALUES)) {
+        issues.push(
+          node.name === undefined
+            ? requiredIssue(`${path}.name`, `${path}.icon.name is required`)
+            : enumIssue(
+                `${path}.name`,
+                `${path}.icon.name must be one of: ${ICON_NAME_VALUES.join(", ")}`,
+                ICON_NAME_VALUES,
+                node.name,
+              ),
+        );
+      }
+      if (
+        node.tone !== undefined &&
+        !isAllowedString(node.tone, TEXT_TONE_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.tone`,
+            `${path}.icon.tone must be a known tone`,
+            TEXT_TONE_VALUES,
+            node.tone,
+          ),
+        );
+      }
+      if (node.label !== undefined && typeof node.label !== "string") {
+        issues.push(
+          typeIssue(
+            `${path}.label`,
+            `${path}.icon.label must be a string`,
+            "string",
+            node.label,
+          ),
+        );
+      }
+      break;
+
+    case "badge":
+      issues.push(...validateKnownFields(node, BADGE_KEYS, path));
+      if (typeof node.text !== "string") {
+        issues.push(
+          node.text === undefined
+            ? requiredIssue(`${path}.text`, `${path}.badge.text is required`)
+            : typeIssue(
+                `${path}.text`,
+                `${path}.badge.text must be a string`,
+                "string",
+                node.text,
+              ),
+        );
+      }
+      if (
+        node.tone !== undefined &&
+        !isAllowedString(node.tone, TEXT_TONE_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.tone`,
+            `${path}.badge.tone must be a known tone`,
+            TEXT_TONE_VALUES,
+            node.tone,
+          ),
+        );
+      }
+      if (
+        node.dot !== undefined &&
+        !isAllowedString(node.dot, TEXT_TONE_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.dot`,
+            `${path}.badge.dot must be a known tone`,
+            TEXT_TONE_VALUES,
+            node.dot,
+          ),
+        );
+      }
+      if (
+        node.variant !== undefined &&
+        !isAllowedString(node.variant, BADGE_VARIANT_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.variant`,
+            `${path}.badge.variant must be outline, soft, or solid`,
+            BADGE_VARIANT_VALUES,
+            node.variant,
+          ),
+        );
+      }
+      if (node.mono !== undefined && typeof node.mono !== "boolean") {
+        issues.push(
+          typeIssue(
+            `${path}.mono`,
+            `${path}.badge.mono must be a boolean`,
+            "boolean",
+            node.mono,
+          ),
+        );
+      }
+      break;
+
+    case "rule":
+      issues.push(...validateKnownFields(node, RULE_KEYS, path));
+      if (
+        node.length !== undefined &&
+        typeof node.length !== "string" &&
+        typeof node.length !== "number"
+      ) {
+        issues.push(
+          typeIssue(
+            `${path}.length`,
+            `${path}.rule.length must be a string or number`,
+            "string | number",
+            node.length,
+          ),
+        );
+      }
+      if (node.thickness !== undefined && typeof node.thickness !== "number") {
+        issues.push(
+          typeIssue(
+            `${path}.thickness`,
+            `${path}.rule.thickness must be a number`,
+            "number",
+            node.thickness,
+          ),
+        );
+      }
+      if (node.radius !== undefined && typeof node.radius !== "number") {
+        issues.push(
+          typeIssue(
+            `${path}.radius`,
+            `${path}.rule.radius must be a number`,
+            "number",
+            node.radius,
+          ),
+        );
+      }
+      if (
+        node.tone !== undefined &&
+        !isAllowedString(node.tone, TEXT_TONE_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.tone`,
+            `${path}.rule.tone must be a known tone`,
+            TEXT_TONE_VALUES,
+            node.tone,
+          ),
+        );
+      }
+      if (node.gradient !== undefined) {
+        if (!Array.isArray(node.gradient)) {
+          issues.push(
+            typeIssue(
+              `${path}.gradient`,
+              `${path}.rule.gradient must be an array of two tones`,
+              "array",
+              node.gradient,
+            ),
+          );
+        } else {
+          if (node.gradient.length !== 2) {
+            issues.push(
+              issue(
+                `${path}.gradient`,
+                "constraint",
+                `${path}.rule.gradient must contain exactly two tones`,
+                {
+                  suggestion: "Provide exactly two tone names.",
+                },
+              ),
+            );
+          }
+          node.gradient.forEach((stop: unknown, i: number) => {
+            if (!isAllowedString(stop, TEXT_TONE_VALUES)) {
+              issues.push(
+                enumIssue(
+                  `${path}.gradient[${i}]`,
+                  `${path}.rule.gradient[${i}] must be a known tone`,
+                  TEXT_TONE_VALUES,
+                  stop,
+                ),
+              );
+            }
+          });
+        }
+      }
+      break;
+
+    case "table": {
+      issues.push(...validateKnownFields(node, TABLE_KEYS, path));
+      issues.push(...validateTableColumns(node.columns, `${path}.columns`));
+      const columnCount = Array.isArray(node.columns) ? node.columns.length : 0;
+      issues.push(...validateTableRows(node.rows, columnCount, `${path}.rows`));
+      issues.push(...validateLayoutMeta(node.meta, `${path}.meta`));
+      break;
+    }
+
+    case "connector":
+      issues.push(...validateKnownFields(node, CONNECTOR_KEYS, path));
+      if (node.from === undefined) {
+        issues.push(
+          requiredIssue(`${path}.from`, `${path}.connector.from is required`),
+        );
+      } else {
+        issues.push(...validateConnectorPoint(node.from, `${path}.from`));
+      }
+      if (node.to === undefined) {
+        issues.push(
+          requiredIssue(`${path}.to`, `${path}.connector.to is required`),
+        );
+      } else {
+        issues.push(...validateConnectorPoint(node.to, `${path}.to`));
+      }
+      if (node.control !== undefined) {
+        issues.push(...validateConnectorPoint(node.control, `${path}.control`));
+      }
+      if (
+        node.arrow !== undefined &&
+        !isAllowedString(node.arrow, CONNECTOR_ARROW_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.arrow`,
+            `${path}.connector.arrow must be none, end, start, or both`,
+            CONNECTOR_ARROW_VALUES,
+            node.arrow,
+          ),
+        );
+      }
+      if (node.dashed !== undefined && typeof node.dashed !== "boolean") {
+        issues.push(
+          typeIssue(
+            `${path}.dashed`,
+            `${path}.connector.dashed must be a boolean`,
+            "boolean",
+            node.dashed,
+          ),
+        );
+      }
+      if (
+        node.tone !== undefined &&
+        !isAllowedString(node.tone, TEXT_TONE_VALUES)
+      ) {
+        issues.push(
+          enumIssue(
+            `${path}.tone`,
+            `${path}.connector.tone must be a known tone`,
+            TEXT_TONE_VALUES,
+            node.tone,
+          ),
+        );
+      }
+      break;
+
+    default:
+      issues.push(
+        issue(
+          `${path}.kind`,
+          "unknown_kind",
+          `${path}.kind must be a known layout or content kind`,
+          {
+            expected: LAYOUT_KINDS,
+            received:
+              typeof node.kind === "string"
+                ? node.kind
+                : describeType(node.kind),
+            suggestion: `Use one of the supported kinds: ${LAYOUT_KINDS}.`,
+          },
+        ),
+      );
+      break;
+  }
+
+  return issues;
+}