@danxbot/ui 7.9.6 → 7.9.8

package/dist/types/lib/reads/slots.d.ts

@@ -44,6 +44,28 @@ export declare function slotPendingKeys(id: string): readonly string[];
  * inserts at a guessed index renders a list that is subtly, confidently wrong.
  *
  * AND ONLY WHERE IT BELONGS — see `belongsTo`.
+ *
+ * ==== HELD BACK WHILE AN OPTIMISTIC CREATE OF THIS TYPE IS OUTSTANDING (SG-982) ====
+ *
+ * A row the reader just created optimistically has a TEMPORARY key here — the request that will
+ * tell this slot the real one is still in flight. If the server's own `created` broadcast for
+ * that same row reaches this client before that request answers (observed: the broadcast can
+ * easily win the race against the reader's own round trip), it names the REAL key, which this
+ * function cannot recognise as "the row already shown" — the two keys share no characters. Adding
+ * it to `pending` right away would render it as a second row beside the optimistic one for
+ * however long the request takes to settle, which is exactly the transient duplicate this guards
+ * against.
+ *
+ * So while ANY optimistic create for this slot's type is outstanding (`optimisticHead` /
+ * `optimisticTail` non-empty), an incoming `created` key is parked in `awaitingSettle` instead —
+ * neither rendered nor counted — and `settleOptimisticMember` flushes it into `pending` the
+ * instant the slot has no outstanding optimistic create left. If the parked key turns out to BE
+ * the reader's own row, `settleOptimisticMember` already removes it before the flush ever runs
+ * (see its own doc); if it turns out to be someone else's genuinely new row, it reaches `pending`
+ * moments later, no worse than it would have anyway.
+ *
+ * This never suppresses a `created` broadcast outright, and it applies only during a real,
+ * in-progress race — not a guess about which rows might collide, and not a fixed delay.
  */
 export declare function appendCreated(event: RealtimeEvent): void;
 /** What a create's `lists` predicate is shown about each live slot. */
@@ -74,6 +96,12 @@ export declare function addOptimisticMember(key: string, type: string, lists: ((
  * An optimistic create has settled. With `realKey` (the server answered), the real row takes
  * the pending row's place — in the fetched page, so it stays put until the server next orders
  * the list. With `null` (the create failed), the pending row simply goes.
+ *
+ * ALSO THE FLUSH POINT FOR `awaitingSettle` (SG-982): once this slot has no outstanding
+ * optimistic create left, any `created` broadcasts `appendCreated` held back while this one was
+ * in flight are released into `pending` — the race they were parked for is over. `realKey` itself
+ * is removed from that queue first: if it is the reader's own echo, it has just been folded
+ * straight into `keys` above and must never also reach `pending` as a second copy.
  */
 export declare function settleOptimisticMember(tempKey: string, realKey: string | null): void;
 export declare function subscribeToSlot(id: string, listener: () => void): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "7.9.6",
+  "version": "7.9.8",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",