@palbase/web 1.6.2 → 1.8.0

package/dist/{analytics-facade-DhcTP_kw.d.ts → analytics-facade-CgURkjpP.d.ts}

@@ -622,6 +622,16 @@ interface PalbeConfig {
     apiKey: string;
     /** Informational — url+apiKey are already branch-specific (endpointRef embeds the branch slug); gen bakes all three consistently. */
     branch?: string;
+    /**
+     * F2 app-registration: the registered app `identifier` from
+     * `palbase-config.json` — for web this is the declared ORIGIN (e.g.
+     * `https://app.example.com`). When non-empty, `configure` REFUSES to build the
+     * runtime if `window.location.origin` does not match (SDK-REFUSES), and the
+     * value rides on `X-Palbase-Bundle` on EVERY request so the Kong gate can match
+     * it (the IDENTICAL header + value the iOS SDK sends). Empty/absent → legacy /
+     * tooling: no guard, no header.
+     */
+    identifier?: string;
     oauth?: PalbeOAuthConfig;
     /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
     storage?: SessionStorageAdapter;
@@ -825,6 +835,49 @@ interface ChatMessage {
      * Mirrors iOS `ChatMessage.effectiveExpiry` (which it derives from).
      */
     readonly expiresAt: Date | null;
+    /**
+     * Server-metadata cluster — the double-tick DELIVERED watermark on THIS user's OWN
+     * (`direction === 'outgoing'`) messages, FOLDED TO USER-LEVEL. The wire carries the
+     * acking device_id; the SDK folds across a peer's devices and across peers to ONE
+     * user-level server_seq (MONOTONIC max — a stale lower incoming tick NEVER lowers it).
+     * A per-message tick is "is `message.serverSeq <= deliveredUpTo`?". Absent (`undefined`)
+     * until a `delivered` conv event covers this message; never set on an incoming message.
+     * Mirrors iOS `Chat.deliveredUpTo` (a chat-level scalar there; per-message here).
+     */
+    readonly deliveredUpTo?: number;
+    /**
+     * Server-metadata cluster — the double-tick READ watermark on THIS user's OWN
+     * (`direction === 'outgoing'`) messages, FOLDED TO USER-LEVEL + MONOTONIC max (same
+     * fold as `deliveredUpTo`). Set by a `read` conv event. Read STAYS gated by the peer's
+     * `share_receipts` server-side (the broadcast simply never arrives when muted); the
+     * client fold is identical to delivered. Mirrors iOS `Chat.readUpTo`.
+     */
+    readonly readUpTo?: number;
+}
+/**
+ * The per-(user, group) notify scope (the server-metadata MUTE toggle). `'all'`
+ * (default, absent row) fires the push wake; `'none'` (muted) suppresses it. The raw
+ * wire value is the snake-free `"all"`/`"none"` string. An unknown/garbage server value
+ * maps to `'all'` at the surface — fail-OPEN, never silently mutes (mirrors iOS
+ * `NotifyScope`). The server stores this opaque enum and stays MLS-blind (no content).
+ */
+type NotifyScope = 'all' | 'none';
+/**
+ * The caller's OWN unread view (the `GET /v1/messaging/groups/{gid}/unread` response).
+ * Every field is an OPAQUE server-metadata integer (no message content): the group's max
+ * server_seq, this caller's read + delivered cursors, and the server-derived unread
+ * count. The camelCase mirror of the snake_case wire (`group_max_seq` → `groupMaxSeq`,
+ * etc). Mirrors iOS `UnreadView`.
+ */
+interface UnreadView {
+    /** The highest server_seq the group has reached (the newest message's seq). */
+    readonly groupMaxSeq: number;
+    /** The furthest server_seq THIS caller has marked read. */
+    readonly lastReadSeq: number;
+    /** The furthest server_seq THIS caller's devices have acked delivered. */
+    readonly deliveredSeq: number;
+    /** The server-derived unread count for this caller (clamped `>= 0` at the surface). */
+    readonly unreadCount: number;
 }
 /** The receipt from a send — the server's monotonic sequence + accepted epoch. */
 interface SentReceipt {
@@ -1001,7 +1054,12 @@ interface ChatBackend {
     registerActive(group: MessagingGroup): void;
     setTyping(group: MessagingGroup, isTyping: boolean): void;
     markRead(group: MessagingGroup, upToServerSeq: number): Promise<void>;
-    /** Subscribe live message + conv (presence/typing/read) for an active group. */
+    /** Server-metadata cluster: set/get the per-(user,group) notify scope (mute) and
+     * fetch the caller's own unread view. The server stays MLS-blind (opaque metadata). */
+    setNotifyScope(group: MessagingGroup, scope: NotifyScope): Promise<NotifyScope>;
+    getNotifyScope(group: MessagingGroup): Promise<NotifyScope>;
+    unread(group: MessagingGroup): Promise<UnreadView>;
+    /** Subscribe live message + conv (presence/typing/read/delivered) for an active group. */
     subscribeLive(group: MessagingGroup, chat: Chat): Unsubscribe$1;
     /** Resolve a sender device id → its owning user id (for senderUserId). */
     userIdForDevice(group: MessagingGroup, deviceId: string): Promise<string | null>;
@@ -1306,6 +1364,20 @@ declare class Chat {
     leave(): Promise<void>;
     setTyping(isTyping: boolean): void;
     markRead(message: ChatMessage): Promise<void>;
+    /** Set this chat's notify scope (the mute toggle). `'none'` mutes the push wake;
+     * `'all'` unmutes (the default). Materializes a draft first (the scope is a
+     * per-(user,group) server row), PUTs `/notify`, and returns the server-echoed scope.
+     * Mirrors iOS `Chat.setNotifyScope`. */
+    setNotifyScope(scope: NotifyScope): Promise<NotifyScope>;
+    /** Refresh + return this chat's notify scope from the server (fail-OPEN to `'all'`).
+     * Returns `'all'` for a draft chat (no server row yet). */
+    getNotifyScope(): Promise<NotifyScope>;
+    /** Fetch the caller's authoritative SERVER unread count (opaque server metadata).
+     * Returns the clamped count (`max(0, …)`); `0` for a draft chat. The local computed
+     * `unreadCount` getter stays the instant, offline best-effort badge — this is the
+     * canonical count on demand. Named distinctly so it does not shadow the observable
+     * `unreadCount` snapshot getter. Mirrors iOS `Chat.refreshUnread`. */
+    unreadCountFromServer(): Promise<number>;
     /** Add an emoji reaction to a message. No-op if the message isn't reactable
      * (empty clientMsgId — a legacy/system row). The reaction folds locally with
      * the server receipt's `(epoch, serverSeq)` so the target's tally updates
@@ -1374,6 +1446,153 @@ declare class PalbeMessaging {
     onChatsChange(cb: () => void): Unsubscribe$1;
 }
 
+/** The Faz-1 trace kinds plus the Faz-1.5 web-vital family. */
+type PerfTraceType = 'network' | 'app_start' | 'custom' | 'web_vital';
+/**
+ * One perf measurement, shaped EXACTLY as the ingest wire expects. Keys are
+ * snake_case to match the Go decode tags — do not rename to camelCase.
+ */
+interface PerfItem {
+    /** Client-generated UUIDv7 — server dedup key. */
+    row_id: string;
+    trace_type: PerfTraceType;
+    name: string;
+    /** Duration in milliseconds. */
+    value: number;
+    counters?: Record<string, number>;
+    attrs?: Record<string, string>;
+    request_id?: string;
+    /** Unix milliseconds. */
+    timestamp: number;
+}
+
+/**
+ * Bounded FIFO perf-item queue. `enqueue` appends and evicts the oldest on
+ * overflow; `drainAll` returns everything (oldest-first) and clears the store;
+ * `count` is the current depth; `dropped` is the cumulative eviction counter.
+ *
+ * When `localStorage` is present the queue is read-through / write-through to a
+ * fixed key, so a fresh instance after a reload sees the persisted items. With
+ * no `localStorage` it is purely in-memory.
+ */
+declare class PerfOfflineQueue {
+    private items;
+    private _dropped;
+    private readonly maxItems;
+    constructor(maxItems?: number);
+    /** Append items; FIFO-evict the oldest when over `maxItems`. */
+    enqueue(items: PerfItem[]): void;
+    /** Return all queued items (oldest-first) and clear the queue + store. */
+    drainAll(): PerfItem[];
+    /** Current queue depth. */
+    get count(): number;
+    /** Cumulative count of FIFO-evicted items (a `dropped` metric, not silent). */
+    get dropped(): number;
+    /** Drop the oldest items until at most `maxItems` remain, counting each. */
+    private trim;
+    private persist;
+    private clearStore;
+}
+
+/**
+ * The mutable PalPerf state shared between the facade and the network hook.
+ * `testDevice` is signalled to the server via the `X-Palbase-Test-Device: 1`
+ * request header (server-authoritative tagging — the SDK only flips the bit).
+ */
+declare class PerfState {
+    /** Pending, un-flushed perf items (FIFO). */
+    readonly buffer: PerfItem[];
+    /** When true, every flush carries `X-Palbase-Test-Device: 1`. */
+    testDevice: boolean;
+    enqueue(item: PerfItem): void;
+    /** Detach up to `MAX_PERF_BATCH` items for one POST (FIFO order preserved). */
+    take(limit?: number): PerfItem[];
+    get size(): number;
+}
+
+/**
+ * A running custom trace. `putAttribute`/`incrementMetric` accumulate metadata;
+ * `stop()` records ONE `custom` PerfItem whose `value` is the elapsed
+ * milliseconds since `startTrace`. Idempotent: a second `stop()` is a no-op.
+ */
+declare class PerfTrace {
+    private readonly name;
+    private readonly onStop;
+    private readonly attrs;
+    private readonly counters;
+    private readonly startedAt;
+    private stopped;
+    constructor(name: string, onStop: (item: PerfItem) => void);
+    putAttribute(key: string, value: string): void;
+    incrementMetric(name: string, by?: number): void;
+    stop(): void;
+}
+declare class PalbePerf {
+    private readonly rt;
+    private readonly state;
+    /** Durable offline buffer for failed flushes (persist-on-fail). Browser →
+     * localStorage-backed; server → in-memory. */
+    private readonly queue;
+    private flushTimer;
+    /** Browser → buffer + size/timer flush. Server (no document) → immediate
+     * per-item flush, zero timers (nothing leaks into RSC/route handlers). */
+    private readonly browser;
+    /** Bound `online` handler so it can be removed on `dispose()` (no leak). */
+    private readonly onOnline;
+    /** Server-controlled client-side sample rate (0..100). 100 until the config
+     * client fetches `/v1/analytics/perf/config` — the SDK obeys this ceiling and
+     * never raises its own rate (invariant 3). `record` drops an item whose
+     * deterministic `row_id` bucket is >= this pct, mirroring the server's
+     * `SampleDecision` so client + server keep the SAME rows. */
+    private samplePct;
+    constructor(rt: PalbeRuntime, state?: PerfState, 
+    /** Durable offline buffer for failed flushes (persist-on-fail). Browser →
+     * localStorage-backed; server → in-memory. */
+    queue?: PerfOfflineQueue);
+    /** Remove the `online` listener. Called when the runtime is replaced so the
+     * handler does not outlive this facade. No-op outside the browser. */
+    dispose(): void;
+    /** Mark (or unmark) this client's traffic as test — the server tags the rows
+     * when the `X-Palbase-Test-Device: 1` header rides along on flush. */
+    setTestDevice(on: boolean): void;
+    /** Apply the server-resolved client-side sample rate (0..100), clamped. Called
+     * by `PerfConfigClient` after fetching `/v1/analytics/perf/config`. The SDK
+     * OBEYS this value — it is a ceiling, never raised locally. */
+    setSamplePct(pct: number): void;
+    /** Pending (un-flushed) buffer depth. Test-only visibility into the buffer so
+     * the remote-sampling tests can assert how many items were sampled in. */
+    get bufferSizeForTest(): number;
+    /** Opt-in: wrap the global `fetch` so every app-level request is recorded as a
+     * redacted `network` perf item (the `/v1/analytics/*` ingest paths are
+     * self-excluded). OFF by default — swizzling a global is a page-wide side
+     * effect. Returns an `uninstall` that restores the original `fetch`. */
+    enableFetchCapture(): () => void;
+    /** Start a custom trace; the returned handle records a `custom` item on
+     * `.stop()`. */
+    startTrace(name: string): PerfTrace;
+    /** Buffer one perf item. In the browser, flush on size/timer; on the server
+     * flush immediately (no timers). Never throws.
+     *
+     * Client-side remote sampling: an item whose deterministic `row_id` bucket is
+     * NOT below the server-controlled `samplePct` is dropped before buffering —
+     * the SAME FNV-1a-mod-100 decision the server applies at ingest, so the two
+     * keep identical rows and the SDK saves the upload (defense-in-depth: the
+     * server re-samples authoritatively). */
+    record(item: PerfItem): void;
+    /** Buffer a network trace — called by `request.ts` around `rt.http.request`
+     * (the analytics ingest path is excluded by the caller to avoid recursion). */
+    recordNetwork(method: string, url: string, status: number, durationMs: number, requestId?: string): void;
+    /** Drain the offline queue (oldest-first) and the live buffer to
+     * `/v1/analytics/perf` (≤100 items per request, sequential). Resolves when
+     * delivery finished; NEVER rejects. A failed slice is NOT dropped — it goes
+     * to the offline queue (persist-on-fail) so the next flush (size/timer or the
+     * `online` reconnect event) retries it. Items keep their original `row_id`,
+     * so a redelivery dedups server-side (ReplacingMergeTree). */
+    flush(): Promise<void>;
+    private startTimer;
+    private cancelTimer;
+}
+
 /**
  * The connection state of the shared realtime WebSocket (iOS enum parity), plus
  * `'error'` — surfaced when a channel could not be recovered after a
@@ -1471,6 +1690,14 @@ declare class PalbeRealtime {
 
 interface PalbeRuntime {
     config: PalbeConfig;
+    /**
+     * F2 app-registration: the registered app `identifier` (web ORIGIN) stashed at
+     * configure. Rides on `X-Palbase-Bundle` on EVERY request (request.ts) so the
+     * Kong gate can match it. Empty string when the binding is unconfigured/tooling
+     * (no header is sent). Origin-match is enforced in `buildRuntime` BEFORE this
+     * runtime is returned — a mismatch throws there and no runtime is built.
+     */
+    appIdentifier: string;
     http: HttpClient$1;
     tokenManager: TokenManager$1;
     authClient: AuthClient;
@@ -1480,6 +1707,13 @@ interface PalbeRuntime {
     analytics: PalbeAnalytics;
     calls: PalbeCalls;
     messaging: PalbeMessaging;
+    /**
+     * PalPerf surface. EAGER (like analytics identity): `request.ts` records a
+     * `network` trace around EVERY SDK fetch, so the facade must exist from the
+     * first request — never lazy. The buffer/timer it owns is inert until the
+     * first item is recorded.
+     */
+    perf: PalbePerf;
     storage: SessionStorageAdapter;
     /**
      * Destroy the realtime facade if it was already constructed (no-op otherwise).
@@ -1731,4 +1965,4 @@ declare class PalbeAnalytics {
     private post;
 }
 
-export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type PalbeRuntime as N, type OAuthExchangeResult as O, PalbeAnalytics as P, buildRuntime as Q, RealtimeChannel as R, type SentReceipt as S, type Unsubscribe as U, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };
+export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type NotifyScope as N, type OAuthExchangeResult as O, PalbeAnalytics as P, type Unsubscribe as Q, RealtimeChannel as R, type SentReceipt as S, type PalbeRuntime as T, type UnreadView as U, buildRuntime as V, PalbePerf as W, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };

package/dist/{analytics-facade-ATGUv2-f.d.cts → analytics-facade-DfJ420F5.d.cts}

@@ -622,6 +622,16 @@ interface PalbeConfig {
     apiKey: string;
     /** Informational — url+apiKey are already branch-specific (endpointRef embeds the branch slug); gen bakes all three consistently. */
     branch?: string;
+    /**
+     * F2 app-registration: the registered app `identifier` from
+     * `palbase-config.json` — for web this is the declared ORIGIN (e.g.
+     * `https://app.example.com`). When non-empty, `configure` REFUSES to build the
+     * runtime if `window.location.origin` does not match (SDK-REFUSES), and the
+     * value rides on `X-Palbase-Bundle` on EVERY request so the Kong gate can match
+     * it (the IDENTICAL header + value the iOS SDK sends). Empty/absent → legacy /
+     * tooling: no guard, no header.
+     */
+    identifier?: string;
     oauth?: PalbeOAuthConfig;
     /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
     storage?: SessionStorageAdapter;
@@ -825,6 +835,49 @@ interface ChatMessage {
      * Mirrors iOS `ChatMessage.effectiveExpiry` (which it derives from).
      */
     readonly expiresAt: Date | null;
+    /**
+     * Server-metadata cluster — the double-tick DELIVERED watermark on THIS user's OWN
+     * (`direction === 'outgoing'`) messages, FOLDED TO USER-LEVEL. The wire carries the
+     * acking device_id; the SDK folds across a peer's devices and across peers to ONE
+     * user-level server_seq (MONOTONIC max — a stale lower incoming tick NEVER lowers it).
+     * A per-message tick is "is `message.serverSeq <= deliveredUpTo`?". Absent (`undefined`)
+     * until a `delivered` conv event covers this message; never set on an incoming message.
+     * Mirrors iOS `Chat.deliveredUpTo` (a chat-level scalar there; per-message here).
+     */
+    readonly deliveredUpTo?: number;
+    /**
+     * Server-metadata cluster — the double-tick READ watermark on THIS user's OWN
+     * (`direction === 'outgoing'`) messages, FOLDED TO USER-LEVEL + MONOTONIC max (same
+     * fold as `deliveredUpTo`). Set by a `read` conv event. Read STAYS gated by the peer's
+     * `share_receipts` server-side (the broadcast simply never arrives when muted); the
+     * client fold is identical to delivered. Mirrors iOS `Chat.readUpTo`.
+     */
+    readonly readUpTo?: number;
+}
+/**
+ * The per-(user, group) notify scope (the server-metadata MUTE toggle). `'all'`
+ * (default, absent row) fires the push wake; `'none'` (muted) suppresses it. The raw
+ * wire value is the snake-free `"all"`/`"none"` string. An unknown/garbage server value
+ * maps to `'all'` at the surface — fail-OPEN, never silently mutes (mirrors iOS
+ * `NotifyScope`). The server stores this opaque enum and stays MLS-blind (no content).
+ */
+type NotifyScope = 'all' | 'none';
+/**
+ * The caller's OWN unread view (the `GET /v1/messaging/groups/{gid}/unread` response).
+ * Every field is an OPAQUE server-metadata integer (no message content): the group's max
+ * server_seq, this caller's read + delivered cursors, and the server-derived unread
+ * count. The camelCase mirror of the snake_case wire (`group_max_seq` → `groupMaxSeq`,
+ * etc). Mirrors iOS `UnreadView`.
+ */
+interface UnreadView {
+    /** The highest server_seq the group has reached (the newest message's seq). */
+    readonly groupMaxSeq: number;
+    /** The furthest server_seq THIS caller has marked read. */
+    readonly lastReadSeq: number;
+    /** The furthest server_seq THIS caller's devices have acked delivered. */
+    readonly deliveredSeq: number;
+    /** The server-derived unread count for this caller (clamped `>= 0` at the surface). */
+    readonly unreadCount: number;
 }
 /** The receipt from a send — the server's monotonic sequence + accepted epoch. */
 interface SentReceipt {
@@ -1001,7 +1054,12 @@ interface ChatBackend {
     registerActive(group: MessagingGroup): void;
     setTyping(group: MessagingGroup, isTyping: boolean): void;
     markRead(group: MessagingGroup, upToServerSeq: number): Promise<void>;
-    /** Subscribe live message + conv (presence/typing/read) for an active group. */
+    /** Server-metadata cluster: set/get the per-(user,group) notify scope (mute) and
+     * fetch the caller's own unread view. The server stays MLS-blind (opaque metadata). */
+    setNotifyScope(group: MessagingGroup, scope: NotifyScope): Promise<NotifyScope>;
+    getNotifyScope(group: MessagingGroup): Promise<NotifyScope>;
+    unread(group: MessagingGroup): Promise<UnreadView>;
+    /** Subscribe live message + conv (presence/typing/read/delivered) for an active group. */
     subscribeLive(group: MessagingGroup, chat: Chat): Unsubscribe$1;
     /** Resolve a sender device id → its owning user id (for senderUserId). */
     userIdForDevice(group: MessagingGroup, deviceId: string): Promise<string | null>;
@@ -1306,6 +1364,20 @@ declare class Chat {
     leave(): Promise<void>;
     setTyping(isTyping: boolean): void;
     markRead(message: ChatMessage): Promise<void>;
+    /** Set this chat's notify scope (the mute toggle). `'none'` mutes the push wake;
+     * `'all'` unmutes (the default). Materializes a draft first (the scope is a
+     * per-(user,group) server row), PUTs `/notify`, and returns the server-echoed scope.
+     * Mirrors iOS `Chat.setNotifyScope`. */
+    setNotifyScope(scope: NotifyScope): Promise<NotifyScope>;
+    /** Refresh + return this chat's notify scope from the server (fail-OPEN to `'all'`).
+     * Returns `'all'` for a draft chat (no server row yet). */
+    getNotifyScope(): Promise<NotifyScope>;
+    /** Fetch the caller's authoritative SERVER unread count (opaque server metadata).
+     * Returns the clamped count (`max(0, …)`); `0` for a draft chat. The local computed
+     * `unreadCount` getter stays the instant, offline best-effort badge — this is the
+     * canonical count on demand. Named distinctly so it does not shadow the observable
+     * `unreadCount` snapshot getter. Mirrors iOS `Chat.refreshUnread`. */
+    unreadCountFromServer(): Promise<number>;
     /** Add an emoji reaction to a message. No-op if the message isn't reactable
      * (empty clientMsgId — a legacy/system row). The reaction folds locally with
      * the server receipt's `(epoch, serverSeq)` so the target's tally updates
@@ -1374,6 +1446,153 @@ declare class PalbeMessaging {
     onChatsChange(cb: () => void): Unsubscribe$1;
 }
 
+/** The Faz-1 trace kinds plus the Faz-1.5 web-vital family. */
+type PerfTraceType = 'network' | 'app_start' | 'custom' | 'web_vital';
+/**
+ * One perf measurement, shaped EXACTLY as the ingest wire expects. Keys are
+ * snake_case to match the Go decode tags — do not rename to camelCase.
+ */
+interface PerfItem {
+    /** Client-generated UUIDv7 — server dedup key. */
+    row_id: string;
+    trace_type: PerfTraceType;
+    name: string;
+    /** Duration in milliseconds. */
+    value: number;
+    counters?: Record<string, number>;
+    attrs?: Record<string, string>;
+    request_id?: string;
+    /** Unix milliseconds. */
+    timestamp: number;
+}
+
+/**
+ * Bounded FIFO perf-item queue. `enqueue` appends and evicts the oldest on
+ * overflow; `drainAll` returns everything (oldest-first) and clears the store;
+ * `count` is the current depth; `dropped` is the cumulative eviction counter.
+ *
+ * When `localStorage` is present the queue is read-through / write-through to a
+ * fixed key, so a fresh instance after a reload sees the persisted items. With
+ * no `localStorage` it is purely in-memory.
+ */
+declare class PerfOfflineQueue {
+    private items;
+    private _dropped;
+    private readonly maxItems;
+    constructor(maxItems?: number);
+    /** Append items; FIFO-evict the oldest when over `maxItems`. */
+    enqueue(items: PerfItem[]): void;
+    /** Return all queued items (oldest-first) and clear the queue + store. */
+    drainAll(): PerfItem[];
+    /** Current queue depth. */
+    get count(): number;
+    /** Cumulative count of FIFO-evicted items (a `dropped` metric, not silent). */
+    get dropped(): number;
+    /** Drop the oldest items until at most `maxItems` remain, counting each. */
+    private trim;
+    private persist;
+    private clearStore;
+}
+
+/**
+ * The mutable PalPerf state shared between the facade and the network hook.
+ * `testDevice` is signalled to the server via the `X-Palbase-Test-Device: 1`
+ * request header (server-authoritative tagging — the SDK only flips the bit).
+ */
+declare class PerfState {
+    /** Pending, un-flushed perf items (FIFO). */
+    readonly buffer: PerfItem[];
+    /** When true, every flush carries `X-Palbase-Test-Device: 1`. */
+    testDevice: boolean;
+    enqueue(item: PerfItem): void;
+    /** Detach up to `MAX_PERF_BATCH` items for one POST (FIFO order preserved). */
+    take(limit?: number): PerfItem[];
+    get size(): number;
+}
+
+/**
+ * A running custom trace. `putAttribute`/`incrementMetric` accumulate metadata;
+ * `stop()` records ONE `custom` PerfItem whose `value` is the elapsed
+ * milliseconds since `startTrace`. Idempotent: a second `stop()` is a no-op.
+ */
+declare class PerfTrace {
+    private readonly name;
+    private readonly onStop;
+    private readonly attrs;
+    private readonly counters;
+    private readonly startedAt;
+    private stopped;
+    constructor(name: string, onStop: (item: PerfItem) => void);
+    putAttribute(key: string, value: string): void;
+    incrementMetric(name: string, by?: number): void;
+    stop(): void;
+}
+declare class PalbePerf {
+    private readonly rt;
+    private readonly state;
+    /** Durable offline buffer for failed flushes (persist-on-fail). Browser →
+     * localStorage-backed; server → in-memory. */
+    private readonly queue;
+    private flushTimer;
+    /** Browser → buffer + size/timer flush. Server (no document) → immediate
+     * per-item flush, zero timers (nothing leaks into RSC/route handlers). */
+    private readonly browser;
+    /** Bound `online` handler so it can be removed on `dispose()` (no leak). */
+    private readonly onOnline;
+    /** Server-controlled client-side sample rate (0..100). 100 until the config
+     * client fetches `/v1/analytics/perf/config` — the SDK obeys this ceiling and
+     * never raises its own rate (invariant 3). `record` drops an item whose
+     * deterministic `row_id` bucket is >= this pct, mirroring the server's
+     * `SampleDecision` so client + server keep the SAME rows. */
+    private samplePct;
+    constructor(rt: PalbeRuntime, state?: PerfState, 
+    /** Durable offline buffer for failed flushes (persist-on-fail). Browser →
+     * localStorage-backed; server → in-memory. */
+    queue?: PerfOfflineQueue);
+    /** Remove the `online` listener. Called when the runtime is replaced so the
+     * handler does not outlive this facade. No-op outside the browser. */
+    dispose(): void;
+    /** Mark (or unmark) this client's traffic as test — the server tags the rows
+     * when the `X-Palbase-Test-Device: 1` header rides along on flush. */
+    setTestDevice(on: boolean): void;
+    /** Apply the server-resolved client-side sample rate (0..100), clamped. Called
+     * by `PerfConfigClient` after fetching `/v1/analytics/perf/config`. The SDK
+     * OBEYS this value — it is a ceiling, never raised locally. */
+    setSamplePct(pct: number): void;
+    /** Pending (un-flushed) buffer depth. Test-only visibility into the buffer so
+     * the remote-sampling tests can assert how many items were sampled in. */
+    get bufferSizeForTest(): number;
+    /** Opt-in: wrap the global `fetch` so every app-level request is recorded as a
+     * redacted `network` perf item (the `/v1/analytics/*` ingest paths are
+     * self-excluded). OFF by default — swizzling a global is a page-wide side
+     * effect. Returns an `uninstall` that restores the original `fetch`. */
+    enableFetchCapture(): () => void;
+    /** Start a custom trace; the returned handle records a `custom` item on
+     * `.stop()`. */
+    startTrace(name: string): PerfTrace;
+    /** Buffer one perf item. In the browser, flush on size/timer; on the server
+     * flush immediately (no timers). Never throws.
+     *
+     * Client-side remote sampling: an item whose deterministic `row_id` bucket is
+     * NOT below the server-controlled `samplePct` is dropped before buffering —
+     * the SAME FNV-1a-mod-100 decision the server applies at ingest, so the two
+     * keep identical rows and the SDK saves the upload (defense-in-depth: the
+     * server re-samples authoritatively). */
+    record(item: PerfItem): void;
+    /** Buffer a network trace — called by `request.ts` around `rt.http.request`
+     * (the analytics ingest path is excluded by the caller to avoid recursion). */
+    recordNetwork(method: string, url: string, status: number, durationMs: number, requestId?: string): void;
+    /** Drain the offline queue (oldest-first) and the live buffer to
+     * `/v1/analytics/perf` (≤100 items per request, sequential). Resolves when
+     * delivery finished; NEVER rejects. A failed slice is NOT dropped — it goes
+     * to the offline queue (persist-on-fail) so the next flush (size/timer or the
+     * `online` reconnect event) retries it. Items keep their original `row_id`,
+     * so a redelivery dedups server-side (ReplacingMergeTree). */
+    flush(): Promise<void>;
+    private startTimer;
+    private cancelTimer;
+}
+
 /**
  * The connection state of the shared realtime WebSocket (iOS enum parity), plus
  * `'error'` — surfaced when a channel could not be recovered after a
@@ -1471,6 +1690,14 @@ declare class PalbeRealtime {
 
 interface PalbeRuntime {
     config: PalbeConfig;
+    /**
+     * F2 app-registration: the registered app `identifier` (web ORIGIN) stashed at
+     * configure. Rides on `X-Palbase-Bundle` on EVERY request (request.ts) so the
+     * Kong gate can match it. Empty string when the binding is unconfigured/tooling
+     * (no header is sent). Origin-match is enforced in `buildRuntime` BEFORE this
+     * runtime is returned — a mismatch throws there and no runtime is built.
+     */
+    appIdentifier: string;
     http: HttpClient$1;
     tokenManager: TokenManager$1;
     authClient: AuthClient;
@@ -1480,6 +1707,13 @@ interface PalbeRuntime {
     analytics: PalbeAnalytics;
     calls: PalbeCalls;
     messaging: PalbeMessaging;
+    /**
+     * PalPerf surface. EAGER (like analytics identity): `request.ts` records a
+     * `network` trace around EVERY SDK fetch, so the facade must exist from the
+     * first request — never lazy. The buffer/timer it owns is inert until the
+     * first item is recorded.
+     */
+    perf: PalbePerf;
     storage: SessionStorageAdapter;
     /**
      * Destroy the realtime facade if it was already constructed (no-op otherwise).
@@ -1731,4 +1965,4 @@ declare class PalbeAnalytics {
     private post;
 }
 
-export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type PalbeRuntime as N, type OAuthExchangeResult as O, PalbeAnalytics as P, buildRuntime as Q, RealtimeChannel as R, type SentReceipt as S, type Unsubscribe as U, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };
+export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type NotifyScope as N, type OAuthExchangeResult as O, PalbeAnalytics as P, type Unsubscribe as Q, RealtimeChannel as R, type SentReceipt as S, type PalbeRuntime as T, type UnreadView as U, buildRuntime as V, PalbePerf as W, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };