builder-gen.js

const { getState } = require("@saltcorn/data/db/state");
const Table = require("@saltcorn/data/models/table");
const Trigger = require("@saltcorn/data/models/trigger");
const View = require("@saltcorn/data/models/view");
const { edit_build_in_actions } = require("@saltcorn/data/viewable_fields");
const { buildBuilderSchema } = require("./builder-schema");
const { getLlmConfigurationSafe, canUseResponseFormat } = require("./common");
const { build_schema_data } = require("@saltcorn/data/plugin-helper");
const {
  GET_RELATION_PATHS_FUNCTION,
  getRelationPaths,
  getRelationPathsForPairs,
  pickBestRelation,
} = require("./relation-paths");

const ACTION_SIZES = ["btn-sm", "btn-lg"];

// ── Edit-mode guidance blocks ─────────────────────────────────────────────────

const EDIT_FIELD_INCLUSION = `\
Layout is a form for editing a single row. \
Include ALL non-primary-key, non-calculated fields from the table as inputs — \
not just fields mentioned in the task description. \
Never include calculated fields (aggregations, derived values) in an edit form — they are read-only. \
The only fields that may be omitted are FK fields to the users table that are explicitly \
designated as ownership fields (set automatically from the logged-in user). \
All other foreign key fields — including parent-context keys like trip_id — MUST appear as \
selector inputs; Saltcorn auto-fills them from the URL state when opened in context.`;

const {
  fieldview_selection_rules: EDIT_FIELDVIEW_SELECTION,
} = require("./app-constructor/fixed-prompts");

const EDIT_LAYOUT_STRUCTURE = `\
Every field MUST be preceded by a label. \
Use a blank segment with the field's label text immediately above each field inside an above array, like: \
{"above": [{"type":"blank","contents":"Field Label","class":""}, {"type":"field","field_name":"...","fieldview":"edit"}]}. \
Alternatively wrap groups of fields in a card with a descriptive title.`;

const EDIT_ACTIONS = `\
Use edit fieldviews, group related inputs, and finish with a row of actions: \
a Save button (action_name "Save", style "btn btn-primary") and \
a Cancel button (action_name "GoBack", style "btn btn-outline-secondary"). \
To add a trigger button, add an extra action segment with action_name set to the trigger's name \
exactly as it appears in the available actions list (ctx.actions).`;

// ── Show-mode guidance blocks ─────────────────────────────────────────────────

const SHOW_PURPOSE = `\
Layout displays one record read-only. \
Use show fieldviews only (e.g. "show", "as_text", "showDay").`;

const SHOW_NO_EDIT_FIELDVIEWS = `\
A show layout is read-only and must never use edit fieldviews \
(textarea, edit, input, select) — those are for form inputs, not display.`;

const SHOW_LABELS = `\
Every field MUST be preceded by a label using a blank segment or \
grouped in a card with a descriptive title.`;

// ── List-columns guidance blocks ──────────────────────────────────────────────

const LISTCOLUMNS_STRUCTURE = `\
Layout defines list columns for a list view. \
Use a list_columns wrapper with besides entries containing list_column segments. \
Each list_column has a header_label for the column heading — \
do NOT add any blank or label segment inside a list_column. \
Typically each list_column contains a single field, action, or view_link.`;

const LISTCOLUMNS_FIELDVIEWS = `\
Include all meaningful fields as columns, including foreign key fields. \
For a foreign key field use fieldview "show" so the related record's label is displayed rather than a raw ID. \
For string/text fields use fieldview "as_text" or "show" by default; \
only use "show_with_html" when the task explicitly requires rendering HTML content.`;

const LISTCOLUMNS_VIEW_LINK = `\
A view_link that opens the detail of a row MUST point to a Show-type view (viewtemplate "Show"). \
Only include such a view_link if a Show view for this table is listed in the available views. \
Every view_link requires a "relation" string — you MUST call get_relation_paths before generating the layout \
whenever the layout will contain any view_link or embedded view segment.`;

// ── Composed MODE_GUIDANCE ────────────────────────────────────────────────────

const MODE_GUIDANCE = {
  edit: [
    EDIT_FIELD_INCLUSION,
    EDIT_ACTIONS,
    EDIT_FIELDVIEW_SELECTION,
    EDIT_LAYOUT_STRUCTURE,
  ].join(" "),

  show: [SHOW_PURPOSE, SHOW_NO_EDIT_FIELDVIEWS, SHOW_LABELS].join(" "),

  list: "Layout represents a single row in a list. Highlight key fields, keep actions compact, and support filtering if requested.",

  listcolumns: [
    LISTCOLUMNS_STRUCTURE,
    LISTCOLUMNS_FIELDVIEWS,
    LISTCOLUMNS_VIEW_LINK,
  ].join(" "),

  filter:
    "Layout lets users define filters. Provide appropriate filter inputs plus an action to run or reset filters.",

  page: "Layout builds a general app page. Combine hero text, cards, containers, and call-to-action buttons.",

  default:
    "Use Saltcorn layout primitives (above, besides, container, card, tabs, blank, field, action, view_link, view). Do not return HTML snippets.",
};

const stripCodeFences = (text) => text.replace(/```(?:json)?/gi, "").trim();

const stripHtmlTags = (text) =>
  String(text || "")
    .replace(/<script[\s\S]*?<\/script>/gi, " ")
    .replace(/<style[\s\S]*?<\/style>/gi, " ")
    .replace(/<[^>]+>/g, " ")
    .replace(/\s+/g, " ")
    .trim();

const attrValue = (node, key) => {
  if (!node) return undefined;
  if (Object.prototype.hasOwnProperty.call(node, key)) return node[key];
  if (
    node.attributes &&
    Object.prototype.hasOwnProperty.call(node.attributes, key)
  )
    return node.attributes[key];
  return undefined;
};

const pickAttrValue = (node, keys) => {
  for (const key of keys) {
    const val = attrValue(node, key);
    if (val !== undefined) return val;
  }
  return undefined;
};

const firstItem = (value) => (Array.isArray(value) ? value[0] : value);

const findBalancedBlock = (text, openChar, closeChar) => {
  const start = text.indexOf(openChar);
  if (start === -1) return null;
  let depth = 0;
  let inString = false;
  let escape = false;
  for (let i = start; i < text.length; i++) {
    const ch = text[i];
    if (inString) {
      if (escape) escape = false;
      else if (ch === "\\") escape = true;
      else if (ch === '"') inString = false;
      continue;
    }
    if (ch === '"') {
      inString = true;
      continue;
    }
    if (ch === openChar) depth++;
    else if (ch === closeChar) {
      depth--;
      if (depth === 0) return text.slice(start, i + 1);
    }
  }
  return null;
};

const extractJsonStructure = (text) => {
  if (!text) return null;
  const cleaned = stripCodeFences(String(text));
  const attempt = (candidate) => {
    if (!candidate) return null;
    try {
      return JSON.parse(candidate);
    } catch (err) {
      return null;
    }
  };

  const trimmed = cleaned.trim();
  let parsed = attempt(trimmed);
  if (parsed) return parsed;

  const eqIdx = trimmed.indexOf("=");
  if (eqIdx !== -1) {
    parsed = attempt(trimmed.slice(eqIdx + 1).trim());
    if (parsed) return parsed;
  }

  const arrayBlock = findBalancedBlock(trimmed, "[", "]");
  if (arrayBlock) {
    parsed = attempt(arrayBlock);
    if (parsed) return parsed;
  }
  const objectBlock = findBalancedBlock(trimmed, "{", "}");
  if (objectBlock) {
    parsed = attempt(objectBlock);
    if (parsed) return parsed;
  }
  return null;
};

const getSchemaByRef = (root, ref) => {
  if (!ref || typeof ref !== "string" || !ref.startsWith("#/")) return null;
  const parts = ref
    .slice(2)
    .split("/")
    .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
  let current = root;
  for (const part of parts) {
    if (!current || typeof current !== "object") return null;
    current = current[part];
  }
  return current || null;
};

const validateSchemaRefs = (schema) => {
  const missing = [];
  const walk = (node) => {
    if (!node || typeof node !== "object") return;
    if (Array.isArray(node)) {
      node.forEach((item) => walk(item));
      return;
    }
    if (typeof node.$ref === "string") {
      const target = getSchemaByRef(schema, node.$ref);
      if (!target) missing.push(node.$ref);
    }
    for (const key of Object.keys(node)) walk(node[key]);
  };
  walk(schema);
  if (missing.length) {
    throw new Error(`Schema $ref targets not found: ${missing.join(", ")}`);
  }
};

const schemaHasRef = (schema) => {
  let found = false;
  const walk = (node) => {
    if (found || !node || typeof node !== "object") return;
    if (Array.isArray(node)) {
      node.forEach((item) => walk(item));
      return;
    }
    if (typeof node.$ref === "string") {
      found = true;
      return;
    }
    Object.keys(node).forEach((key) => walk(node[key]));
  };
  walk(schema);
  return found;
};

const derefSchema = (schema, maxDepth = 3) => {
  const root = JSON.parse(JSON.stringify(schema));
  const expand = (node, stack) => {
    if (!node || typeof node !== "object") return node;
    if (Array.isArray(node)) return node.map((item) => expand(item, stack));
    if (typeof node.$ref === "string") {
      if (stack.length >= maxDepth) {
        return { $ref: node.$ref };
      }
      if (stack.includes(node.$ref)) {
        return { $ref: node.$ref };
      }
      const target = getSchemaByRef(root, node.$ref);
      if (!target) throw new Error(`Schema $ref not found: ${node.$ref}`);
      return expand({ ...target }, [...stack, node.$ref]);
    }
    const out = {};
    for (const key of Object.keys(node)) {
      if (key === "$ref") continue;
      out[key] = expand(node[key], stack);
    }
    return out;
  };
  return expand(root, []);
};

const simplifySchemaForLlm = (schema) => {
  const deref = derefSchema(schema, 2); // Reduced maxDepth
  const scrub = (node, keyName, depth = 0) => {
    if (!node || typeof node !== "object" || depth > 4) {
      // Added depth limit
      if (
        keyName === "contents" ||
        keyName === "besides" ||
        keyName === "above"
      )
        return {
          type: "string",
          description: "Simplified content: a string or a basic segment.",
        };
      return node;
    }
    if (Array.isArray(node))
      return node.map((item) => scrub(item, undefined, depth + 1));
    if (keyName === "style") {
      return {
        type: "string",
        description: "CSS style string (e.g. background-color: red;).",
      };
    }
    if (typeof node.$ref === "string") {
      return {
        type: "object",
        description: "Simplified recursive segment.",
        additionalProperties: false,
      };
    }
    const out = {};
    for (const [key, val] of Object.entries(node)) {
      if (key === "$defs" || key === "definitions") continue;
      out[key] = scrub(val, key, depth + 1);
    }
    const nodeType = out.type;
    const isObjectType =
      nodeType === "object" ||
      (Array.isArray(nodeType) && nodeType.includes("object")) ||
      Object.prototype.hasOwnProperty.call(out, "properties");
    const isArrayType =
      nodeType === "array" ||
      (Array.isArray(nodeType) && nodeType.includes("array")) ||
      Object.prototype.hasOwnProperty.call(out, "items");
    const isNumberType =
      nodeType === "number" ||
      nodeType === "integer" ||
      (Array.isArray(nodeType) &&
        (nodeType.includes("number") || nodeType.includes("integer")));
    if (isObjectType) {
      out.additionalProperties = false;
    }
    if (isArrayType && typeof out.minItems !== "undefined") {
      const minItems = Number(out.minItems);
      if (Number.isFinite(minItems) && minItems > 1) out.minItems = 1;
    }
    if (isNumberType) {
      delete out.minimum;
      delete out.maximum;
      delete out.exclusiveMinimum;
      delete out.exclusiveMaximum;
      delete out.multipleOf;
    }
    return out;
  };
  return scrub(deref);
};

const countOptionalParams = (schema) => {
  let count = 0;
  const walk = (node) => {
    if (!node || typeof node !== "object") return;
    if (Array.isArray(node)) {
      node.forEach(walk);
      return;
    }
    const props = node.properties;
    if (props && typeof props === "object") {
      const required = Array.isArray(node.required) ? node.required : [];
      const optional = Object.keys(props).filter(
        (key) => !required.includes(key)
      );
      count += optional.length;
      Object.values(props).forEach(walk);
    }
    if (node.items) walk(node.items);
    if (node.anyOf) node.anyOf.forEach(walk);
    if (node.oneOf) node.oneOf.forEach(walk);
    if (node.allOf) node.allOf.forEach(walk);
  };
  walk(schema);
  return count;
};

const trimOptionalProperties = (schema, maxOptional) => {
  if (!schema || typeof schema !== "object") return schema;

  const clonedSchema = JSON.parse(JSON.stringify(schema));
  let optionalCount = countOptionalParams(clonedSchema);
  if (optionalCount <= maxOptional) {
    return clonedSchema;
  }

  const optionalPropsByNode = new Map();

  const findOptional = (node, path = []) => {
    if (!node || typeof node !== "object") return;
    if (Array.isArray(node)) {
      node.forEach((item, i) => findOptional(item, [...path, i]));
      return;
    }

    const props = node.properties;
    if (props && typeof props === "object") {
      const required = new Set(node.required || []);
      const optionalKeys = Object.keys(props).filter((k) => !required.has(k));
      if (optionalKeys.length > 0) {
        optionalPropsByNode.set(node, optionalKeys);
      }
      Object.values(props).forEach((propNode) => findOptional(propNode));
    }

    if (node.items) findOptional(node.items, [...path, "items"]);
    if (node.anyOf)
      node.anyOf.forEach((item, i) =>
        findOptional(item, [...path, "anyOf", i])
      );
    if (node.oneOf)
      node.oneOf.forEach((item, i) =>
        findOptional(item, [...path, "oneOf", i])
      );
    if (node.allOf)
      node.allOf.forEach((item, i) =>
        findOptional(item, [...path, "allOf", i])
      );
  };

  findOptional(clonedSchema);

  const nodesWithOptionals = Array.from(optionalPropsByNode.keys());
  let nodeIndex = 0;

  while (optionalCount > maxOptional && nodeIndex < nodesWithOptionals.length) {
    const node = nodesWithOptionals[nodeIndex];
    const optionalKeys = optionalPropsByNode.get(node);

    if (optionalKeys && optionalKeys.length > 0) {
      const keyToRemove = optionalKeys.pop();
      delete node.properties[keyToRemove];
      optionalCount--;
    } else {
      nodeIndex++;
    }
  }

  return clonedSchema;
};

const randomId = () =>
  Math.floor(Math.random() * 0xffffff)
    .toString(16)
    .padStart(6, "0");

const toCamelCaseStyle = (key) =>
  key.replace(/-([a-z])/g, (_m, chr) => chr.toUpperCase());

const parseStyleString = (styleStr) => {
  if (typeof styleStr !== "string") return styleStr;
  const trimmed = styleStr.trim();
  if (!trimmed) return {};
  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
    try {
      const parsed = JSON.parse(trimmed);
      return parsed && typeof parsed === "object" ? parsed : {};
    } catch (err) {
      // fall through to CSS parsing
    }
  }
  const out = {};
  trimmed.split(";").forEach((part) => {
    const section = part.trim();
    if (!section) return;
    const idx = section.indexOf(":");
    if (idx === -1) return;
    const rawKey = section.slice(0, idx).trim();
    const value = section.slice(idx + 1).trim();
    if (!rawKey || !value) return;
    if (rawKey.startsWith("--")) out[rawKey] = value;
    else out[toCamelCaseStyle(rawKey)] = value;
  });
  return out;
};

const ensureArray = (value) =>
  Array.isArray(value) ? value : value == null ? [] : [value];

const prettifyActionName = (name) =>
  (name || "")
    .replace(/_/g, " ")
    .replace(/([a-z])([A-Z])/g, "$1 $2")
    .replace(/\s+/g, " ")
    .trim();

// Picks a valid fieldview from the field's available fieldviews only.
// Never returns a fieldview that doesn't exist in field.fieldviews
const pickFieldview = (field, mode, requestedFieldview = null) => {
  const isEditMode = mode === "edit" || mode === "filter";
  const availableViews = isEditMode
    ? field?.editFieldviews || field?.fieldviews || []
    : field?.fieldviews || [];

  // If no available fieldviews, return the first one or a safe default
  if (!availableViews.length) {
    // Return the first available or fall back based on mode
    return mode === "edit" || mode === "filter" ? "edit" : "show";
  }

  // Helper to validate and return a fieldview only if it exists (exact match only)
  const validateAndReturn = (candidate) => {
    if (!candidate) return null;
    const lower = String(candidate).toLowerCase();
    return (
      availableViews.find((fv) => String(fv).toLowerCase() === lower) || null
    );
  };

  // Edit-only fieldviews must never be used in show/list modes
  const EDIT_ONLY_FIELDVIEWS = new Set(["textarea", "edit", "input", "select"]);
  const isShowMode =
    mode === "show" || mode === "list" || mode === "listcolumns";

  // For date fields in edit mode: flatpickr is always preferred (handles all date types).
  // Only fall back to edit_day when day_only=true and flatpickr is not installed.
  const fieldTypeLower = String(field?.type || "").toLowerCase();
  const isDateField =
    (mode === "edit" || mode === "filter") &&
    (fieldTypeLower === "date" || fieldTypeLower.includes("date"));
  if (isDateField) {
    const flatpickrMatch = availableViews.find(
      (fv) => String(fv).toLowerCase() === "flatpickr"
    );
    if (flatpickrMatch) return flatpickrMatch;
    if (field?.attributes?.day_only) {
      const dayMatch = availableViews.find(
        (fv) => String(fv).toLowerCase() === "edit_day"
      );
      if (dayMatch) return dayMatch;
    }
  }

  // Fields with fixed options (options attribute) always use plain select, never select_by_code
  if ((mode === "edit" || mode === "filter") && field?.attributes?.options) {
    const selectMatch = availableViews.find(
      (fv) => String(fv).toLowerCase() === "select"
    );
    if (selectMatch) return selectMatch;
  }

  // If a specific fieldview was requested by the user, try to honor it
  // but ONLY if it actually exists in available views and is appropriate for the mode
  if (requestedFieldview) {
    if (
      isShowMode &&
      EDIT_ONLY_FIELDVIEWS.has(String(requestedFieldview).toLowerCase())
    ) {
      // Fall through to show-mode defaults — don't use edit fieldviews in show context
    } else {
      const validated = validateAndReturn(requestedFieldview);
      if (validated) return validated;
      // Requested fieldview not available for this field - fall through to defaults
    }
  }

  // Get the field's configured default fieldview
  const defaultFieldview =
    field?.default_fieldview || field?.defaultFieldview || field?.fieldview;

  if (defaultFieldview) {
    const validated = validateAndReturn(defaultFieldview);
    if (validated) return validated;
  }

  // Mode-based selection from available fieldviews
  if (mode === "show" || mode === "list" || mode === "listcolumns") {
    // For show mode, prefer simple text-based views, but only from available views
    const showPreferences = ["as_text", "show", "as_string", "text", "showas"];
    for (const pref of showPreferences) {
      const match = availableViews.find(
        (fv) => String(fv).toLowerCase() === pref
      );
      if (match) return match;
    }
  } else if (mode === "edit" || mode === "filter") {
    // For edit mode, prefer edit-capable fieldviews from available views (exact match)
    const editPreferences = ["edit", "input", "select", "textarea"];
    for (const pref of editPreferences) {
      const match = availableViews.find(
        (fv) => String(fv).toLowerCase() === pref
      );
      if (match) return match;
    }
  }

  // Fall back to first available fieldview - this is always valid
  return availableViews[0];
};

const evenWidths = (count) => {
  if (!count) return [];
  const widths = Array(count).fill(Math.max(1, Math.floor(12 / count)));
  let total = widths.reduce((sum, n) => sum + n, 0);
  let idx = 0;
  while (total < 12) {
    widths[idx] += 1;
    total += 1;
    idx = (idx + 1) % count;
  }
  while (total > 12 && widths.some((w) => w > 1)) {
    if (widths[idx] > 1) {
      widths[idx] -= 1;
      total -= 1;
    }
    idx = (idx + 1) % count;
  }
  return widths;
};

const normalizeWidths = (current, count) => {
  if (!count) return [];
  if (Array.isArray(current) && current.length === count) {
    const sanitized = current.map((val) => {
      const num = Number(val);
      return Number.isFinite(num) && num > 0
        ? Math.min(12, Math.round(num))
        : null;
    });
    if (sanitized.every((n) => n && n > 0)) {
      const total = sanitized.reduce((sum, n) => sum + n, 0);
      if (total === 12) return sanitized;
    }
  }
  return evenWidths(count);
};

const parseJsonPayload = (raw) => {
  if (raw == null) throw new Error("Empty response from LLM");
  if (typeof raw === "object") return raw;
  const cleaned = stripCodeFences(String(raw));
  const extracted = extractJsonStructure(cleaned);
  if (extracted) return extracted;
  throw new Error("Could not parse JSON payload from LLM response");
};

const normalizeChild = (value, ctx) => {
  if (value == null) return null;
  if (typeof value === "string") return { type: "blank", contents: value };
  return normalizeSegment(value, ctx);
};

const normalizeTabs = (tabs, ctx) =>
  ensureArray(tabs)
    .map((tab) => ({ ...tab, contents: normalizeChild(tab?.contents, ctx) }))
    .filter((tab) => tab?.title && tab.contents)
    .map((tab) => ({ ...tab, class: tab.class || "" }));

const normalizeSegment = (segment, ctx) => {
  if (segment == null) return null;
  if (typeof segment === "string") return { type: "blank", contents: segment };
  if (Array.isArray(segment)) {
    const arr = segment
      .map((child) => normalizeSegment(child, ctx))
      .filter(Boolean);
    return arr.length ? arr : null;
  }
  if (typeof segment !== "object") return null;

  const clone = { ...segment };
  if (typeof clone.style === "string") {
    clone.style = parseStyleString(clone.style);
  }
  if (clone.type === "prompt") return null;

  if ((!clone.type || clone.type === "stack") && clone.above) {
    const above = ensureArray(clone.above)
      .map((child) => normalizeSegment(child, ctx))
      .filter(Boolean);
    return above.length ? { ...clone, above } : null;
  }
  if (!clone.type && clone.besides) {
    const besides = ensureArray(clone.besides).map((child) =>
      child == null ? null : normalizeSegment(child, ctx)
    );
    if (!besides.some((child) => child)) return null;
    return {
      ...clone,
      besides,
      widths: normalizeWidths(clone.widths, besides.length),
    };
  }
  // Handle {columns: {besides: [...], widths: [...]}} wrapper the LLM sometimes emits
  if (!clone.type && clone.columns?.besides) {
    const inner = clone.columns;
    const besides = ensureArray(inner.besides).map((child) =>
      child == null ? null : normalizeSegment(child, ctx)
    );
    if (!besides.some(Boolean)) return null;
    return {
      besides,
      widths: normalizeWidths(inner.widths, besides.length),
    };
  }

  switch (clone.type) {
    case "columns":
    case "row":
    case "grid": {
      // LLM uses these as a besides wrapper with widths
      if (clone.besides) {
        const besides = ensureArray(clone.besides).map((child) =>
          child == null ? null : normalizeSegment(child, ctx)
        );
        if (!besides.some(Boolean)) return null;
        return {
          besides,
          widths: normalizeWidths(clone.widths, besides.length),
        };
      }
      // fall through to container-like handling if no besides
      const contents = normalizeChild(clone.contents, ctx);
      return contents ? { ...clone, contents } : null;
    }
    case "container": {
      const contents = normalizeChild(clone.contents, ctx);
      return contents
        ? {
            ...clone,
            contents,
            class: clone.class || "",
            customClass: clone.customClass || "",
          }
        : null;
    }
    case "card": {
      const contents = normalizeChild(clone.contents, ctx);
      return contents
        ? {
            ...clone,
            contents,
            title: clone.title || "",
            class: clone.class || "",
          }
        : null;
    }
    case "tabs": {
      const tabs = normalizeTabs(clone.tabs, ctx);
      if (!tabs.length) return null;
      const titles = clone.titles ?? tabs.map((t) => t.title || "");
      const contents = clone.contents ?? tabs.map((t) => t.contents);
      return { ...clone, tabs, titles, contents, class: clone.class || "" };
    }
    case "blank":
      return {
        ...clone,
        contents: typeof clone.contents === "string" ? clone.contents : "",
        class: clone.class || "",
      };
    case "line_break":
      return { type: "line_break", class: clone.class || "" };
    case "image":
      return clone.url || clone.src
        ? {
            ...clone,
            url: clone.url || clone.src || "",
            alt: clone.alt || "",
            class: clone.class || "",
          }
        : null;
    case "link":
      return clone.url
        ? {
            ...clone,
            text: clone.text || clone.url,
            link_style: clone.link_style || "",
            class: clone.class || "",
          }
        : null;
    case "search_bar":
      return { ...clone, class: clone.class || "" };
    case "view":
      if (!ctx.viewNames.length) return null;
      return {
        ...clone,
        view: ctx.viewNames.includes(clone.view)
          ? clone.view
          : ctx.viewNames[0],
        state: clone.state || {},
        class: clone.class || "",
      };
    case "view_link": {
      if (!ctx.viewNames.length) return null;
      const resolvedView = ctx.viewNames.includes(clone.view)
        ? clone.view
        : ctx.viewNames[0];
      let relation = clone.relation;
      if (!relation && ctx.table && ctx.schemaData) {
        try {
          const relations = getRelationPaths(
            ctx.table.name,
            resolvedView,
            ctx.schemaData
          );
          if (relations.length > 0) {
            const picked = pickBestRelation(relations);
            if (picked) relation = picked.relationString;
          }
        } catch (e) {
          console.error("view_link relation lookup failed:", e.message);
        }
      }
      // Convert {{ expr }} template syntax to isFormula.label: true with JS expression
      let viewLabel = clone.view_label || clone.view;
      let isFormula = clone.isFormula || {};
      const tmplMatch =
        typeof viewLabel === "string" &&
        viewLabel.match(/^\{\{\s*(.+?)\s*\}\}$/);
      if (tmplMatch) {
        viewLabel = tmplMatch[1];
        isFormula = { ...isFormula, label: true };
      }
      return {
        ...clone,
        view: resolvedView,
        view_label: viewLabel,
        link_style: clone.link_style || "",
        class: clone.class || "",
        isFormula,
        ...(relation ? { relation } : {}),
      };
    }
    case "field": {
      if (!ctx.fields.length) return null;
      const fieldMeta = ctx.fieldMap[clone.field_name] || ctx.fields[0];
      // Use pickFieldview which validates that the fieldview exists in fieldMeta.fieldviews
      // If clone.fieldview is invalid, pickFieldview will return a valid alternative
      const validFieldview = pickFieldview(
        fieldMeta,
        ctx.mode,
        clone.fieldview
      );
      return {
        ...clone,
        field_name: fieldMeta.name,
        fieldview: validFieldview,
        configuration: clone.configuration || {},
        class: clone.class || "",
      };
    }
    case "list_columns": {
      const besides = ensureArray(clone.besides).map((child) =>
        child == null ? null : normalizeSegment(child, ctx)
      );
      if (!besides.some(Boolean)) return null;
      // Drop 'type' — List viewtemplate expects { besides, list_columns: true } with no type field
      const { type: _t, ...rest } = clone;
      return { ...rest, besides, list_columns: true };
    }
    case "list_column": {
      let raw = clone.contents;
      // Saltcorn's list renderer handles `above` in a cell (wraps in Container)
      // but silently drops a typeless `besides`. Convert it so both links render
      // stacked in one column rather than disappearing.
      if (raw && !raw.type && Array.isArray(raw.besides)) {
        raw = { above: raw.besides };
      }
      const contents = normalizeChild(raw, ctx);
      return contents
        ? { ...clone, contents, header_label: clone.header_label || "" }
        : null;
    }
    case "action": {
      if (!ctx.actions.length) return null;
      const actionName = ctx.actions.includes(clone.action_name)
        ? clone.action_name
        : ctx.actions[0];
      return {
        ...clone,
        action_name: actionName,
        action_label: clone.action_label || prettifyActionName(actionName),
        action_style: clone.action_style || "btn-primary",
        action_size: ACTION_SIZES.includes(clone.action_size)
          ? clone.action_size
          : undefined,
        rndid: clone.rndid || randomId(),
        minRole: clone.minRole || 100,
        nsteps: clone.nsteps || 1,
        isFormula: clone.isFormula || {},
        configuration: clone.configuration || {},
        class: clone.class || "",
      };
    }
    default: {
      if (clone.children) {
        const childSegments = ensureArray(clone.children)
          .map((child) => normalizeSegment(child, ctx))
          .filter(Boolean);
        if (childSegments.length === 1) return childSegments[0];
        if (childSegments.length > 1) return { above: childSegments };
      }
      if (clone.contents) {
        const contents = normalizeChild(clone.contents, ctx);
        return contents ? { ...clone, contents } : null;
      }
      return null;
    }
  }
};

const collectSegments = (segment, out = []) => {
  if (segment == null) return out;
  if (Array.isArray(segment)) {
    segment.forEach((s) => collectSegments(s, out));
    return out;
  }
  if (typeof segment !== "object") return out;
  out.push(segment);
  if (segment.above) collectSegments(segment.above, out);
  if (segment.besides) collectSegments(segment.besides, out);
  if (segment.contents) collectSegments(segment.contents, out);
  if (segment.tabs) {
    ensureArray(segment.tabs).forEach((tab) =>
      collectSegments(tab.contents, out)
    );
  }
  return out;
};

// margin/padding must be [top, right, bottom, left] - saltcorn-markup's
// renderer calls .every()/.map() on them and crashes on a bare string/number.
const fixBoxModel = (value) => {
  if (value == null) return undefined;
  if (Array.isArray(value))
    return value.length === 4
      ? value
      : [0, 1, 2, 3].map((i) => value[i] ?? value[0] ?? 0);
  if (typeof value === "string" || typeof value === "number")
    return [value, value, value, value];
  return undefined;
};

// Recursively fixes margin/padding shape, with no HTML stripping - used
// internally by sanitizeLayout below.
const fixLayoutBoxModel = (segment) => {
  if (segment == null) return segment;
  if (Array.isArray(segment)) return segment.map(fixLayoutBoxModel);
  if (typeof segment !== "object") return segment;

  const clone = { ...segment };
  if (clone.margin !== undefined) {
    const fixed = fixBoxModel(clone.margin);
    if (fixed) clone.margin = fixed;
    else delete clone.margin;
  }
  if (clone.padding !== undefined) {
    const fixed = fixBoxModel(clone.padding);
    if (fixed) clone.padding = fixed;
    else delete clone.padding;
  }

  if (clone.contents !== undefined)
    clone.contents = fixLayoutBoxModel(clone.contents);
  if (clone.above !== undefined) clone.above = fixLayoutBoxModel(clone.above);
  if (clone.besides !== undefined)
    clone.besides = fixLayoutBoxModel(clone.besides);
  if (clone.tabs !== undefined)
    clone.tabs = ensureArray(clone.tabs).map((tab) => ({
      ...tab,
      contents: fixLayoutBoxModel(tab?.contents),
    }));
  return clone;
};

// Pre-save fixes for callers that must not otherwise change the layout.
const sanitizeLayout = (layout) => fixLayoutBoxModel(layout);

const sanitizeNoHtmlSegments = (segment) => {
  if (segment == null) return segment;
  if (Array.isArray(segment))
    return segment
      .map((child) => sanitizeNoHtmlSegments(child))
      .filter(Boolean);
  if (typeof segment !== "object") return segment;

  const clone = { ...segment };
  if (clone.type === "blank") {
    const usedHtml = !!clone.isHTML;
    delete clone.isHTML;
    delete clone.text_strings;
    if (usedHtml && typeof clone.contents === "string") {
      clone.contents = stripHtmlTags(clone.contents);
    }
  }

  if (clone.margin !== undefined) {
    const fixed = fixBoxModel(clone.margin);
    if (fixed) clone.margin = fixed;
    else delete clone.margin;
  }
  if (clone.padding !== undefined) {
    const fixed = fixBoxModel(clone.padding);
    if (fixed) clone.padding = fixed;
    else delete clone.padding;
  }

  if (clone.contents !== undefined)
    clone.contents = sanitizeNoHtmlSegments(clone.contents);
  if (clone.above !== undefined)
    clone.above = sanitizeNoHtmlSegments(clone.above);
  if (clone.besides !== undefined)
    clone.besides = sanitizeNoHtmlSegments(clone.besides);
  if (clone.tabs !== undefined)
    clone.tabs = ensureArray(clone.tabs)
      .map((tab) => ({
        ...tab,
        contents: sanitizeNoHtmlSegments(tab?.contents),
      }))
      .filter((tab) => tab?.contents);
  return clone;
};

const truncateText = (value, maxLen) => {
  const str = String(value ?? "");
  if (str.length <= maxLen) return str;
  return `${str.slice(0, maxLen)}\n...truncated...`;
};

const normalizeLayoutCandidate = (candidate, ctx) => {
  let normalized = normalizeSegment(candidate, ctx);
  if (!normalized) {
    normalized = convertForeignLayout(candidate, ctx);
  }
  if (!normalized) return null;
  let layout = Array.isArray(normalized) ? { above: normalized } : normalized;

  // For listcolumns mode: if the LLM wrapped the list in a stack, unwrap it
  if (
    ctx.mode === "listcolumns" &&
    layout.type === "stack" &&
    Array.isArray(layout.above)
  ) {
    const listChild = layout.above.find((c) => c?.list_columns);
    if (listChild) {
      const { type: _t, ...rest } = listChild;
      layout = rest;
    }
  }

  return sanitizeNoHtmlSegments(layout);
};

const buildFieldMetadata = (fields) => {
  if (!fields || !fields.length) return null;
  const lines = fields
    .filter((f) => !f.primary_key)
    .map((f) => {
      const attrs = Object.entries(f.attributes || {})
        .filter(
          ([, v]) => v !== null && v !== undefined && v !== "" && v !== false
        )
        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
        .join(", ");
      return `  ${f.name} (${f.type}${f.calculated ? ", calculated" : ""}${
        attrs ? ` — attrs: ${attrs}` : ""
      })`;
    });
  return `Table fields available for this layout:\n${lines.join("\n")}`;
};

const buildPromptText = (userPrompt, ctx, schema) => {
  const parts = [
    `You are an expert Saltcorn layout builder assistant. Your task is to generate a layout for mode "${ctx.mode}" that precisely fulfills the user's request.`,
    'CRITICAL: You must return ONLY a single valid JSON object. Do not include introductory text, explanations, markdown formatting (like ```json), or any pseudo-markup. The output must strictly follow this shape: {"layout": <layout-object>}.',
    'The "layout" object MUST conform entirely to the provided JSON Schema. Do not invent properties, types, or structure not defined in the schema.',
  ];
  parts.push(ctx.modeGuidance);
  const fieldMeta = buildFieldMetadata(ctx.fields);
  if (fieldMeta) parts.push(fieldMeta);
  parts.push(
    "When a card or container background is requested, set bgType explicitly (None, Color, Image, or Gradient). For Color use bgColor, for Image use bgFileId plus imageLocation (Top, Card, Body) and optionally imageSize (cover, contain, repeat using cover as default) when location is Card or Body, and for Gradient use gradStartColor, gradEndColor, and numeric gradDirection. Use hex color codes when specifying colors."
  );
  parts.push(
    `Here is the strict Saltcorn layout JSON schema you MUST follow to construct the layout. Do not deviate from these definitions:\n${JSON.stringify(
      schema
    )}`
  );
  parts.push(
    `TOOL CALL REQUIRED: If the layout you are about to generate contains any view_link or embedded view (type "view") segment, ` +
      `you MUST call get_relation_paths with all required source_table/target_view pairs BEFORE returning JSON. ` +
      `Do NOT guess or omit the "relation" field — return the tool call first and use the result in the layout.`
  );
  parts.push(
    `Based on the schema above, process the following user request and generate the layout JSON. Reminder: ONLY output valid JSON starting with { and ending with }, no markdown fences.\nUser request:\n"${userPrompt}"`
  );
  return parts.join("\n\n");
};

