Compatibility and troubleshooting

Tested platforms

Kajay is ESM-only, React 19, and tested in real Chromium. Published declarations are designed for TypeScript 5.5 and newer and are checked with TypeScript 6 and 7. Firefox and WebKit are not support claims until they join CI.

Start with observable state

Keep parse diagnostics and subscribe at the boundary you are debugging. A definition problem, answer change, validation wait, and failed network seam are different states and should not collapse into one generic error.

const { survey, diagnostics } = parseSurvey(definition, options);

for (const diagnostic of diagnostics) {
  logger.warn(diagnostic.code, diagnostic.path, diagnostic.message);
}

survey.onValueChanged.add(({ name, value }) => {
  logger.debug('answer changed', { name, value });
});

survey.onValidatingChanged.add(({ isValidating }) => {
  logger.debug('validation state', { isValidating });
});

Common failures

• Definition will not parse: inspect diagnostic code and path; validate generated JSON against the committed schema.
• Logic looks stale: use setValue, not direct data mutation, and confirm referenced names and function registrations.
• Validation never finishes: ensure every async validator resolves and distinguish a rejected server request from respondent errors.
• Remote choices are empty: supply the matching loader, check response shape, and inspect host authentication or endpoint mapping.
• Custom controls do not respond: forward all contract props, handlers, ids, ARIA attributes, and refs.

Prepare a useful reproduction