@calimero-network/mero-react 5.0.0 → 6.0.0

package/dist/index.d.cts

@@ -2,9 +2,9 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import React__default, { CSSProperties, ReactNode } from 'react';
 import * as _calimero_network_mero_js from '@calimero-network/mero-js';
-import { MeroJs, TokenStore, SetMetadataRequest, SseEventData, GroupMembershipEventData, GroupMigrationEventData, AddGroupMembersRequest, CreateContextRequest, CreateGroupInNamespaceRequest, CreateNamespaceRequest, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, DeleteGroupRequest, DeleteNamespaceRequest, DetachContextFromGroupRequest, GroupUpgradeStatusResponseData, GroupContextEntry, GroupInfo, CreateGroupInvitationRequest, MetadataRecord, JoinGroupRequest, JoinNamespaceRequest, MigrationStatus, MigrationStatusRollup, MemberMigrationStatusEntry, MigrateMyEntriesSummary, Namespace, SubgroupEntry, NamespaceIdentity, RemoveGroupMembersRequest, ReparentGroupRequest, ResyncContextRequest, RetryGroupUpgradeRequest, SetDefaultCapabilitiesRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, SyncGroupRequest, UpdateMemberRoleRequest, UpgradeGroupRequest, TokenData } from '@calimero-network/mero-js';
+import { MeroJs, TokenStore, SetMetadataRequest, SseEventData, GroupMembershipEventData, GroupMigrationEventData, Codec, AddGroupMembersRequest, CreateContextRequest, CreateGroupInNamespaceRequest, CreateNamespaceRequest, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, DeleteGroupRequest, DeleteNamespaceRequest, DetachContextFromGroupRequest, GroupUpgradeStatusResponseData, GroupContextEntry, GroupInfo, CreateGroupInvitationRequest, MetadataRecord, JoinGroupRequest, JoinNamespaceRequest, MigrationStatus, MigrationStatusRollup, MemberMigrationStatusEntry, MigrateMyEntriesSummary, Namespace, SubgroupEntry, NamespaceIdentity, NodeIdentity, RemoveGroupMembersRequest, ReparentGroupRequest, ResyncContextRequest, RetryGroupUpgradeRequest, SetDefaultCapabilitiesRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, SyncGroupRequest, UpdateMemberRoleRequest, UpgradeGroupRequest, TokenData } from '@calimero-network/mero-js';
 export * from '@calimero-network/mero-js';
-export { CAPABILITIES, DEFAULT_LOCAL_NODE_PORTS, DiscoverLocalNodesOptions, MetadataRecord, discoverLocalNodes, hasCap, localNodeUrl, nodeEndpoint, probeNodeHealth, withCap, withoutCap } from '@calimero-network/mero-js';
+export { CAPABILITIES, Codec, DEFAULT_LOCAL_NODE_PORTS, DiscoverLocalNodesOptions, EphemeralClient, EphemeralEntry, MetadataRecord, discoverLocalNodes, hasCap, localNodeUrl, nodeEndpoint, probeNodeHealth, withCap, withoutCap } from '@calimero-network/mero-js';
 
 /**
  * Types for mero-react
@@ -336,6 +336,50 @@ interface MigrationAdminPanelProps {
  */
 declare function MigrationAdminPanel({ namespaceId, pollIntervalMs, className }: MigrationAdminPanelProps): react_jsx_runtime.JSX.Element;
 