const buildRepairPrompt = (rawOutput, schema) => {
  const cleaned = truncateText(rawOutput, 6000);
  return [
    "You are repairing a JSON payload for Saltcorn. Return ONLY valid JSON.",
    "Do not add explanations, markdown, or code fences.",
    "If the JSON is incomplete, finish it. If it has extra text, remove it.",
    `Schema (must conform):\n${JSON.stringify(schema)}`,
    `Invalid output to fix:\n${cleaned}`,
  ].join("\n\n");
};

const buildReducedPrompt = (userPrompt, ctx, schema) => {
  const limitedPrompt = `${userPrompt}\n\nLimit the layout to at most 4 containers/cards and no more than 2 levels of nesting. Keep the output compact.`;
  return buildPromptText(limitedPrompt, ctx, schema);
};

const convertChildList = (children, ctx) => {
  const segments = ensureArray(children)
    .map((child) => convertForeignLayout(child, ctx))
    .filter(Boolean);
  if (!segments.length) return null;
  if (segments.length === 1) return segments[0];
  return { above: segments };
};

const convertChildrenArray = (children, ctx) =>
  ensureArray(children)
    .map((child) => convertForeignLayout(child, ctx))
    .filter(Boolean);

const convertForeignField = (node, ctx) => {
  const fieldName = pickAttrValue(node, ["field", "field_name", "name"]);
  if (!fieldName && !ctx.fields.length) return null;
  const fieldMeta = ctx.fieldMap[fieldName] || ctx.fields[0];
  if (!fieldMeta) return null;
  let userView = pickAttrValue(node, ["fieldview", "view"]);
  const viewsAttr = attrValue(node, "views");
  if (!userView && viewsAttr !== undefined) userView = firstItem(viewsAttr);
  const typeHint = attrValue(node, "type");
  if (
    !userView &&
    typeof typeHint === "string" &&
    typeHint.toLowerCase() === "textarea"
  ) {
    userView = "textarea";
  }
  // Use pickFieldview to validate userView against field's available fieldviews
  const validFieldview = pickFieldview(fieldMeta, ctx.mode, userView);
  return {
    type: "field",
    field_name: fieldMeta.name,
    fieldview: validFieldview,
    configuration: node.configuration || {},
  };
};

const convertForeignAction = (node, ctx) => {
  const actionName =
    pickAttrValue(node, ["action", "action_name", "name"]) || ctx.actions[0];
  if (!actionName) return null;
  const style = pickAttrValue(node, ["style", "action_style"]);
  const label = pickAttrValue(node, ["label", "action_label"]);
  const size = pickAttrValue(node, ["size", "action_size"]);
  const confirm = attrValue(node, "confirm");
  return {
    type: "action",
    action_name: actionName,
    action_label: label || prettifyActionName(actionName),
    action_style: style || "btn-primary",
    action_size: ACTION_SIZES.includes(size) ? size : undefined,
    confirm,
    rndid: randomId(),
    minRole: 100,
    nsteps: 1,
    isFormula: {},
    configuration: node.configuration || {},
  };
};

const convertForeignLayout = (node, ctx) => {
  if (!node && node !== 0) return null;
  if (Array.isArray(node)) {
    const segments = node
      .map((child) => convertForeignLayout(child, ctx))
      .filter(Boolean);
    if (!segments.length) return null;
    if (segments.length === 1) return segments[0];
    return { above: segments };
  }
  if (typeof node === "string") return { type: "blank", contents: node };
  if (typeof node !== "object") return null;
  if (node.layout) return convertForeignLayout(node.layout, ctx);

  const type = node.type || node.kind;
  switch (type) {
    case "container": {
      const contents =
        convertForeignLayout(node.contents, ctx) ||
        convertChildList(node.children, ctx);
      return contents ? { type: "container", contents } : null;
    }
    case "card": {
      const contents =
        convertForeignLayout(node.contents, ctx) ||
        convertChildList(node.children, ctx);
      return contents ? { type: "card", title: node.title, contents } : null;
    }
    case "columns": {
      const columns = convertChildrenArray(node.columns || node.children, ctx);
      return columns.length
        ? {
            besides: columns,
            widths: normalizeWidths(node.widths, columns.length),
          }
        : null;
    }
    case "column":
      return (
        convertForeignLayout(node.contents, ctx) ||
        convertChildList(node.children, ctx)
      );
    case "row":
    case "section":
    case "stack":
    case "group":
    case "form":
    case "form_group":
    case "formgroup":
    case "form-row":
    case "form-group":
      return convertChildList(node.children, ctx);
    case "tabs": {
      const tabs = ensureArray(node.tabs || node.children)
        .map((tab) => ({
          title: tab.title || tab.label || "Tab",
          contents: convertForeignLayout(tab.contents || tab.children, ctx),
        }))
        .filter((tab) => tab.contents);
      return tabs.length ? { type: "tabs", tabs } : null;
    }
    case "actions":
      return convertChildList(node.children, ctx);
    case "fieldview":
    case "field":
    case "input":
    case "textarea":
    case "select":
      return convertForeignField(node, ctx);
    case "action":
    case "button":
      return convertForeignAction(node, ctx);
    case "label":
    case "heading":
    case "title":
      return {
        type: "blank",
        contents: node.text || node.value || node.contents || "",
      };
    case "text":
      return {
        type: "blank",
        contents: node.text || node.value || node.contents || "",
      };
    case "html":
      return {
        type: "blank",
        contents: stripHtmlTags(node.html || node.contents || ""),
      };
    case "image":
      return {
        type: "image",
        url: node.url || node.src || "",
        alt: node.alt || "",
      };
    default:
      if (node.children) return convertChildList(node.children, ctx);
      if (node.contents) return convertForeignLayout(node.contents, ctx);
      if (node.text) return { type: "blank", contents: node.text };
      return null;
  }
};

const splitNodeText = (text) => {
  const attrs = {};
  const body = [];
  (text || "")
    .split(/\r?\n/)
    .map((line) => line.trim())
    .filter(Boolean)
    .forEach((line) => {
      const eqIdx = line.indexOf("=");
      if (eqIdx > 0) {
        const key = line.slice(0, eqIdx).trim();
        const value = line.slice(eqIdx + 1).trim();
        if (key) attrs[key] = value;
        else body.push(line);
      } else body.push(line);
    });
  return { attrs, text: body.join(" ").trim() };
};

const buildBracketObject = (node) => {
  if (!node || !node.tag) return null;
  const children = (node.children || [])
    .map((child) => buildBracketObject(child))
    .filter(Boolean);
  const { attrs, text } = splitNodeText(node.text || "");
  const obj = { type: node.tag };
  if (children.length) obj.children = children;
  if (Object.keys(attrs).length) obj.attributes = attrs;
  if (text) obj.text = text;
  return obj;
};

const buildContext = async (mode, tableName) => {
  const normalizedMode = (mode || "show").toLowerCase();
  const ctx = {
    mode: normalizedMode,
    modeGuidance: MODE_GUIDANCE[normalizedMode] || MODE_GUIDANCE.default,
    table: null,
    fields: [],
    fieldMap: {},
    actions: [],
    viewNames: [],
    viewTableMap: {},
    schemaData: null,
  };

  // Global actions and views are useful even when no table is specified (page builder)
  const stateActions = Object.keys(getState().actions || {});
  try {
    const schemaData = await build_schema_data();
    ctx.schemaData = schemaData;
    ctx.viewNames = schemaData.views.map((v) => v.name).filter(Boolean);
    for (const v of schemaData.views) {
      if (v.name && v.table_id) {
        const vt = Table.findOne({ id: v.table_id });
        if (vt) ctx.viewTableMap[v.name] = vt.name;
      }
    }
  } catch (err) {
    ctx.viewNames = [];
    ctx.viewTableMap = {};
  }

  if (!tableName) {
    const triggers = Trigger.find({
      when_trigger: { or: ["API call", "Never"] },
    }).filter((tr) => tr.name && !tr.table_id);

    ctx.actions = Array.from(
      new Set([...stateActions, ...triggers.map((tr) => tr.name)])
    ).filter(Boolean);
    return ctx;
  }

  const lookup =
    typeof tableName === "number" || /^[0-9]+$/.test(String(tableName))
      ? { id: Number(tableName) }
      : { name: tableName };
  const table = Table.findOne(lookup);
  if (!table) return ctx;

  let rawFields = [];
  try {
    rawFields = table.getFields ? table.getFields() : table.fields || [];
  } catch (err) {
    rawFields = table.fields || [];
  }
  if (rawFields?.then) rawFields = await rawFields;
  const fields = (rawFields || []).map((field) => {
    const fvDefs = field.type?.fieldviews || {};
    let fieldviews = Object.keys(fvDefs);
    // FK fields have type "Key" (a string) so field.type?.fieldviews is empty;
    // ensure select and show are always available for them
    const typeName = field.type?.name || field.type || "";
    if (!fieldviews.length && String(typeName).startsWith("Key")) {
      fieldviews = ["select", "show"];
    }
    // File fields store their fieldviews in state.fileviews, not on the type object
    let fileFvDefs = {};
    if (String(typeName) === "File") {
      fileFvDefs = getState().fileviews || {};
      fieldviews = Object.keys(fileFvDefs);
    }
    // editFieldviews: only fieldviews where isEdit is not explicitly false
    const effectiveFvDefs = String(typeName) === "File" ? fileFvDefs : fvDefs;
    const editFieldviews = fieldviews.filter(
      (fv) => effectiveFvDefs[fv]?.isEdit !== false
    );

    const isPkName =
      table.pk_name &&
      typeof field.name === "string" &&
      field.name === table.pk_name;

    // Capture the default fieldview from various possible sources
    // Priority: field-level configured > field's attributes > type default
    const defaultFieldview =
      field.fieldview ||
      field.default_fieldview ||
      (field.attributes && field.attributes.fieldview) ||
      field.type?.default_fieldview ||
      null;

    return {
      name: field.name,
      label: field.label || field.name,
      type: field.type?.name || field.type || field.input_type || "String",
      required: !!field.required,
      primary_key: !!field.primary_key,
      calculated: !!field.calculated,
      is_pk_name: !!isPkName,
      default_fieldview: defaultFieldview,
      fieldviews: fieldviews.length ? fieldviews : ["show"],
      editFieldviews: editFieldviews.length ? editFieldviews : fieldviews,
      attributes: field.attributes || {},
    };
  });

  const triggers = Trigger.find({
    when_trigger: { or: ["API call", "Never"] },
  }).filter((tr) => tr.name && (!tr.table_id || tr.table_id === table.id));

  let viewNames = [];
  try {
    const views = await View.find_table_views_where(table.id, () => true);
    viewNames = views.map((v) => v.name);
  } catch (err) {
    viewNames = [];
  }

  const builtIns =
    ctx.mode === "edit" || ctx.mode === "filter"
      ? edit_build_in_actions || []
      : ["Delete", "GoBack"];
  const actions = Array.from(
    new Set([...builtIns, ...stateActions, ...triggers.map((tr) => tr.name)])
  ).filter(Boolean);

  ctx.table = table;
  ctx.fields = fields;
  ctx.fieldMap = Object.fromEntries(fields.map((f) => [f.name, f]));
  ctx.actions = actions;
  ctx.viewNames = viewNames;
  return ctx;
};

const buildErrorLayout = ({ message, mode, table }) => {
  const trimmedMessage = String(message || "Unknown error").slice(0, 500);
  const contextLine = table
    ? `Mode: ${mode || "show"} | Table: ${table}`
    : `Mode: ${mode || "show"}`;
  return {
    above: [
      {
        type: "container",
        customClass: "p-3 border rounded",
        style: {
          backgroundColor: "#fff3cd",
          borderColor: "#ffecb5",
          color: "#000000",
        },
        contents: {
          above: [
            {
              type: "blank",
              contents: "Builder generation failed",
              textStyle: ["h4", "fw-bold"],
              block: true,
              inline: false,
            },
            {
              type: "blank",
              contents: contextLine,
              textStyle: ["small"],
              block: true,
              inline: false,
            },
            {
              type: "blank",
              contents:
                "We could not generate a layout from your request. Please try rephrasing or simplifying the prompt.",
              block: true,
              inline: false,
            },
            {
              type: "blank",
              contents: `Error: ${trimmedMessage}`,
              textStyle: ["font-monospace", "small"],
              block: true,
              inline: false,
            },
          ],
        },
      },
    ],
  };
};

const GET_RELATION_PATHS_TOOL = {
  type: "function",
  function: GET_RELATION_PATHS_FUNCTION,
};

/**
 * Run the LLM allowing up to MAX_TOOL_ROUNDS get_relation_paths calls (depth
 * escalation: 2 → 4 → 6) before producing the final layout JSON.
 */
const MAX_TOOL_ROUNDS = 4;
const runWithRelationTools = async (llm, mainPrompt, opts) => {
  const llm_add_message = getState().functions.llm_add_message;

  const runChat = Array.isArray(opts.chat) ? [...opts.chat] : [];
  runChat.push({ role: "user", content: mainPrompt });

  // Drop response_format during tool phase; repair chain handles JSON after.
  const toolOpts = { ...opts, tools: [GET_RELATION_PATHS_TOOL] };
  delete toolOpts.response_format;
  delete toolOpts.chat;

  const schemaData = await build_schema_data();

  for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
    const raw = await llm.run(null, { ...toolOpts, chat: runChat });

    if (!raw?.hasToolCalls) {
      return typeof raw === "string" ? raw : raw?.content ?? "";
    }

    // Append the assistant message so the next round has full context.
    if (raw.ai_sdk && Array.isArray(raw.messages)) {
      raw.messages
        .filter((m) => m.role === "assistant")
        .forEach((m) => runChat.push(m));
    } else if (raw.tool_calls) {
      runChat.push({
        role: "assistant",
        content: raw.content || null,
        tool_calls: raw.tool_calls,
      });
    }

    for (const tc of raw.getToolCalls()) {
      let resultText;
      if (tc.tool_name === "get_relation_paths") {
        const maxDepth = tc.input.max_depth ?? 2;
        const sections = getRelationPathsForPairs(
          tc.input.pairs || [],
          schemaData,
          maxDepth
        );
        resultText =
          sections.join("\n\n") +
          `\n\nFor each pair above: analyse whether the listed paths include a suitable one for the intended relation type (ChildList, ParentShow, Own, etc.). ` +
          `If a suitable path exists, set the "relation" property to the chosen path string for all types including Own. ` +
          `If no suitable path exists for a pair (no paths listed, or none match the intended type), call get_relation_paths again with a higher max_depth (4, then 6). ` +
          `Do not escalate just because multiple paths are listed — only escalate when none is appropriate.`;
      } else {
        resultText = `Unknown tool: ${tc.tool_name}`;
      }
      await llm_add_message.run("tool_response", resultText, {
        chat: runChat,
        tool_call: tc,
      });
    }
  }

  // Exhausted tool rounds — force final JSON answer.
  const final = await llm.run(null, { ...opts, chat: runChat });
  return typeof final === "string" ? final : final?.content ?? "";
};

