Fields and checks
Declare a record's fields and your own checks: field kinds, labels in Arabic and English, severities, when checks run, acknowledging, and what is sent to the model.
A record is a set of fields plus the checks that judge them. You declare both in useBaseeraImmersive. Baseera never reads your DOM or your database: it sees only what your get functions return and what your checks report.
useBaseeraImmersive({
entity: { type: "invoice", ref: invoice.id, title: `Invoice ${invoice.number}` },
fields: [
{ name: "customer", label: { ar: "العميل", en: "Customer" }, kind: "text", get: () => form.customer },
{ name: "total", label: { ar: "الإجمالي", en: "Total" }, kind: "number", get: () => form.total },
],
checks: [
{
id: "total-mismatch",
severity: "blocking",
fields: ["total"],
run: (r) => (Number(r.total) === linesSum(form.lines) ? { ok: true } : { ok: false, message: "The total does not match the lines." }),
},
],
finish: { label: "Send invoice", action: ({ receipt }) => sendInvoice(invoice.id, receipt) },
});The entity
entity names the record: type (up to 100 characters), ref (up to 200) and an optional title. The pair type and ref identifies the record everywhere: in the receipt, in the trail, in the dashboard and in server signals. Use your own stable ids.
A different type or ref on the same component starts over as a new record. Only one record is in immersive mode at a time. A second useBaseeraImmersive, nested or mounted later, replaces the first, with a warning in development.
Fields
Prop
Type
| Kind | Use for | Value |
|---|---|---|
text | Names, ids, free text, summaries | A string |
number | Amounts, quantities | A number or a numeric string |
date | Dates | An ISO date such as 2026-10-01 |
select | A choice from a list | The chosen value |
Values can be any JSON. A value that cannot be serialized is treated as unchanged and sent as null.
Labels in Arabic and English
Pass { ar, en } and the review panel picks the one that matches its locale. A plain string is used in both. Write the Arabic label as a person would say it, not as a translation of the field name.
Fields that are not inputs
A field does not have to be an input. Line items are a common case: send a one-line summary as the field, and let the checks read the real lines from your state.
{ name: "lines", label: { ar: "البنود", en: "Line items" }, kind: "text",
get: () => form.lines.map((l) => `${l.description} ${l.qty} x ${l.unitPrice}`).join("; ") },The record passed to run
Every check receives record, an object of { [name]: get() }, read at the moment the check runs. The second argument carries signals (see Signals).
run: (record, { signals }) => { /* ... */ }run is synchronous. For a check that needs your server, compute the answer in your own state first (a loaded customer, a lookup result) and read it in the closure. Fresh closures on every render are fine: nothing restarts.
Severities
| Severity | Meaning | Holds the Finish button |
|---|---|---|
blocking | The record should not be finished like this. | Yes. The person can override with a reason. |
warning | Probably wrong, worth a look. | Only if you set blockOnWarnings. |
info | A note. | No. |
A check returns { ok: true } or { ok: false, message, fix? }. Write the message for the person: what is wrong, in their language. It is shown on the field and sent to the model.
If run throws, the check counts as failed with the message "This check could not run." A blocking check that throws keeps the finish disabled, and the override is unavailable until the check runs. A check that cannot run is unknown, not passing.
When checks run
- When immersive mode starts.
- 250 ms after a field's value changes. Values are compared as JSON on each render, so a burst of typing runs the checks once.
- At once when you send a signal.
- After
recheck(), on the same 250 ms delay.
Call recheck() after anything that changes a result but is not a field: a lookup that finished, a toggle outside the form.
const { recheck } = useBaseeraImmersiveState();
useEffect(() => recheck(), [customer, recheck]);A check that turns passing stays in results with the status resolved for 3 seconds, so the person sees it clear, and then drops.
Acknowledge
acknowledge(id) hides a warning or an info for this record until its result changes: the same check id with a different message shows again. In the review panel this is the Got it button.
- Blocking checks cannot be acknowledged. The call is ignored, with a warning in development.
- An acknowledged check still counts as failing for the model (
ok: falseon the wire), so the model knows it was dismissed rather than fixed. - An acknowledged warning no longer holds a finish when
blockOnWarningsis on. - Each acknowledgement is written to the trail.
What is sent to the model
On every chat turn while a record is open, the SDK sends the entity, each field's name, label, kind and value, and each check's id, severity, pass or fail, message and fields. The runtime puts them in the system prompt as data from your app, never as instructions, and adds a platform rule telling the model to treat the checks as the source of truth.
| Limit | Value | When over |
|---|---|---|
| Fields | 50 | The request is refused with invalid_request. |
| Checks | 100 | The request is refused with invalid_request. |
| One field value | 2 KB serialized | The SDK cuts it and ends it with …[truncated]. |
The whole immersive object | 16 KB | The SDK drops field values first, then passing checks. |
The check function itself, and a check's fix, are not sent. Only results are.
Everything sent goes to the model provider you chose. Do not declare fields that hold secrets, and keep values to what the checks and the model need.
Next steps
Quickstart
Add immersive mode to an invoice screen: declare fields, a blocking check and a warning, bind the inputs, show the finish bar and verify the finish on your server.
AI checks
Write a rule in plain words on the agent, opt a screen into it by id, and let Baseera check the record against your knowledge, with sources, caching and a cost cap.