form0-core 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -8,7 +8,7 @@
   "main": "src/index.js",
   "type": "module",
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/builtin-metadata.test.js && node tests/calculation-editor.test.js && node tests/security-test.js",
+    "test": "node tests/form0-core.test.js && node tests/builtin-metadata.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/security-test.js",
     "postinstall": "node scripts/postinstall.cjs",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,json,ts,tsx,md}\""

package/src/builtins/control/setresult.js

@@ -22,7 +22,7 @@ export const SETRESULT_METADATA = defineBuiltinMetadata({
   signature: 'SETRESULT(value)',
   description: 'Set the final return value for multiline calculations.',
   examples: ['SETRESULT($price * $quantity)'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION],
 });
 
 export const SETRESULT = (value) => {

package/src/builtins/event/control/off.js

@@ -1,5 +1,6 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
 import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
+import { isValidEventType } from '../../../engine/event-registry.js';
 
 /**
  * OFF builtin for form events
@@ -37,6 +38,16 @@ export const OFF_METADATA = defineBuiltinMetadata({
 });
 
 export function OFF(eventType, fieldKeyOrCallback, callback) {
+  if (typeof eventType !== 'string' || eventType.trim().length === 0) {
+    console.warn('[form0] OFF() requires a non-empty event type string');
+    return null;
+  }
+
+  if (!isValidEventType(eventType)) {
+    console.warn(`[form0] OFF() received an unknown event type: ${eventType}`);
+    return null;
+  }
+
   let fieldKey = '*';
   let actualCallback = undefined;
 

package/src/builtins/event/control/on.js

@@ -1,5 +1,6 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
 import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
+import { isValidEventType } from '../../../engine/event-registry.js';
 
 /**
  * ON builtin for form events
@@ -29,6 +30,16 @@ export const ON_METADATA = defineBuiltinMetadata({
 });
 
 export function ON(eventType, fieldKeyOrCallback, callback) {
+  if (typeof eventType !== 'string' || eventType.trim().length === 0) {
+    console.warn('[form0] ON() requires a non-empty event type string');
+    return null;
+  }
+
+  if (!isValidEventType(eventType)) {
+    console.warn(`[form0] ON() received an unknown event type: ${eventType}`);
+    return null;
+  }
+
   let fieldKey = '*';
   let actualCallback = fieldKeyOrCallback;
 
@@ -38,6 +49,11 @@ export function ON(eventType, fieldKeyOrCallback, callback) {
     actualCallback = callback;
   }
 
+  if (typeof actualCallback !== 'function') {
+    console.warn('[form0] ON() requires a callback function');
+    return null;
+  }
+
   // Create operation descriptor
   const operation = {
     type: 'EVENT_OPERATION',

package/src/builtins/registry.js

@@ -65,7 +65,7 @@ export { ON, ON_METADATA } from './event/control/on.js';
 export { OFF, OFF_METADATA } from './event/control/off.js';
 export { __consumeEventOperations } from './event/event-operations-collector.js';
 
-const CALCULATION_AND_EVENT_ENTRIES = Object.freeze([
+const COMMON_RUNTIME_ENTRIES = Object.freeze([
   { implementation: IF, definition: IF_METADATA },
   { implementation: AND, definition: AND_METADATA },
   { implementation: OR, definition: OR_METADATA },
@@ -73,7 +73,6 @@ const CALCULATION_AND_EVENT_ENTRIES = Object.freeze([
   { implementation: COUNTA, definition: COUNTA_METADATA },
   { implementation: COUNTBLANK, definition: COUNTBLANK_METADATA },
   { implementation: ARRAY, definition: ARRAY_METADATA },
-  { implementation: SETRESULT, definition: SETRESULT_METADATA },
   { implementation: EVAL, definition: EVAL_METADATA },
   { implementation: CHOICEVALUE, definition: CHOICEVALUE_METADATA },
   { implementation: CHOICELABEL, definition: CHOICELABEL_METADATA },
@@ -91,6 +90,10 @@ const CALCULATION_AND_EVENT_ENTRIES = Object.freeze([
   { implementation: UPPER, definition: UPPER_METADATA },
 ]);
 
+const CALCULATION_ONLY_ENTRIES = Object.freeze([
+  { implementation: SETRESULT, definition: SETRESULT_METADATA },
+]);
+
 const EVENT_ONLY_ENTRIES = Object.freeze([
   { implementation: ALERT, definition: ALERT_METADATA },
   { implementation: SETVALUE, definition: SETVALUE_METADATA },
@@ -110,12 +113,23 @@ function filterDefinitionsByContext(definitions, context) {
   return Object.freeze(definitions.filter((definition) => definition.contexts.includes(context)));
 }
 
-export const builtins = buildBuiltinObject(CALCULATION_AND_EVENT_ENTRIES);
+export const calculationBuiltins = buildBuiltinObject([
+  ...COMMON_RUNTIME_ENTRIES,
+  ...CALCULATION_ONLY_ENTRIES,
+]);
+
+export const eventBuiltins = buildBuiltinObject([
+  ...COMMON_RUNTIME_ENTRIES,
+  ...EVENT_ONLY_ENTRIES,
+]);
 
-export const eventBuiltins = buildBuiltinObject(EVENT_ONLY_ENTRIES);
+// Backward-compatible alias for calculation runtime helpers.
+export const builtins = calculationBuiltins;
 
 export const BUILTIN_DEFINITIONS = Object.freeze(
-  [...CALCULATION_AND_EVENT_ENTRIES, ...EVENT_ONLY_ENTRIES].map(({ definition }) => definition)
+  [...COMMON_RUNTIME_ENTRIES, ...CALCULATION_ONLY_ENTRIES, ...EVENT_ONLY_ENTRIES].map(
+    ({ definition }) => definition
+  )
 );
 
 export const CALCULATION_BUILTIN_DEFINITIONS = filterDefinitionsByContext(

package/src/engine/form-engine.js

@@ -3,7 +3,7 @@ import { evaluateVisibility } from './conditions.js';
 import { evaluateRequirement } from './conditions.js';
 import { evaluateReadOnly } from './conditions.js';
 import { validateFields } from './field-validation.js';
-import { builtins, eventBuiltins } from '../builtins/registry.js';
+import { calculationBuiltins, eventBuiltins } from '../builtins/registry.js';
 import { validateSchema } from '../schema/schema-validator.js';
 import { flattenFields } from '../utilities/field-helpers.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
@@ -90,7 +90,7 @@ export function createFormEngine({
   const required = {};
   const read_only = {};
 
-  const allHelpers = { ...builtins, ...helpers };
+  const allHelpers = { ...calculationBuiltins, ...helpers };
 
   // Initialize context resolution system
   const contextResolver = new ContextResolver(form);
@@ -99,7 +99,7 @@ export function createFormEngine({
   // Initialize event system with context resolution
   const eventManager = new EventManager(form, contextResolver, sharedWarningSystem);
   eventManager.securityConfig = security; // Pass security config
-  const eventHelpers = { ...builtins, ...eventBuiltins, ...helpers };
+  const eventHelpers = { ...eventBuiltins, ...helpers };
 
   // Initialize event code if present
   if (form.events && form.events.code) {

package/src/index.js

@@ -35,8 +35,14 @@ export {
   getCalculationBuiltinCatalog,
   getCalculationReferenceCatalog,
   analyzeCalculationExpression,
+  createCalculationPreviewSession,
   simulateCalculationExpression,
 } from './utilities/calculation-editor.js';
+export {
+  getFormEventBuiltinCatalog,
+  getFormEventReferenceCatalog,
+  analyzeFormEventCode,
+} from './utilities/form-event-editor.js';
 export {
   getFormAIMetadata,
   getFormAIContext,

package/src/security/validation.js

@@ -1,16 +1,15 @@
-import { builtins, eventBuiltins } from '../builtins/registry.js';
+import { calculationBuiltins, eventBuiltins } from '../builtins/registry.js';
 import { DEFAULT_SECURITY_CONFIG, SAFE_SECURITY_CONFIG, SECURITY_MODES } from './config.js';
 
 // Helper function to validate builtin function names in expressions
 function validateBuiltinNames(expr, includeEventBuiltins = false) {
   // Always use fresh builtin sets (no caching) to support dynamic builtin registration
-  const validBuiltinsSet = new Set(Object.keys(builtins));
+  const validCalculationBuiltinsSet = new Set(Object.keys(calculationBuiltins));
   const validEventBuiltinsSet = new Set(Object.keys(eventBuiltins));
 
-  // Combine regular and event builtins if in event context
   const allowedBuiltins = includeEventBuiltins
-    ? new Set([...validBuiltinsSet, ...validEventBuiltinsSet])
-    : validBuiltinsSet;
+    ? validEventBuiltinsSet
+    : validCalculationBuiltinsSet;
 
   // Extract function calls from the expression
   // This regex matches function calls like FUNCTIONNAME( allowing for whitespace
@@ -46,8 +45,8 @@ function validateBuiltinNames(expr, includeEventBuiltins = false) {
     }
 
     // Check for potential typos by finding similar builtin names
-    const validBuiltins = [...allowedBuiltins]; // Convert back to array for filtering
-    const similarBuiltins = validBuiltins.filter((builtin) => {
+    const validBuiltinNames = [...allowedBuiltins];
+    const similarBuiltins = validBuiltinNames.filter((builtin) => {
       // Simple similarity check - same length or very close
       const lengthDiff = Math.abs(builtin.length - functionName.length);
       return lengthDiff <= 2 && builtin.startsWith(functionName.substring(0, 3));

package/src/utilities/calculation-editor.js

@@ -296,6 +296,33 @@ function sanitizeCollectedWarnings(warnings) {
   }));
 }
 
+function clearRecord(record) {
+  if (!record || typeof record !== 'object') {
+    return;
+  }
+
+  Object.keys(record).forEach((key) => {
+    delete record[key];
+  });
+}
+
+function resetEngineValues(targetValues, sourceValues) {
+  clearRecord(targetValues);
+  Object.assign(targetValues, deepClone(sourceValues));
+}
+
+function normalizeSimulationValues(values) {
+  return values && typeof values === 'object' && !Array.isArray(values) ? values : {};
+}
+
+function createSimulationErrorResult(runtimeError, warnings = []) {
+  return {
+    result: null,
+    runtimeError,
+    warnings,
+  };
+}
+
 /**
  * @typedef {'stable' | 'advanced' | 'unavailable'} CalculationBuiltinStatus
  *
@@ -615,30 +642,34 @@ export function analyzeCalculationExpression({
 }
 
 /**
- * Simulate a CalculatedField expression against form0-core's real evaluation engine.
+ * Create a reusable preview session for CalculatedField authoring.
  *
  * @param {Object} options
  * @param {Object} options.schema
  * @param {string} options.fieldDataName
  * @param {string} options.expression
- * @param {Object} [options.values]
  * @param {Object} [options.security]
  * @returns {{
- *   result: unknown,
- *   runtimeError: string | null,
- *   warnings: Array<{
- *     message: string,
- *     suggestion: string | null,
- *     context: Object | null,
- *     fieldContext: Object | null,
- *   }>,
+ *   run: (options?: {
+ *     expression?: string,
+ *     values?: Object,
+ *   }) => {
+ *     result: unknown,
+ *     runtimeError: string | null,
+ *     warnings: Array<{
+ *       message: string,
+ *       suggestion: string | null,
+ *       context: Object | null,
+ *       fieldContext: Object | null,
+ *     }>,
+ *   },
+ *   dispose: () => void,
  * }}
  */
-export function simulateCalculationExpression({
+export function createCalculationPreviewSession({
   schema,
   fieldDataName,
   expression,
-  values = {},
   security = DEFAULT_SECURITY_CONFIG,
 }) {
   const simulationSchema = cloneSimulationSchema(schema);
@@ -647,17 +678,19 @@ export function simulateCalculationExpression({
 
   if (!targetField) {
     return {
-      result: null,
-      runtimeError: `Field '${fieldDataName}' does not exist in the form schema.`,
-      warnings: [],
+      run: () =>
+        createSimulationErrorResult(
+          `Field '${fieldDataName}' does not exist in the form schema.`
+        ),
+      dispose: () => {},
     };
   }
 
   if (targetField.type !== 'CalculatedField') {
     return {
-      result: null,
-      runtimeError: `Field '${fieldDataName}' is not a CalculatedField.`,
-      warnings: [],
+      run: () =>
+        createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
+      dispose: () => {},
     };
   }
 
@@ -666,41 +699,113 @@ export function simulateCalculationExpression({
   const warningSystem = new WarningSystem({
     enableCollection: true,
     enableConsoleWarnings: false,
+    throttleMs: 0,
   });
   const runtimeDiagnostics = [];
+  const engine = createFormEngine({
+    schema: simulationSchema,
+    initialValues: {},
+    security,
+    warningSystem,
+    runtimeDiagnostics,
+  });
 
-  try {
-    const engine = createFormEngine({
-      schema: simulationSchema,
-      initialValues:
-        values && typeof values === 'object' && !Array.isArray(values) ? values : {},
-      security,
-      warningSystem,
-      runtimeDiagnostics,
-    });
+  engine.eval();
 
-    engine.eval();
+  const engineState = engine.getState();
+  const baselineValues = deepClone(engineState.values);
+  let currentExpression = targetField.calculate;
+  let disposed = false;
 
-    const engineState = engine.getState();
-    const simulatedResult = engineState.values[fieldDataName];
-    const runtimeError =
-      runtimeDiagnostics.find((diagnostic) => diagnostic.fieldName === fieldDataName)?.message ||
-      runtimeDiagnostics[0]?.message ||
-      null;
+  return {
+    run: ({ expression: nextExpression, values = {} } = {}) => {
+      if (disposed) {
+        return createSimulationErrorResult('Calculation preview session has been disposed.');
+      }
 
-    return {
-      result: simulatedResult === undefined ? null : simulatedResult,
-      runtimeError,
-      warnings: sanitizeCollectedWarnings(warningSystem.getCollectedWarnings()),
-    };
-  } catch (error) {
-    return {
-      result: null,
-      runtimeError:
-        error instanceof Error && error.message
-          ? error.message
-          : 'Unknown calculation simulation error.',
-      warnings: sanitizeCollectedWarnings(warningSystem.getCollectedWarnings()),
-    };
+      warningSystem.clearCollectedWarnings();
+      runtimeDiagnostics.length = 0;
+
+      if (typeof nextExpression === 'string' && nextExpression !== currentExpression) {
+        targetField.calculate = nextExpression;
+        currentExpression = nextExpression;
+      }
+
+      resetEngineValues(engineState.values, baselineValues);
+      Object.assign(engineState.values, normalizeSimulationValues(values));
+
+      try {
+        engine.eval();
+
+        const simulatedResult = engineState.values[fieldDataName];
+        const runtimeError =
+          runtimeDiagnostics.find((diagnostic) => diagnostic.fieldName === fieldDataName)
+            ?.message ||
+          runtimeDiagnostics[0]?.message ||
+          null;
+
+        return {
+          result: simulatedResult === undefined ? null : simulatedResult,
+          runtimeError,
+          warnings: sanitizeCollectedWarnings(warningSystem.getCollectedWarnings()),
+        };
+      } catch (error) {
+        return createSimulationErrorResult(
+          error instanceof Error && error.message
+            ? error.message
+            : 'Unknown calculation simulation error.',
+          sanitizeCollectedWarnings(warningSystem.getCollectedWarnings())
+        );
+      }
+    },
+    dispose: () => {
+      disposed = true;
+      warningSystem.clearCollectedWarnings();
+      runtimeDiagnostics.length = 0;
+      clearRecord(engineState.values);
+    },
+  };
+}
+
+/**
+ * Simulate a CalculatedField expression against form0-core's real evaluation engine.
+ *
+ * @param {Object} options
+ * @param {Object} options.schema
+ * @param {string} options.fieldDataName
+ * @param {string} options.expression
+ * @param {Object} [options.values]
+ * @param {Object} [options.security]
+ * @returns {{
+ *   result: unknown,
+ *   runtimeError: string | null,
+ *   warnings: Array<{
+ *     message: string,
+ *     suggestion: string | null,
+ *     context: Object | null,
+ *     fieldContext: Object | null,
+ *   }>,
+ * }}
+ */
+export function simulateCalculationExpression({
+  schema,
+  fieldDataName,
+  expression,
+  values = {},
+  security = DEFAULT_SECURITY_CONFIG,
+}) {
+  const session = createCalculationPreviewSession({
+    schema,
+    fieldDataName,
+    expression,
+    security,
+  });
+  try {
+    return session.run({
+      expression,
+      values,
+    });
+  } finally {
+    session.dispose();
   }
 }

package/src/utilities/form-event-editor.js

@@ -0,0 +1,488 @@
+import { BUILTIN_CONTEXTS } from '../builtins/builtin-metadata.js';
+import { BUILTIN_DEFINITION_BY_NAME, EVENT_BUILTIN_DEFINITIONS } from '../builtins/registry.js';
+import { ContextResolver } from '../engine/context-resolver.js';
+import { getAllEventTypes } from '../engine/event-registry.js';
+import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
+import { validateExpression } from '../security/validation.js';
+import { flattenFields } from './field-helpers.js';
+
+const COMMON_GLOBAL_FUNCTIONS = new Set([
+  'Math',
+  'Date',
+  'JSON',
+  'Number',
+  'String',
+  'Array',
+  'Object',
+  'Boolean',
+]);
+
+const STRUCTURAL_FIELD_TYPES = new Set([
+  'Section',
+  'RepeatableSection',
+  'BuildingPlanSection',
+]);
+
+const FORM_EVENT_BUILTIN_STATUS_BY_NAME = Object.freeze({
+  EVAL: 'advanced',
+  FORM: 'unavailable',
+});
+
+function getFormEventBuiltinStatus(name) {
+  return FORM_EVENT_BUILTIN_STATUS_BY_NAME[name] ?? 'stable';
+}
+
+function toFormEventBuiltinDefinition(definition) {
+  return Object.freeze({
+    name: definition.name,
+    category: definition.category,
+    signature: definition.signature,
+    description: definition.description,
+    examples: Object.freeze([...definition.examples]),
+    status: getFormEventBuiltinStatus(definition.name),
+  });
+}
+
+const FORM_EVENT_BUILTIN_CATALOG = Object.freeze(
+  EVENT_BUILTIN_DEFINITIONS.map(toFormEventBuiltinDefinition)
+);
+
+const FORM_EVENT_BUILTIN_METADATA_BY_NAME = new Map(
+  FORM_EVENT_BUILTIN_CATALOG.map((definition) => [definition.name, definition])
+);
+
+function normalizeFormSchema(schema) {
+  if (schema && Array.isArray(schema.elements)) {
+    return schema;
+  }
+
+  if (schema && schema.form && Array.isArray(schema.form.elements)) {
+    return schema.form;
+  }
+
+  throw new Error('Expected a form schema or a root schema containing form.elements');
+}
+
+function isBuiltinCallMatchAllowed(functionName) {
+  return COMMON_GLOBAL_FUNCTIONS.has(functionName);
+}
+
+function removeEvalContents(code) {
+  let result = '';
+  let i = 0;
+
+  while (i < code.length) {
+    const evalMatch = code.substring(i).match(/^EVAL\s*\(/);
+    if (evalMatch) {
+      result += 'EVAL()';
+      i += evalMatch[0].length;
+
+      let parenCount = 1;
+      let inSingleQuote = false;
+      let inDoubleQuote = false;
+      let inBacktick = false;
+
+      while (i < code.length && parenCount > 0) {
+        const char = code[i];
+
+        if (char === "'" && !inDoubleQuote && !inBacktick) {
+          inSingleQuote = !inSingleQuote;
+        } else if (char === '"' && !inSingleQuote && !inBacktick) {
+          inDoubleQuote = !inDoubleQuote;
+        } else if (char === '`' && !inSingleQuote && !inDoubleQuote) {
+          inBacktick = !inBacktick;
+        }
+
+        if (!inSingleQuote && !inDoubleQuote && !inBacktick) {
+          if (char === '(') {
+            parenCount++;
+          } else if (char === ')') {
+            parenCount--;
+          }
+        }
+
+        i++;
+      }
+    } else {
+      result += code[i];
+      i++;
+    }
+  }
+
+  return result;
+}
+
+function extractFunctionCalls(code) {
+  const functionCallPattern = /\b([A-Z_][A-Z0-9_]*)\s*\(/g;
+  const matches = [];
+  let match;
+
+  while ((match = functionCallPattern.exec(code)) !== null) {
+    matches.push({
+      name: match[1],
+      index: match.index,
+      length: match[1].length,
+    });
+  }
+
+  return matches;
+}
+
+function extractFieldReferenceMatches(code) {
+  const cleanedCode = removeEvalContents(code);
+  const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
+  const matches = [];
+  let match;
+
+  while ((match = fieldRegex.exec(cleanedCode)) !== null) {
+    matches.push({
+      fieldName: match[1],
+      reference: `$${match[1]}`,
+      index: match.index,
+      length: match[0].length,
+    });
+  }
+
+  return matches;
+}
+
+function extractLiteralEventTypeMatches(code) {
+  const matches = [];
+  const eventTypeCallPattern = /\b(ON|OFF)\s*\(\s*(['"])([^'"\\]*(?:\\.[^'"\\]*)*)\2/g;
+  let match;
+
+  while ((match = eventTypeCallPattern.exec(code)) !== null) {
+    const eventType = match[3];
+    const eventTypeIndex = match.index + match[0].indexOf(eventType);
+    matches.push({
+      builtinName: match[1],
+      eventType,
+      index: eventTypeIndex,
+      length: eventType.length,
+    });
+  }
+
+  return matches;
+}
+
+function cloneCatalogDefinition(definition) {
+  return {
+    ...definition,
+    examples: [...definition.examples],
+  };
+}
+
+function toFormEventReferenceDefinition(field, resolver) {
+  return {
+    key: typeof field.key === 'string' ? field.key : field.data_name,
+    reference: `$${field.data_name}`,
+    dataName: field.data_name,
+    label: typeof field.label === 'string' ? field.label : field.data_name,
+    type: typeof field.type === 'string' ? field.type : 'UnknownField',
+    description: typeof field.description === 'string' ? field.description : null,
+    displayStyle:
+      field.display && typeof field.display === 'object' && typeof field.display.style === 'string'
+        ? field.display.style
+        : typeof field.display === 'string'
+          ? field.display
+          : null,
+    parentPath: resolver.getFieldInfo(field.data_name)?.parentPath || [],
+  };
+}
+
+function createIssue({ code, severity, message, symbol = null, index = null, length = null }) {
+  return {
+    code,
+    severity,
+    message,
+    symbol,
+    startIndex: typeof index === 'number' ? index : null,
+    endIndex: typeof index === 'number' && typeof length === 'number' ? index + length : null,
+  };
+}
+
+function addIssue(issues, issueKeys, issue) {
+  const key = `${issue.code}:${issue.symbol || issue.message}`;
+  if (issueKeys.has(key)) {
+    return;
+  }
+  issueKeys.add(key);
+  issues.push(issue);
+}
+
+function validateSyntax(code) {
+  new Function(code);
+}
+
+function createSchemaFilteredSecurityConfig(securityConfig) {
+  if (!securityConfig || typeof securityConfig !== 'object') {
+    return DEFAULT_SECURITY_CONFIG;
+  }
+
+  return {
+    ...securityConfig,
+    validateBuiltins: false,
+  };
+}
+
+/**
+ * @typedef {'stable' | 'advanced' | 'unavailable'} FormEventBuiltinStatus
+ *
+ * @typedef {Object} FormEventBuiltinDefinition
+ * @property {string} name
+ * @property {string} category
+ * @property {string} signature
+ * @property {string} description
+ * @property {string[]} examples
+ * @property {FormEventBuiltinStatus} status
+ *
+ * @typedef {Object} FormEventReferenceDefinition
+ * @property {string} key
+ * @property {string} reference
+ * @property {string} dataName
+ * @property {string} label
+ * @property {string} type
+ * @property {string | null} description
+ * @property {string | null} displayStyle
+ * @property {string[]} parentPath
+ *
+ * @typedef {Object} FormEventCodeIssue
+ * @property {string} code
+ * @property {'error' | 'warning'} severity
+ * @property {string} message
+ * @property {string | null} symbol
+ * @property {number | null} startIndex
+ * @property {number | null} endIndex
+ */
+
+/**
+ * Return the canonical builtin catalog for form event authoring.
+ *
+ * @returns {FormEventBuiltinDefinition[]}
+ */
+export function getFormEventBuiltinCatalog() {
+  return FORM_EVENT_BUILTIN_CATALOG.map(cloneCatalogDefinition);
+}
+
+/**
+ * Return the list of field references available for form event authoring.
+ *
+ * @param {Object} options
+ * @param {Object} options.schema
+ * @returns {FormEventReferenceDefinition[]}
+ */
+export function getFormEventReferenceCatalog({ schema }) {
+  const form = normalizeFormSchema(schema);
+  const resolver = new ContextResolver(form);
+
+  return flattenFields(form.elements)
+    .filter((field) => field && typeof field === 'object')
+    .filter((field) => field.data_name)
+    .filter((field) => !STRUCTURAL_FIELD_TYPES.has(field.type))
+    .map((field) => toFormEventReferenceDefinition(field, resolver));
+}
+
+/**
+ * Statistically analyze form event code without executing it.
+ *
+ * @param {Object} options
+ * @param {string} options.code
+ * @param {Object} options.schema
+ * @param {Object} [options.securityConfig]
+ * @returns {{
+ *   valid: boolean,
+ *   issues: FormEventCodeIssue[],
+ *   usedBuiltins: string[],
+ *   referencedFields: string[],
+ * }}
+ */
+export function analyzeFormEventCode({
+  code,
+  schema,
+  securityConfig = DEFAULT_SECURITY_CONFIG,
+}) {
+  const issues = [];
+  const issueKeys = new Set();
+  const usedBuiltins = [];
+  const usedBuiltinNames = new Set();
+  const referencedFields = [];
+  const referencedFieldNames = new Set();
+  const validEventTypes = new Set(getAllEventTypes());
+  const normalizedCode = typeof code === 'string' ? code : '';
+  const form = normalizeFormSchema(schema);
+  const knownFieldNames = new Set(
+    flattenFields(form.elements)
+      .filter((field) => field && typeof field === 'object')
+      .map((field) => field.data_name)
+      .filter((fieldName) => typeof fieldName === 'string' && fieldName.length > 0)
+  );
+
+  if (normalizedCode.trim().length > 0) {
+    try {
+      validateSyntax(normalizedCode);
+    } catch (error) {
+      addIssue(
+        issues,
+        issueKeys,
+        createIssue({
+          code: 'invalid_syntax',
+          severity: 'error',
+          message:
+            error instanceof Error && error.message
+              ? `Invalid form event syntax: ${error.message}`
+              : 'Invalid form event syntax.',
+          index: 0,
+          length: 1,
+        })
+      );
+    }
+  }
+
+  const securityValidation = validateExpression(
+    normalizedCode,
+    createSchemaFilteredSecurityConfig(securityConfig),
+    true
+  );
+
+  if (!securityValidation.valid) {
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'security_validation_failed',
+        severity: 'error',
+        message: securityValidation.reason,
+        index: 0,
+        length: 1,
+      })
+    );
+  }
+
+  for (const call of extractFunctionCalls(normalizedCode)) {
+    if (isBuiltinCallMatchAllowed(call.name)) {
+      continue;
+    }
+
+    const builtinDefinition = BUILTIN_DEFINITION_BY_NAME.get(call.name);
+    if (builtinDefinition) {
+      const isEventBuiltin = builtinDefinition.contexts.includes(BUILTIN_CONTEXTS.EVENT);
+
+      if (!isEventBuiltin && builtinDefinition.contexts.includes(BUILTIN_CONTEXTS.CALCULATION)) {
+        addIssue(
+          issues,
+          issueKeys,
+          createIssue({
+            code: 'calculation_builtin_not_allowed',
+            severity: 'error',
+            message: `${call.name}() is only available in CalculatedField expressions, not in form event code.`,
+            symbol: call.name,
+            index: call.index,
+            length: call.length,
+          })
+        );
+        continue;
+      }
+
+      const builtinMetadata = FORM_EVENT_BUILTIN_METADATA_BY_NAME.get(call.name);
+      if (!builtinMetadata) {
+        continue;
+      }
+
+      if (!usedBuiltinNames.has(call.name)) {
+        usedBuiltinNames.add(call.name);
+        usedBuiltins.push(call.name);
+      }
+
+      if (builtinMetadata.status === 'unavailable') {
+        addIssue(
+          issues,
+          issueKeys,
+          createIssue({
+            code: 'unavailable_builtin',
+            severity: 'error',
+            message: `${call.name}() is not available in form event code.`,
+            symbol: call.name,
+            index: call.index,
+            length: call.length,
+          })
+        );
+      } else if (builtinMetadata.status === 'advanced') {
+        addIssue(
+          issues,
+          issueKeys,
+          createIssue({
+            code: 'advanced_builtin',
+            severity: 'warning',
+            message: `${call.name}() is an advanced builtin. Prefer direct $field references when possible.`,
+            symbol: call.name,
+            index: call.index,
+            length: call.length,
+          })
+        );
+      }
+
+      continue;
+    }
+
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'unknown_builtin',
+        severity: 'error',
+        message: `Unknown builtin function: ${call.name}.`,
+        symbol: call.name,
+        index: call.index,
+        length: call.length,
+      })
+    );
+  }
+
+  for (const reference of extractFieldReferenceMatches(normalizedCode)) {
+    if (!referencedFieldNames.has(reference.fieldName)) {
+      referencedFieldNames.add(reference.fieldName);
+      referencedFields.push(reference.fieldName);
+    }
+
+    if (!knownFieldNames.has(reference.fieldName)) {
+      addIssue(
+        issues,
+        issueKeys,
+        createIssue({
+          code: 'unknown_field_reference',
+          severity: 'error',
+          message: `Unknown field reference: ${reference.reference}.`,
+          symbol: reference.reference,
+          index: reference.index,
+          length: reference.length,
+        })
+      );
+    }
+  }
+
+  for (const eventTypeReference of extractLiteralEventTypeMatches(normalizedCode)) {
+    if (validEventTypes.has(eventTypeReference.eventType)) {
+      continue;
+    }
+
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'unknown_event_type',
+        severity: 'error',
+        message: `Unknown event type: ${eventTypeReference.eventType}.`,
+        symbol: eventTypeReference.eventType,
+        index: eventTypeReference.index,
+        length: eventTypeReference.length,
+      })
+    );
+  }
+
+  return {
+    valid: issues.every((issue) => issue.severity !== 'error'),
+    issues,
+    usedBuiltins,
+    referencedFields,
+  };
+}