@saltcorn/copilot 0.7.4 → 0.8.0

package/builder-gen.js

@@ -1,33 +1,1512 @@
 const { getState } = require("@saltcorn/data/db/state");
-const WorkflowStep = require("@saltcorn/data/models/workflow_step");
-const Trigger = require("@saltcorn/data/models/trigger");
 const Table = require("@saltcorn/data/models/table");
-const { getActionConfigFields } = require("@saltcorn/data/plugin-helper");
+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 { RelationsFinder } = require("@saltcorn/common-code");
+const { RelationType } = require("@saltcorn/common-code");
 
-module.exports = {
-  run: async (prompt, mode, table) => {
-    const str = await getState().functions.llm_generate.run(
-      `Generate an HTML snippet according to the requirement below. Your snippet will be 
-placed inside a page which has loaded the Bootstrap 5 CSS framework, so you can use any 
-Bootstrap 5 classes.
-
-If you need to run javascript in script tag that depends on external reosurces, you wrap this
-in a DOMContentLoaded event handler as external javascript resources may be loaded after your HTML snippet is included.
-
-Include only the HTML snippet with no explanation before or after the code snippet.
-      
-Generate the HTML5 snippet for this request: ${prompt}
-`,
+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 EDIT_FIELDVIEW_SELECTION = `\
+For date fields always prefer fieldview "flatpickr" when available — it provides the best user experience \
+and works for both regular dates and day-only dates. \
+Only use fieldview "edit_day" as a fallback when the field has day_only=true and flatpickr is not installed. \
+For String fields that have an options attribute (a comma-separated list of fixed choices), \
+use fieldview "select" — this renders a dropdown with those options. \
+Do not use "select_by_code" for fields with fixed options.`;
+
+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").`;
+
+// ── 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.`;
+
+// ── 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 availableViews = 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)
     );
-    const strHtml = str.includes("```html")
-      ? str.split("```html")[1].split("```")[0]
-      : str;
+    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 finder = new RelationsFinder(
+            ctx.schemaData.tables,
+            ctx.schemaData.views,
+            6
+          );
+          const relations = finder.findRelations(
+            ctx.table.name,
+            resolvedView,
+            []
+          );
+          if (relations.length > 0) {
+            const picked = pickRelation(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;
+      return { ...clone, besides, list_columns: true };
+    }
+    case "list_column": {
+      const contents = normalizeChild(clone.contents, 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;
+};
+
+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.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;
+  const layout = Array.isArray(normalized) ? { above: normalized } : normalized;
+  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(
+    `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 pickRelation = (relations) => {
+  let own = null,
+    parent = null,
+    child = null;
+  for (const r of relations) {
+    if (r.type === RelationType.OWN) own = r;
+    else if (r.type === RelationType.PARENT_SHOW) parent = r;
+    else if (
+      r.type === RelationType.CHILD_LIST ||
+      r.type === RelationType.ONE_TO_ONE_SHOW
+    )
+      child = r;
+  }
+  return own || parent || child || relations[0];
+};
+
+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) => {
+    let fieldviews = Object.keys(field.type?.fieldviews || {});
+    // 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"];
+    }
+    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 {
-      type: "blank",
-      isHTML: true,
-      contents: strHtml,
-      text_strings: [],
+      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"],
+      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,
+            },
+          ],
+        },
+      },
+    ],
+  };
+};
+
+module.exports = {
+  normalizeLayoutCandidate,
+  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 llm.run(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",
@@ -35,5 +1514,7 @@ Generate the HTML5 snippet for this request: ${prompt}
     { name: "prompt", type: "String" },
     { name: "mode", type: "String" },
     { name: "table", type: "String" },
+    { name: "existing_layout", type: "JSON" },
+    { name: "chat", type: "JSON" },
   ],
 };