+interface UseEphemeralOptions<T> {
+    /** Encoding for the presence slice. Defaults to JSON. */
+    codec?: Codec<T>;
+    /** Base value for the first `setPresence` merge. */
+    initial?: T;
+    /** Minimum ms between publishes. Trailing edge — the latest value wins. */
+    throttleMs?: number;
+    /** Include your own echoed presence in `peers`. Default false. */
+    includeSelf?: boolean;
+}
+/** Shape returned by {@link useEphemeral}. */
+interface UseEphemeralResult<T> {
+    peers: Map<string, T>;
+    setPresence: (partial: Partial<T>) => void;
+    ageOf: (author: string) => number | undefined;
+    error: Error | null;
+}
+/**
+ * Observe and publish ephemeral presence (cursors, typing, online) for a
+ * context.
+ *
+ * ONE read path: the subscription. When a client subscribes, the node replays
+ * that context's current presence to that connection as ordinary entries
+ * before the live deltas start, so seeding and updating share a single shape
+ * ({@link EphemeralEntry}) and a reconnect — `SseClient` auto-reconnects and
+ * re-subscribes — re-seeds itself. There is no snapshot fetch and no
+ * client-side reconciliation pass.
+ *
+ * Freshness is computed entirely from local clock deltas: a replayed entry is
+ * current as of `Date.now() - ageMs`, a live delta as of `Date.now()`. No
+ * cross-machine clock comparison is ever performed.
+ *
+ * No client-side TTL or heartbeat: the node sweeps at 7s and emits removals,
+ * and re-publishes on your behalf every 2.5s. A replay is treated as
+ * AUTHORITATIVE — see the replay-reconcile pass in the read effect — so a peer
+ * swept while the SSE connection was down does not survive the reconnect.
+ *
+ * `error` is derived, not accumulated: standing conditions (no `ephemeral`
+ * surface) are recomputed every render, one-shot async failures are latched
+ * keyed by the context they happened in, and whether a latched failure is even
+ * relevant (an unresolved identity when `includeSelf` is true) is decided at
+ * read time. Nothing survives a context switch.
+ */
+declare function useEphemeral<T>(contextId: string | null, options?: UseEphemeralOptions<T>): UseEphemeralResult<T>;
 /**
  * Shape accepted by the metadata-setter hooks — re-exported from mero-js so
  * callers have one canonical type. A `set*Metadata` call **replaces the whole
@@ -403,6 +447,11 @@ declare function useJoinGroup(): {
     loading: boolean;
     error: Error | null;
 };
+/**
+ * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
+ * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
+ * Both are 32-byte strings, so passing a key names nobody and raises nothing.
+ */
 declare function useGroupCapabilities(groupId?: string | null, memberId?: string | null): {
     capabilities: number | null;
     loading: boolean;
@@ -453,11 +502,22 @@ declare function useSyncGroup(): {
     loading: boolean;
     error: Error | null;
 };
+/**
+ * Takes the invitee's signing KEY (bs58) - the one call on this resource that
+ * does, because someone being added may have no account here yet. Every other
+ * member call, including `useRemoveGroupMembers`, takes the ACCOUNT, so a value
+ * round-tripped from an add is the wrong one to remove with.
+ */
 declare function useAddGroupMembers(): {
     addGroupMembers: (groupId: string, request: AddGroupMembersRequest) => Promise<void | null>;
     loading: boolean;
     error: Error | null;
 };
+/**
+ * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
+ * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
+ * Both are 32-byte strings, so passing a key names nobody and raises nothing.
+ */
 declare function useRemoveGroupMembers(): {
     removeGroupMembers: (groupId: string, request: RemoveGroupMembersRequest) => Promise<void | null>;
     loading: boolean;
@@ -475,6 +535,24 @@ declare function useNamespace(namespaceId?: string | null): {
     error: Error | null;
     refetch: () => Promise<void>;
 };
+/**
+ * Who this node is: `accountId` is what member-addressing takes and what
+ * `useGroupMembers` rows are keyed by — `publicKey` is the signing key and
+ * addresses nobody. Both are 32-byte strings, so a swap fails silently.
+ */
+declare function useNodeIdentity(): {
+    identity: NodeIdentity | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * @deprecated Use {@link useNodeIdentity}. Identity is per-node, not
+ * per-namespace, and this no longer gates on participation: it answers for a
+ * namespace this node never joined, so `identity != null` is not "am I a
+ * member?" — ask `useNamespaces` for that. Its `publicKey` is the signing key,
+ * NOT the account member-addressing wants.
+ */
 declare function useNamespaceIdentity(namespaceId?: string | null): {
     identity: NamespaceIdentity | null;
     loading: boolean;
@@ -518,6 +596,11 @@ declare function useNamespaceGroups(namespaceId?: string | null): {
     error: Error | null;
     refetch: () => Promise<void>;
 };
+/**
+ * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
+ * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
+ * Both are 32-byte strings, so passing a key names nobody and raises nothing.
+ */
 declare function useUpdateMemberRole(): {
     updateMemberRole: (groupId: string, identity: string, request: UpdateMemberRoleRequest) => Promise<void | null>;
     loading: boolean;
@@ -555,6 +638,11 @@ declare function useSetGroupMetadata(): {
     loading: boolean;
     error: Error | null;
 };
+/**
+ * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
+ * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
+ * Both are 32-byte strings, so passing a key names nobody and raises nothing.
+ */
 declare function useSetMemberMetadata(): {
     setMemberMetadata: (groupId: string, identity: string, request: SetMetadataInput) => Promise<void | null>;
     loading: boolean;
@@ -632,9 +720,31 @@ declare function useDetachContextFromGroup(): {
     error: Error | null;
 };
 /**
- * Migration-status rollup for a namespace (skew #3). Migration facts arrive via
- * heartbeat gossip (no SSE), so liveness is polling: pass `pollIntervalMs` to
- * re-fetch on an interval. Derived counters are null-safe before the first load.
+ * Subscribe to a namespace's `GroupMigration` events, invoking `onEvent` per
+ * frame and unsubscribing on unmount.
+ *
+ * A non-admin subscriber never sees `CascadeProgress`; core delivers that to
+ * namespace admins only, so a UI must not wait on it to decide progress.
+ */
+/**
+ * Fallback poll cadence for `useMigrationStatus` when the SSE stream is
+ * unavailable (no token, a proxy that buffers, an older node) and the caller
+ * named no interval of its own. Chosen to match the heartbeat cadence that
+ * migration facts actually arrive on; an explicit `pollIntervalMs` overrides it.
+ */
+declare const DEFAULT_MIGRATION_POLL_INTERVAL_MS = 5000;
+declare function useMigrationEvents(namespaceId: string | null | undefined, onEvent: (event: GroupMigrationEventData) => void): boolean;
+/**
+ * Migration-status rollup for a namespace (skew #3).
+ *
+ * Live: subscribes to the `GroupMigration` event family and re-reads on each
+ * frame. It re-READS rather than folding the event's counters in, because the
+ * rollup is recomputed from raw member rows and is the authoritative answer.
+ * `pollIntervalMs` stays as the fallback when SSE is unavailable, and when the
+ * caller names none it defaults to `DEFAULT_MIGRATION_POLL_INTERVAL_MS` for
+ * exactly as long as the stream is down - so the panel can never sit silently
+ * frozen with neither transport.
+ * Derived counters are null-safe before the first load.
  */
 declare function useMigrationStatus(namespaceId?: string | null, options?: {
     pollIntervalMs?: number;
@@ -643,6 +753,12 @@ declare function useMigrationStatus(namespaceId?: string | null, options?: {
     rollup: MigrationStatusRollup | null;
     members: MemberMigrationStatusEntry[];
     allMigrated: boolean;
+    /**
+     * When this node watched the fleet converge, or `null`. Durable, unlike
+     * `allMigrated`, which is recomputed from in-TTL heartbeats and lapses back
+     * to false when a member simply goes quiet.
+     */
+    fleetCompletedAt: number | null;
     membersPendingSignature: number;
     /** Members whose migrate aborted (migration-check failed or apply errored). */
     failed: number;
@@ -707,7 +823,6 @@ declare function useGroupAppVersion(groupId?: string): {
     applicationId: string | null;
     /** The installed blob differs from the one the group targets (see hook doc). */
     pendingApply: boolean;
-    upgradePolicy: string | null;
     /** Only populated via the group-info path; `null` in the namespace path. */
     activeUpgrade: GroupUpgradeStatusResponseData;
 };
@@ -803,4 +918,4 @@ declare function clearContextIdentity(): void;
  */
 declare function clearAllStorage(): void;
 
-export { type AppContext, AppMode, type ApplicationContextRecord, CalimeroLogo, type CalimeroLogoProps, ConnectButton, type ConnectButtonProps, ConnectionType, type ContextDiscoveryOptions, type ContextDiscoveryState, type CustomConnectionConfig, type ExecutionResult, LoginModal, type LoginModalProps, MERO_CSS_VARS, MeroContext, type MeroContextValue, MeroProvider, type MeroProviderConfig, type MeroProviderProps, type MeroTheme, MigrationAdminPanel, type MigrationAdminPanelProps, MigrationPendingBanner, type MigrationPendingBannerProps, type ResolvedMeroTheme, type SetMetadataInput, type SubscriptionEventData, type SubscriptionInput, clearAllStorage, clearApplicationId, clearContextId, clearContextIdentity, clearNodeUrl, clearTokenNodeUrl, cssVar, defaultMeroTheme, getApplicationId, getContextId, getContextIdentity, getNodeUrl, getTokenNodeUrl, localStorageTokenStorage, resolveMeroTheme, setApplicationId, setContextId, setContextIdentity, setNodeUrl, setTokenNodeUrl, themeToCssVars, useAddGroupMembers, useAppVersion, useApplicationContexts, useContextDiscovery, useContextGroup, useContexts, useCreateContext, useCreateGroupInNamespace, useCreateNamespace, useCreateNamespaceInvitation, useDefaultCapabilities, useDeleteContext, useDeleteGroup, useDeleteNamespace, useDetachContextFromGroup, useExecute, useGroupAppVersion, useGroupCapabilities, useGroupContexts, useGroupInfo, useGroupInvitations, useGroupMembers, useGroupMetadata, useGroupUpgradeStatus, useInstallFromRegistry, useJoinContext, useJoinGroup, useJoinNamespace, useJoinSubgroupInheritance, useLatestVersion, useMemberMetadata, useMero, useMigrationStatus, useMyAuthoredMigration, useNamespace, useNamespaceGroups, useNamespaceIdentity, useNamespaces, useNamespacesForApplication, useRemoveGroupMembers, useReparentGroup, useResyncContext, useRetryGroupUpgrade, useSetContextMetadata, useSetDefaultCapabilities, useSetGroupMetadata, useSetMemberMetadata, useSetSubgroupVisibility, useSetTeeAdmissionPolicy, useSubgroupVisibility, useSubgroups, useSubscription, useSyncGroup, useUpdateMemberRole, useUpgradeGroup };
+export { type AppContext, AppMode, type ApplicationContextRecord, CalimeroLogo, type CalimeroLogoProps, ConnectButton, type ConnectButtonProps, ConnectionType, type ContextDiscoveryOptions, type ContextDiscoveryState, type CustomConnectionConfig, DEFAULT_MIGRATION_POLL_INTERVAL_MS, type ExecutionResult, LoginModal, type LoginModalProps, MERO_CSS_VARS, MeroContext, type MeroContextValue, MeroProvider, type MeroProviderConfig, type MeroProviderProps, type MeroTheme, MigrationAdminPanel, type MigrationAdminPanelProps, MigrationPendingBanner, type MigrationPendingBannerProps, type ResolvedMeroTheme, type SetMetadataInput, type SubscriptionEventData, type SubscriptionInput, type UseEphemeralOptions, type UseEphemeralResult, clearAllStorage, clearApplicationId, clearContextId, clearContextIdentity, clearNodeUrl, clearTokenNodeUrl, cssVar, defaultMeroTheme, getApplicationId, getContextId, getContextIdentity, getNodeUrl, getTokenNodeUrl, localStorageTokenStorage, resolveMeroTheme, setApplicationId, setContextId, setContextIdentity, setNodeUrl, setTokenNodeUrl, themeToCssVars, useAddGroupMembers, useAppVersion, useApplicationContexts, useContextDiscovery, useContextGroup, useContexts, useCreateContext, useCreateGroupInNamespace, useCreateNamespace, useCreateNamespaceInvitation, useDefaultCapabilities, useDeleteContext, useDeleteGroup, useDeleteNamespace, useDetachContextFromGroup, useEphemeral, useExecute, useGroupAppVersion, useGroupCapabilities, useGroupContexts, useGroupInfo, useGroupInvitations, useGroupMembers, useGroupMetadata, useGroupUpgradeStatus, useInstallFromRegistry, useJoinContext, useJoinGroup, useJoinNamespace, useJoinSubgroupInheritance, useLatestVersion, useMemberMetadata, useMero, useMigrationEvents, useMigrationStatus, useMyAuthoredMigration, useNamespace, useNamespaceGroups, useNamespaceIdentity, useNamespaces, useNamespacesForApplication, useNodeIdentity, useRemoveGroupMembers, useReparentGroup, useResyncContext, useRetryGroupUpgrade, useSetContextMetadata, useSetDefaultCapabilities, useSetGroupMetadata, useSetMemberMetadata, useSetSubgroupVisibility, useSetTeeAdmissionPolicy, useSubgroupVisibility, useSubgroups, useSubscription, useSyncGroup, useUpdateMemberRole, useUpgradeGroup };

package/dist/index.d.ts

@@ -2,9 +2,9 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import React__default, { CSSProperties, ReactNode } from 'react';
 import * as _calimero_network_mero_js from '@calimero-network/mero-js';
-import { MeroJs, TokenStore, SetMetadataRequest, SseEventData, GroupMembershipEventData, GroupMigrationEventData, AddGroupMembersRequest, CreateContextRequest, CreateGroupInNamespaceRequest, CreateNamespaceRequest, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, DeleteGroupRequest, DeleteNamespaceRequest, DetachContextFromGroupRequest, GroupUpgradeStatusResponseData, GroupContextEntry, GroupInfo, CreateGroupInvitationRequest, MetadataRecord, JoinGroupRequest, JoinNamespaceRequest, MigrationStatus, MigrationStatusRollup, MemberMigrationStatusEntry, MigrateMyEntriesSummary, Namespace, SubgroupEntry, NamespaceIdentity, RemoveGroupMembersRequest, ReparentGroupRequest, ResyncContextRequest, RetryGroupUpgradeRequest, SetDefaultCapabilitiesRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, SyncGroupRequest, UpdateMemberRoleRequest, UpgradeGroupRequest, TokenData } from '@calimero-network/mero-js';
+import { MeroJs, TokenStore, SetMetadataRequest, SseEventData, GroupMembershipEventData, GroupMigrationEventData, Codec, AddGroupMembersRequest, CreateContextRequest, CreateGroupInNamespaceRequest, CreateNamespaceRequest, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, DeleteGroupRequest, DeleteNamespaceRequest, DetachContextFromGroupRequest, GroupUpgradeStatusResponseData, GroupContextEntry, GroupInfo, CreateGroupInvitationRequest, MetadataRecord, JoinGroupRequest, JoinNamespaceRequest, MigrationStatus, MigrationStatusRollup, MemberMigrationStatusEntry, MigrateMyEntriesSummary, Namespace, SubgroupEntry, NamespaceIdentity, NodeIdentity, RemoveGroupMembersRequest, ReparentGroupRequest, ResyncContextRequest, RetryGroupUpgradeRequest, SetDefaultCapabilitiesRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, SyncGroupRequest, UpdateMemberRoleRequest, UpgradeGroupRequest, TokenData } from '@calimero-network/mero-js';
 export * from '@calimero-network/mero-js';
-export { CAPABILITIES, DEFAULT_LOCAL_NODE_PORTS, DiscoverLocalNodesOptions, MetadataRecord, discoverLocalNodes, hasCap, localNodeUrl, nodeEndpoint, probeNodeHealth, withCap, withoutCap } from '@calimero-network/mero-js';
+export { CAPABILITIES, Codec, DEFAULT_LOCAL_NODE_PORTS, DiscoverLocalNodesOptions, EphemeralClient, EphemeralEntry, MetadataRecord, discoverLocalNodes, hasCap, localNodeUrl, nodeEndpoint, probeNodeHealth, withCap, withoutCap } from '@calimero-network/mero-js';
 
 /**
  * Types for mero-react
@@ -336,6 +336,50 @@ interface MigrationAdminPanelProps {
  */
 declare function MigrationAdminPanel({ namespaceId, pollIntervalMs, className }: MigrationAdminPanelProps): react_jsx_runtime.JSX.Element;
 
+interface UseEphemeralOptions<T> {
+    /** Encoding for the presence slice. Defaults to JSON. */
+    codec?: Codec<T>;
+    /** Base value for the first `setPresence` merge. */
+    initial?: T;
+    /** Minimum ms between publishes. Trailing edge — the latest value wins. */
+    throttleMs?: number;
+    /** Include your own echoed presence in `peers`. Default false. */
+    includeSelf?: boolean;
+}
+/** Shape returned by {@link useEphemeral}. */
+interface UseEphemeralResult<T> {
+    peers: Map<string, T>;
+    setPresence: (partial: Partial<T>) => void;
+    ageOf: (author: string) => number | undefined;
+    error: Error | null;
+}
+/**
+ * Observe and publish ephemeral presence (cursors, typing, online) for a
+ * context.
+ *
+ * ONE read path: the subscription. When a client subscribes, the node replays
+ * that context's current presence to that connection as ordinary entries
+ * before the live deltas start, so seeding and updating share a single shape
+ * ({@link EphemeralEntry}) and a reconnect — `SseClient` auto-reconnects and
+ * re-subscribes — re-seeds itself. There is no snapshot fetch and no
+ * client-side reconciliation pass.
+ *
+ * Freshness is computed entirely from local clock deltas: a replayed entry is
+ * current as of `Date.now() - ageMs`, a live delta as of `Date.now()`. No
+ * cross-machine clock comparison is ever performed.
+ *
+ * No client-side TTL or heartbeat: the node sweeps at 7s and emits removals,
+ * and re-publishes on your behalf every 2.5s. A replay is treated as
+ * AUTHORITATIVE — see the replay-reconcile pass in the read effect — so a peer
+ * swept while the SSE connection was down does not survive the reconnect.
+ *
+ * `error` is derived, not accumulated: standing conditions (no `ephemeral`
+ * surface) are recomputed every render, one-shot async failures are latched
+ * keyed by the context they happened in, and whether a latched failure is even
+ * relevant (an unresolved identity when `includeSelf` is true) is decided at
+ * read time. Nothing survives a context switch.
+ */
+declare function useEphemeral<T>(contextId: string | null, options?: UseEphemeralOptions<T>): UseEphemeralResult<T>;
 /**
  * Shape accepted by the metadata-setter hooks — re-exported from mero-js so
  * callers have one canonical type. A `set*Metadata` call **replaces the whole
@@ -403,6 +447,11 @@ declare function useJoinGroup(): {
     loading: boolean;
     error: Error | null;
 };
+/**
+ * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
+ * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
+ * Both are 32-byte strings, so passing a key names nobody and raises nothing.
+ */
 declare function useGroupCapabilities(groupId?: string | null, memberId?: string | null): {
     capabilities: number | null;
     loading: boolean;
@@ -453,11 +502,22 @@ declare function useSyncGroup(): {
     loading: boolean;
     error: Error | null;
 };
+/**
+ * Takes the invitee's signing KEY (bs58) - the one call on this resource that
+ * does, because someone being added may have no account here yet. Every other
+ * member call, including `useRemoveGroupMembers`, takes the ACCOUNT, so a value
+ * round-tripped from an add is the wrong one to remove with.
+ */
 declare function useAddGroupMembers(): {
     addGroupMembers: (groupId: string, request: AddGroupMembersRequest) => Promise<void | null>;
     loading: boolean;
     error: Error | null;
 };
+/**
+ * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
+ * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
+ * Both are 32-byte strings, so passing a key names nobody and raises nothing.
+ */
 declare function useRemoveGroupMembers(): {
     removeGroupMembers: (groupId: string, request: RemoveGroupMembersRequest) => Promise<void | null>;
     loading: boolean;
@@ -475,6 +535,24 @@ declare function useNamespace(namespaceId?: string | null): {
     error: Error | null;
     refetch: () => Promise<void>;
 };
+/**
+ * Who this node is: `accountId` is what member-addressing takes and what
+ * `useGroupMembers` rows are keyed by — `publicKey` is the signing key and
+ * addresses nobody. Both are 32-byte strings, so a swap fails silently.
+ */
+declare function useNodeIdentity(): {
+    identity: NodeIdentity | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * @deprecated Use {@link useNodeIdentity}. Identity is per-node, not
+ * per-namespace, and this no longer gates on participation: it answers for a
+ * namespace this node never joined, so `identity != null` is not "am I a
+ * member?" — ask `useNamespaces` for that. Its `publicKey` is the signing key,
+ * NOT the account member-addressing wants.
+ */
 declare function useNamespaceIdentity(namespaceId?: string | null): {
     identity: NamespaceIdentity | null;
     loading: boolean;
@@ -518,6 +596,11 @@ declare function useNamespaceGroups(namespaceId?: string | null): {
     error: Error | null;
     refetch: () => Promise<void>;
 };
+/**
+ * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
+ * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
+ * Both are 32-byte strings, so passing a key names nobody and raises nothing.
+ */
 declare function useUpdateMemberRole(): {
     updateMemberRole: (groupId: string, identity: string, request: UpdateMemberRoleRequest) => Promise<void | null>;
     loading: boolean;
@@ -555,6 +638,11 @@ declare function useSetGroupMetadata(): {
     loading: boolean;
     error: Error | null;
 };
+/**
+ * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
+ * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
+ * Both are 32-byte strings, so passing a key names nobody and raises nothing.
+ */
 declare function useSetMemberMetadata(): {
     setMemberMetadata: (groupId: string, identity: string, request: SetMetadataInput) => Promise<void | null>;
     loading: boolean;
@@ -632,9 +720,31 @@ declare function useDetachContextFromGroup(): {
     error: Error | null;
 };
 /**
- * Migration-status rollup for a namespace (skew #3). Migration facts arrive via
- * heartbeat gossip (no SSE), so liveness is polling: pass `pollIntervalMs` to
- * re-fetch on an interval. Derived counters are null-safe before the first load.
+ * Subscribe to a namespace's `GroupMigration` events, invoking `onEvent` per
+ * frame and unsubscribing on unmount.
+ *
+ * A non-admin subscriber never sees `CascadeProgress`; core delivers that to
+ * namespace admins only, so a UI must not wait on it to decide progress.
+ */
+/**
+ * Fallback poll cadence for `useMigrationStatus` when the SSE stream is
+ * unavailable (no token, a proxy that buffers, an older node) and the caller
+ * named no interval of its own. Chosen to match the heartbeat cadence that
+ * migration facts actually arrive on; an explicit `pollIntervalMs` overrides it.
+ */
+declare const DEFAULT_MIGRATION_POLL_INTERVAL_MS = 5000;
+declare function useMigrationEvents(namespaceId: string | null | undefined, onEvent: (event: GroupMigrationEventData) => void): boolean;
+/**
+ * Migration-status rollup for a namespace (skew #3).
+ *
+ * Live: subscribes to the `GroupMigration` event family and re-reads on each
+ * frame. It re-READS rather than folding the event's counters in, because the
+ * rollup is recomputed from raw member rows and is the authoritative answer.
+ * `pollIntervalMs` stays as the fallback when SSE is unavailable, and when the
+ * caller names none it defaults to `DEFAULT_MIGRATION_POLL_INTERVAL_MS` for
+ * exactly as long as the stream is down - so the panel can never sit silently
+ * frozen with neither transport.
+ * Derived counters are null-safe before the first load.
  */
 declare function useMigrationStatus(namespaceId?: string | null, options?: {
     pollIntervalMs?: number;
@@ -643,6 +753,12 @@ declare function useMigrationStatus(namespaceId?: string | null, options?: {
     rollup: MigrationStatusRollup | null;
     members: MemberMigrationStatusEntry[];
     allMigrated: boolean;
+    /**
+     * When this node watched the fleet converge, or `null`. Durable, unlike
+     * `allMigrated`, which is recomputed from in-TTL heartbeats and lapses back
+     * to false when a member simply goes quiet.
+     */
+    fleetCompletedAt: number | null;
     membersPendingSignature: number;
     /** Members whose migrate aborted (migration-check failed or apply errored). */
     failed: number;
@@ -707,7 +823,6 @@ declare function useGroupAppVersion(groupId?: string): {
     applicationId: string | null;
     /** The installed blob differs from the one the group targets (see hook doc). */
     pendingApply: boolean;
-    upgradePolicy: string | null;
     /** Only populated via the group-info path; `null` in the namespace path. */
     activeUpgrade: GroupUpgradeStatusResponseData;
 };
@@ -803,4 +918,4 @@ declare function clearContextIdentity(): void;
  */
 declare function clearAllStorage(): void;
 
-export { type AppContext, AppMode, type ApplicationContextRecord, CalimeroLogo, type CalimeroLogoProps, ConnectButton, type ConnectButtonProps, ConnectionType, type ContextDiscoveryOptions, type ContextDiscoveryState, type CustomConnectionConfig, type ExecutionResult, LoginModal, type LoginModalProps, MERO_CSS_VARS, MeroContext, type MeroContextValue, MeroProvider, type MeroProviderConfig, type MeroProviderProps, type MeroTheme, MigrationAdminPanel, type MigrationAdminPanelProps, MigrationPendingBanner, type MigrationPendingBannerProps, type ResolvedMeroTheme, type SetMetadataInput, type SubscriptionEventData, type SubscriptionInput, clearAllStorage, clearApplicationId, clearContextId, clearContextIdentity, clearNodeUrl, clearTokenNodeUrl, cssVar, defaultMeroTheme, getApplicationId, getContextId, getContextIdentity, getNodeUrl, getTokenNodeUrl, localStorageTokenStorage, resolveMeroTheme, setApplicationId, setContextId, setContextIdentity, setNodeUrl, setTokenNodeUrl, themeToCssVars, useAddGroupMembers, useAppVersion, useApplicationContexts, useContextDiscovery, useContextGroup, useContexts, useCreateContext, useCreateGroupInNamespace, useCreateNamespace, useCreateNamespaceInvitation, useDefaultCapabilities, useDeleteContext, useDeleteGroup, useDeleteNamespace, useDetachContextFromGroup, useExecute, useGroupAppVersion, useGroupCapabilities, useGroupContexts, useGroupInfo, useGroupInvitations, useGroupMembers, useGroupMetadata, useGroupUpgradeStatus, useInstallFromRegistry, useJoinContext, useJoinGroup, useJoinNamespace, useJoinSubgroupInheritance, useLatestVersion, useMemberMetadata, useMero, useMigrationStatus, useMyAuthoredMigration, useNamespace, useNamespaceGroups, useNamespaceIdentity, useNamespaces, useNamespacesForApplication, useRemoveGroupMembers, useReparentGroup, useResyncContext, useRetryGroupUpgrade, useSetContextMetadata, useSetDefaultCapabilities, useSetGroupMetadata, useSetMemberMetadata, useSetSubgroupVisibility, useSetTeeAdmissionPolicy, useSubgroupVisibility, useSubgroups, useSubscription, useSyncGroup, useUpdateMemberRole, useUpgradeGroup };
+export { type AppContext, AppMode, type ApplicationContextRecord, CalimeroLogo, type CalimeroLogoProps, ConnectButton, type ConnectButtonProps, ConnectionType, type ContextDiscoveryOptions, type ContextDiscoveryState, type CustomConnectionConfig, DEFAULT_MIGRATION_POLL_INTERVAL_MS, type ExecutionResult, LoginModal, type LoginModalProps, MERO_CSS_VARS, MeroContext, type MeroContextValue, MeroProvider, type MeroProviderConfig, type MeroProviderProps, type MeroTheme, MigrationAdminPanel, type MigrationAdminPanelProps, MigrationPendingBanner, type MigrationPendingBannerProps, type ResolvedMeroTheme, type SetMetadataInput, type SubscriptionEventData, type SubscriptionInput, type UseEphemeralOptions, type UseEphemeralResult, clearAllStorage, clearApplicationId, clearContextId, clearContextIdentity, clearNodeUrl, clearTokenNodeUrl, cssVar, defaultMeroTheme, getApplicationId, getContextId, getContextIdentity, getNodeUrl, getTokenNodeUrl, localStorageTokenStorage, resolveMeroTheme, setApplicationId, setContextId, setContextIdentity, setNodeUrl, setTokenNodeUrl, themeToCssVars, useAddGroupMembers, useAppVersion, useApplicationContexts, useContextDiscovery, useContextGroup, useContexts, useCreateContext, useCreateGroupInNamespace, useCreateNamespace, useCreateNamespaceInvitation, useDefaultCapabilities, useDeleteContext, useDeleteGroup, useDeleteNamespace, useDetachContextFromGroup, useEphemeral, useExecute, useGroupAppVersion, useGroupCapabilities, useGroupContexts, useGroupInfo, useGroupInvitations, useGroupMembers, useGroupMetadata, useGroupUpgradeStatus, useInstallFromRegistry, useJoinContext, useJoinGroup, useJoinNamespace, useJoinSubgroupInheritance, useLatestVersion, useMemberMetadata, useMero, useMigrationEvents, useMigrationStatus, useMyAuthoredMigration, useNamespace, useNamespaceGroups, useNamespaceIdentity, useNamespaces, useNamespacesForApplication, useNodeIdentity, useRemoveGroupMembers, useReparentGroup, useResyncContext, useRetryGroupUpgrade, useSetContextMetadata, useSetDefaultCapabilities, useSetGroupMetadata, useSetMemberMetadata, useSetSubgroupVisibility, useSetTeeAdmissionPolicy, useSubgroupVisibility, useSubgroups, useSubscription, useSyncGroup, useUpdateMemberRole, useUpgradeGroup };