// Extracts the layout-generation prompt from the user's chat message, skipping
// tool-result-only turns. Shared by viewgen.js and pagegen.js before run().
const extractLayoutPromptFromChat = (chat, fallback = "") => {
  const extractText = (c) => {
    if (typeof c === "string") return c;
    if (Array.isArray(c)) {
      const textPart = c.find((p) => p?.type === "text" || typeof p === "string");
      return textPart?.text || (typeof textPart === "string" ? textPart : "");
    }
    return "";
  };
  const isToolResultMessage = (item) => {
    if (!Array.isArray(item?.content)) return false;
    return item.content.every((p) => p?.type === "tool_result");
  };
  const userMsgs = Array.isArray(chat)
    ? chat.filter(
        (item) =>
          item?.role === "user" && item?.content && !isToolResultMessage(item)
      )
    : [];
  const promptFromChat = userMsgs.length
    ? extractText(userMsgs[0].content)
    : "";
  return promptFromChat || fallback;
};

module.exports = {
  normalizeLayoutCandidate,
  extractLayoutPromptFromChat,
  sanitizeLayout,
  run: async (prompt, mode, table, existing_layout, chat) => {
    prompt = prompt.trim().replace(/^\[\w+\]:\s*/, "");

    const ctx = await buildContext(mode, table);
    const schema = buildBuilderSchema({ mode, ctx });
    const llm = getState().functions.llm_generate;
    if (!llm?.run) throw new Error("LLM generator not configured");

    const llmConfig = await getLlmConfigurationSafe();
    const allowResponseFormat = canUseResponseFormat(llmConfig);

    let llmPrompt = buildPromptText(prompt, ctx, schema);
    if (existing_layout !== undefined && existing_layout !== null) {
      const layoutJson =
        typeof existing_layout === "string"
          ? existing_layout
          : JSON.stringify(existing_layout);
      llmPrompt = `${llmPrompt}\n\nExisting layout (reproduce this with the requested changes applied):\n${layoutJson}`;
    }

    let responseFormat;
    try {
      if (!schema || !schema.schema) {
        throw new Error("Builder schema unavailable");
      }
      if (!allowResponseFormat) {
        console.warn("LLM backend does not support response_format; skipping");
      } else {
        validateSchemaRefs(schema.schema);
        let simplified = simplifySchemaForLlm(schema.schema);
        const optionalCount = countOptionalParams(simplified);
        console.log({ optionalCount });
        if (optionalCount > 24) {
          simplified = trimOptionalProperties(simplified, 24);
        }
        if (simplified && schemaHasRef(simplified)) {
          console.warn(
            "Builder response schema still contains $ref; skipping response_format"
          );
        } else if (simplified) {
          responseFormat = {
            type: "json_schema",
            json_schema: {
              name: "saltcorn_layout",
              schema: simplified,
            },
          };
        }
      }
    } catch (err) {
      console.warn("Builder response schema validation failed", err);
      // responseFormat = null;
    }

    const options = {};
    if (responseFormat) {
      options.response_format = responseFormat;
    }
    if (Array.isArray(chat) && chat.length) options.chat = chat;

    // const deterministicLayout = buildDeterministicLayout(ctx, prompt);

    let payload;
    let rawResponse;
    try {
      if (!schema || !schema.schema) {
        throw new Error("Builder schema unavailable");
      }
      rawResponse = await runWithRelationTools(llm, llmPrompt, options);
      payload = parseJsonPayload(rawResponse);
      const candidate = payload.layout ?? payload;
      const result = normalizeLayoutCandidate(candidate, ctx);
      if (!result) throw new Error("Empty layout after normalization");
      return result;
    } catch (err) {
      let lastError = err;
      try {
        const repairPrompt = buildRepairPrompt(rawResponse, schema);
        rawResponse = await llm.run(repairPrompt, options);
        payload = parseJsonPayload(rawResponse);
        const candidate = payload.layout ?? payload;
        const result = normalizeLayoutCandidate(candidate, ctx);
        if (!result) throw new Error("Empty layout after normalization");
        return result;
      } catch (repairErr) {
        lastError = repairErr;
      }

      try {
        const reducedPrompt = buildReducedPrompt(prompt, ctx, schema);
        rawResponse = await llm.run(reducedPrompt, options);
        payload = parseJsonPayload(rawResponse);
        const candidate = payload.layout ?? payload;
        const result = normalizeLayoutCandidate(candidate, ctx);
        if (!result) throw new Error("Empty layout after normalization");
        return result;
      } catch (reducedErr) {
        lastError = reducedErr;
      }

      console.warn("Copilot layout generation failed", lastError);
      const errorLayout = buildErrorLayout({
        message: lastError?.message || String(lastError),
        mode,
        table,
      });
      return errorLayout;
    }
  },
  isAsync: true,
  description: "Generate a builder layout",
  hidden: true,
  arguments: [
    { name: "prompt", type: "String" },
    { name: "mode", type: "String" },
    { name: "table", type: "String" },
    { name: "existing_layout", type: "JSON" },
    { name: "chat", type: "JSON" },
  ],
};