@lotics/app-sdk 0.82.0 → 0.82.2

package/docs/ai.md

@@ -322,6 +322,25 @@ Publish the **rendered** view, not the whole table. A screen that shows page 2 o
 
 Declarative and lifecycle-bound: mounting or changing `context` pushes it; unmounting, renaming the `slot`, or passing `null` clears it. Independent components hold **different slots** at once (a list screen + an open drawer), and the newest value per slot wins. Re-posting is change-gated — passing a fresh inline object each render does **not** spam the host; only a real value change re-publishes.
 
+### A slot that never publishes looks exactly like a slot with nothing to say
+
+The failure mode worth knowing before you wire one: this hook has **no visible output**. A
+`useAiContext` behind a guard that never opens publishes `null` forever while the screen it
+describes renders perfectly, and nothing anywhere reports it. Silence is the same shape as
+"there is nothing to report", so neither the app nor a review catches it.
+
+The usual cause is a guard on the query state. `useQuery`'s `error` is `string | null` — it is
+**never `undefined`** — so `error !== undefined` is always true and holds the guard shut on every
+render. Write `if (loading || error) return;`, which is correct whichever of the two the field
+turns out to be, and reads as the question you meant.
+
+**Verify by observing what is published, never by reading the code.** Run the app under
+`lotics app dev` and listen for the host notification on the wrapper page — the payload is the
+context as the chat agent will receive it. Check three things, because each fails differently:
+the slot carries REAL values matching what is on screen (not placeholders), it clears to `null`
+when the surface closes or the tab changes, and it does not publish while the first read is still
+in flight — a count of zero taken from a pending query is an answer nothing measured.
+
 ### The caps (host-enforced — exceeding them truncates or drops, never errors)
 
 | Field | Cap |

package/docs/mutations.md

@@ -272,18 +272,22 @@ Inside the workflow body, the payload is `trigger.app_workflow.inputs.<name>`, t
 `T | null | undefined` for an optional input. The triggering member is
 `runtime.triggered_by_member_id` (`null` for an anonymous public caller).
 
-**Guard on `undefined`, not on nullish.** The three caller states arrive intact, and the loose
-`!= null` collapses two of them — it skips a clear as well as an omission, which is how a Clear
-button ends up doing nothing:
+**Guard on the KEY, not on the value.** The three caller states arrive intact — an omitted input
+has no key at all, a cleared one has the key with `null` — so a value test cannot tell them apart:
+`!= null` and `isNull(…)` both skip a clear as well as an omission, which is how a Clear button
+ends up doing nothing. Ask whether the key was sent:
 
 ```js
 const i = trigger.app_workflow.inputs;
-if (i.title !== undefined) {
+if (includes(keys(i), "title")) {
   // i.title may be null here — that is the CLEAR, and `set` writes it as one.
   await update_records({ table_id: "tbl_items", record_ids: [i.record_id], set: { fld_title: i.title } });
 }
 ```
 
+`undefined` is not spellable in a workflow body — the expression subset has no such identifier, and
+a body naming it fails to save with `Unknown identifier "undefined"`. `keys` is the presence test.
+
 When several optional inputs each map to a field, per-field guards become noise. Hand the whole
 bag to `update_records`' **`set_skip_null`** instead — same object shape as `set`, but entries
 whose value is `null`/`undefined` are dropped, so only the fields actually provided get written

package/docs/workflows.md

@@ -504,15 +504,20 @@ record is the body's decision, and the two write surfaces answer differently:
 | `set: { fld_x: i.x }` | **clears the field** |
 
 So `set_skip_null` is the right default for a bag of optional inputs, and the wrong choice for any
-field the screen must be able to blank — put those in `set`, and guard on `undefined` so an input
-the caller never sent is not written:
+field the screen must be able to blank — put those in `set`, and test whether the KEY was sent so
+an input the caller never sent is not written:
 
 ```js
-if (i.phone !== undefined) {   // NOT `!= null` — that swallows the clear
+if (includes(keys(i), "phone")) {   // NOT `isNull(i.phone)` — that swallows the clear
   await update_records({ table_id: "tbl_x", record_ids: [i.id], set: { fld_phone: i.phone } });
 }
 ```
 
+An omitted input carries no key at all and a cleared one carries the key with `null`, so presence
+is the only test that separates them. It has to be `keys` rather than a comparison against
+`undefined`: the expression subset has no `undefined` identifier, and a body naming it fails to
+save with `Unknown identifier "undefined"`.
+
 `""` is never a clear on any surface: an HTML input emits it for "the user skipped this", so the
 validator coerces it to omitted before the body runs. Reaching for `""` to blank a field fails
 silently — the write reports success and the old value stays. Send `null`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.82.0",
+  "version": "0.82.2",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {