@danxbot/ui 4.1.12 → 5.0.0

package/dist/types/index.d.ts

@@ -113,5 +113,5 @@ export { ProvenanceDisclosure, ProvenanceDetail, ProvenanceBadge, ConfidenceRead
 export { createSimStore, resetSimStores, useSimSettings, setSimSettings, getNetworkSpeed, getDataSource, simulateLatency, SimNetworkError, type SimStore, type SimStoreOptions, type SimSettings, type NetworkSpeed, type DataSource, type SimNamespace, } from "./lib/sim";
 export { NodeCanvas, LAYOUT_DEFAULTS, layoutTree, pathToNode, type NodeCanvasProps, type CanvasEdge, type CanvasLayout, type CanvasNode, type CanvasOrientation, type LayoutOptions, type NodeRenderContext, type NodeRenderer, type PlacedNode, } from "./components/node-canvas";
 export { defineRecordType, resetRecordTypes, useRecord, useRecords, useStaleness, write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef, type ReadOptions, type RecordPayload, type RecordState, type RecordTypeOptions, type RecordTypeToken, type StalenessEntry, type WriteAllResult, type WriteOptions, type WriteResult, type WriteSource, type WriteVerdict, } from "./lib/records";
-export { RealtimeProvider, useRealtime, useRealtimeEpoch, useRealtimeHealth, useRealtimeRegistry, SubscriptionRegistry, normalizeScope, scopeKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RealtimeChannel, type RealtimeConnectionState, type RealtimeDiagnostic, type RealtimeEvent, type RealtimeHealth, type RealtimeProviderProps, type RealtimeScope, type RealtimeScopeInput, type RealtimeStatus, type RealtimeTransport, type RegistryOptions, type SubscriptionHealth, type SubscriptionLease, type SubscriptionRequest, } from "./lib/realtime";
-export { useRecordRead, useRecordListRead, useRecordStoreSweep, applyMutationResult, acquireSlot, appendCreatedKey, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type ListFetch, type ListFetchResult, type ListReadOptions, type ListReadResult, type ReadError, type RecordFetch, type RecordReadOptions, type RecordReadResult, type RunnerOptions, type SlotSnapshot, } from "./lib/reads";
+export { RealtimeProvider, useRealtime, useRealtimeEpoch, useRealtimeHealth, useRealtimeRegistry, SubscriptionRegistry, normalizeScope, scopeKey, subscriptionKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RealtimeChannel, type RealtimeConnectionState, type RealtimeDiagnostic, type RealtimeEvent, type RealtimeHealth, type RealtimeProviderProps, type RealtimeScope, type RealtimeScopeInput, type RealtimeStatus, type RealtimeTransport, type RegistryOptions, type SubscriptionHealth, type SubscriptionLease, type SubscriptionRequest, } from "./lib/realtime";
+export { useRecordRead, useRecordListRead, useRecordStoreSweep, applyMutationResult, acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type ListFetch, type ListFetchResult, type ListReadOptions, type ListReadResult, type ReadError, type RecordFetch, type RecordReadOptions, type RecordReadResult, type RunnerOptions, type SlotSnapshot, } from "./lib/reads";

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

@@ -1,4 +1,4 @@
 export { useRecordRead, useRecordListRead, applyMutationResult, useRecordStoreSweep } from "./hooks";
-export { acquireSlot, appendCreatedKey, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, type SlotSnapshot, } from "./slots";
+export { acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, type SlotSnapshot, } from "./slots";
 export { RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type RunnerOptions } from "./refetch";
 export type { ListFetch, ListFetchResult, ListReadOptions, ListReadResult, ReadError, RecordFetch, RecordReadOptions, RecordReadResult, } from "./types";

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

@@ -1,3 +1,4 @@
+import type { RealtimeEvent, RealtimeScope } from "../realtime";
 export interface SlotSnapshot<T = unknown, TMeta = unknown> {
     readonly items: readonly T[];
     readonly pending: readonly T[];
@@ -17,7 +18,7 @@ export declare function emptySlotSnapshot(): SlotSnapshot;
 export declare function acquireSlot(id: string, options: {
     type: string;
     tag: string;
-    acceptsCreated: boolean;
+    createdScope?: RealtimeScope;
 }): () => void;
 /**
  * Replace a slot's membership with a fetch's answer.
@@ -25,15 +26,26 @@ export declare function acquireSlot(id: string, options: {
  * A key that arrived through a `created` event and is now in the fetched page
  * stops being pending — the fetch has placed it, which is the only thing that
  * ever could.
+ *
+ * @param settled  the keys that were pending when this fetch was ISSUED
+ *   (`slotPendingKeys`, read before the request). The answer covers them even
+ *   when it does not hold them: a row that sorted onto another page is not
+ *   "new" any more, it is placed — elsewhere. Without this a counted row that
+ *   lands on page 2 stays "1 new" after Show, forever. A key appended after
+ *   the request went out is not in this list, and stays pending.
  */
-export declare function writeSlot(id: string, keys: readonly string[], meta: unknown): void;
+export declare function writeSlot(id: string, keys: readonly string[], meta: unknown, settled?: readonly string[]): void;
+/** The keys a slot is holding as pending right now — what a fetch issued now will settle. */
+export declare function slotPendingKeys(id: string): readonly string[];
 /**
- * Append a record that entered the set elsewhere.
+ * Append a record that entered the set elsewhere, to every slot it belongs to.
  *
  * WITH NO POSITION. The server owns sort order and page boundary; a client that
  * inserts at a guessed index renders a list that is subtly, confidently wrong.
+ *
+ * AND ONLY WHERE IT BELONGS — see `belongsTo`.
  */
-export declare function appendCreatedKey(type: string, key: string): void;
+export declare function appendCreated(event: RealtimeEvent): void;
 export declare function subscribeToSlot(id: string, listener: () => void): () => void;
 /** The keys a slot holds right now — the roots a targeted refetch matches on. */
 export declare function slotKeys(id: string): readonly string[];

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

@@ -1,4 +1,5 @@
 import type { RecordPayload, RecordState } from "../records";
+import type { RealtimeScopeInput } from "../realtime";
 /**
  * A refusal.
  *
@@ -76,18 +77,28 @@ export interface ListReadOptions<TMeta = unknown> extends CommonReadOptions {
     readonly key: string;
     readonly fetch: ListFetch<TMeta>;
     /**
-     * Whether a `created` broadcast for this type may append to this slot.
-     * Default `true`.
+     * The realtime scope whose `created` events enter this list — normally the
+     * very scope the screen passes to `useRealtime` for this type. Omit it and no
+     * `created` ever appends here.
      *
-     * SET IT FALSE FOR A SLOT WHOSE MEMBERSHIP THIS CLIENT CANNOT VERIFY. The
-     * backend evaluates a filter subscription server-side per save, so a
-     * `created` event arriving on such a subscription IS authoritative that the
-     * record matches — but the library cannot tell WHICH of several slots of the
-     * same type it matches when a screen holds more than one differently-filtered
-     * list. Appending to all of them would be a guess; this flag is where the app
-     * says which one owns the event.
+     * WHY A LIST HAS TO SAY THIS. The channel carries every record of the type
+     * for the whole tenant, and the server sends an event there when ANY
+     * subscription on the tenant matched. So "a `created` arrived" never meant
+     * "it matches this list": a queue filtered to schema A counted a demand of
+     * no schema at all because a teammate had an unfiltered list open — observed,
+     * and the reason this replaced a boolean that appended every `created` of the
+     * type to every list that accepted one.
+     *
+     * How membership is decided per scope:
+     *   - `"all"`  — every `created` of the type belongs.
+     *   - ids      — a `created` whose id the list names belongs.
+     *   - `{filter}` — only a `created` the server ATTRIBUTED to this scope
+     *     (`RealtimeEvent.subscriptions`). The transport must implement
+     *     `subscriptionsOf`, and this scope must also be subscribed with
+     *     `useRealtime` — the attribution names this client's own subscriptions,
+     *     so a filter nobody here subscribed to is never named.
      */
-    readonly acceptsCreated?: boolean;
+    readonly createdScope?: RealtimeScopeInput;
 }
 /** The loading / refreshing / error triple, shared by both reads. */
 interface ReadStatus {

package/dist/types/lib/realtime/index.d.ts

@@ -1,4 +1,4 @@
 export { RealtimeProvider, useRealtimeRegistry, type RealtimeProviderProps } from "./provider";
 export { useRealtime, useRealtimeEpoch, useRealtimeHealth } from "./hooks";
-export { SubscriptionRegistry, normalizeScope, scopeKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RegistryOptions, } from "./registry";
+export { SubscriptionRegistry, normalizeScope, scopeKey, subscriptionKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RegistryOptions, } from "./registry";
 export type { RealtimeChannel, RealtimeConnectionState, RealtimeDiagnostic, RealtimeEvent, RealtimeHealth, RealtimeScope, RealtimeScopeInput, RealtimeStatus, RealtimeTransport, SubscriptionHealth, SubscriptionLease, SubscriptionRequest, } from "./types";

package/dist/types/lib/realtime/registry.d.ts

@@ -48,6 +48,16 @@ export declare function resetRealtimeSignals(): void;
  */
 export declare function normalizeScope(input: RealtimeScopeInput): RealtimeScope;
 export declare function scopeKey(scope: RealtimeScope): string;
+/**
+ * The registry's key for a (type, scope) subscription — the identity
+ * `RealtimeEvent.subscriptions` names.
+ *
+ * ONE FUNCTION FOR BOTH SIDES. The registry keys its entries with it and a list
+ * slot keys its declared `createdScope` with it, so the two cannot disagree
+ * about what "the same subscription" means — a type spelled `WorkflowInput`
+ * here and `WorkflowInputResource` there would silently never match.
+ */
+export declare function subscriptionKey(type: string, scope: RealtimeScopeInput | RealtimeScope): string;
 export declare class SubscriptionRegistry {
     private readonly transport;
     private readonly entries;
@@ -155,6 +165,17 @@ export declare class SubscriptionRegistry {
      * lands in the store as the team you just joined.
      */
     private deliver;
+    /**
+     * This client's subscriptions a broadcast satisfied, translated from the
+     * server's names through each entry's lease keys.
+     *
+     * THE WHOLE REASON THIS IS NEEDED: the channel is per type per tenant, so an
+     * event arrives here whenever ANY subscription on the tenant matched — a
+     * teammate's unfiltered list included. Arrival says "somebody on this team
+     * asked"; only this says "you asked". `undefined` when the transport cannot
+     * say, which is a different answer from `[]` ("it said, and none were yours").
+     */
+    private attribute;
     /** The event name that means "entered the set", for the read binding. */
     get createdEventName(): string;
     subscribeToHealth: (listener: () => void) => (() => void);

package/dist/types/lib/realtime/types.d.ts

@@ -12,10 +12,13 @@ export type RealtimeConnectionState = "connecting" | "connected" | "disconnected
  *
  * - `ids` — the rows on screen. The backend keys its registry entry per model
  *   id, so this is the scope that pins specific records.
- * - `filter` — a server-evaluated predicate. The backend re-runs it per save,
- *   which is what makes a `created` event authoritative about set entry. It
- *   answers "does this record match my filter" and NOTHING about sort position
- *   or page boundary.
+ * - `filter` — a server-evaluated predicate. The backend re-runs it per save
+ *   and answers "does this record match this filter" — and NOTHING about sort
+ *   position or page boundary. ARRIVAL ALONE PROVES NOTHING about this filter:
+ *   the channel is per type per tenant, so an event arrives whenever ANY
+ *   subscription on the tenant matched, including a teammate's wider one. Only
+ *   `RealtimeEvent.subscriptions` says which of this client's scopes it
+ *   satisfied.
  * - `all` — every record of the type for this tenant.
  */
 export type RealtimeScope = {
@@ -57,6 +60,16 @@ export interface SubscriptionRequest {
 export interface SubscriptionLease {
     /** Milliseconds since epoch. Omit only if the server genuinely does not say. */
     readonly expiresAt?: number;
+    /**
+     * The SERVER'S names for this registration — one per server-side entry the
+     * request fanned out to — in the same vocabulary `subscriptionsOf` returns.
+     *
+     * THIS IS HALF OF ATTRIBUTION. A broadcast names the server entries it
+     * satisfied; the registry maps those names back to its own subscriptions
+     * through these. Omitted on a keepalive, the names from the last subscribe
+     * stand — they describe the registration, which a renewal does not change.
+     */
+    readonly keys?: readonly string[];
 }
 /** A joined socket channel. One per type per tenant, and no more. */
 export interface RealtimeChannel {
@@ -111,6 +124,22 @@ export interface RealtimeTransport {
      * warning, and the registry resubscribes rather than waiting.
      */
     keepalive(requests: readonly SubscriptionRequest[]): Promise<readonly SubscriptionLease[]>;
+    /**
+     * Which server-side registrations a broadcast satisfied, in the vocabulary of
+     * `SubscriptionLease.keys` — or `undefined` when this payload does not say.
+     *
+     * WHY IT EXISTS: the channel carries every record of a type for a whole
+     * tenant, and the server sends an event there when ANY subscription on the
+     * tenant matched. Without this a list filtered to schema A counts a record
+     * that arrived only because a teammate has an unfiltered list open —
+     * observed, not theorised. A method rather than a field name because the
+     * field belongs to the wire format, like `isSelfEvent`.
+     *
+     * Optional: a transport whose server cannot attribute leaves it off, and a
+     * list whose membership needs attribution (a `filter` scope) then counts
+     * nothing rather than guessing.
+     */
+    subscriptionsOf?(payload: RecordPayload): readonly string[] | undefined;
     /** Join (or return) the channel carrying this type for this tenant. */
     channel(type: string, tenant: string | number | undefined): RealtimeChannel;
     connectionState(): RealtimeConnectionState;
@@ -197,6 +226,17 @@ export interface RealtimeEvent {
      * consumer comparing the string would be the second place that fact lives.
      */
     readonly isCreate: boolean;
+    /**
+     * This client's subscriptions the broadcast satisfied, by registry key
+     * (`subscriptionKey(type, scope)`), or `undefined` when the transport could
+     * not attribute it.
+     *
+     * AN EMPTY ARRAY IS AN ANSWER, not a missing one: the server attributed the
+     * event and none of the names were this client's — it is on the channel for
+     * somebody else's subscription. That is the case a filtered list must not
+     * count.
+     */
+    readonly subscriptions: readonly string[] | undefined;
     readonly payload: RecordPayload;
     readonly tenant: string | number | undefined;
 }

package/package.json

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