@agent-native/core 0.211.0 → 0.212.0-nightly-20261021010049

package/dist/client/sharing/share-controller-helpers.d.ts

@@ -44,9 +44,22 @@ export declare function useShareMutations(): {
     share: import("@tanstack/react-query").UseMutationResult<any, Error, Record<string, any>, unknown>;
     unshare: import("@tanstack/react-query").UseMutationResult<any, Error, Record<string, any>, unknown>;
 };
+/**
+ * Chat history lists are cached outside the share query, so a saved grant or
+ * visibility change must tell them to refetch. Other resource types have no
+ * such list to refresh.
+ */
+export declare function notifyShareChanged(resourceType: string): void;
 export declare function optimisticallyUpdateShareCache<TData>(queryClient: QueryClient, queryKey: ShareQueryKey, updater: (previous: TData | undefined) => TData | undefined): TData | undefined;
 export declare function rollbackShareCache<TData>(queryClient: QueryClient, queryKey: ShareQueryKey, previous: TData | undefined): void;
-export declare function useShareMutationGuard(): {
+export declare function optimisticallyUpdateShareVisibility<TData extends {
+    visibility: string | null;
+}>(queryClient: QueryClient, queryKey: ShareQueryKey, visibility: TData["visibility"]): {
+    isCurrent: () => boolean;
+    commit: (next: TData["visibility"]) => void;
+    rollback: () => void;
+};
+export declare function useShareMutationGuard(scope?: string): {
     begin: () => number;
     isLatest: (requestId: number) => boolean;
 };

package/dist/client/sharing/share-controller-helpers.js

@@ -2,6 +2,7 @@ import { useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { agentNativePath } from "../api-path.js";
 import { useActionMutation, useActionQuery } from "../use-action.js";
+import { notifyChatThreadsUpdated } from "../use-chat-threads.js";
 export const DEFAULT_MEMBER_SUGGESTION_LIMIT = 25;
 export const DEFAULT_MEMBER_SEARCH_DEBOUNCE_MS = 140;
 export function createShareQueryParams(resourceType, resourceId) {
@@ -27,6 +28,15 @@ export function useShareMutations() {
         unshare: useActionMutation("unshare-resource"),
     };
 }
+/**
+ * Chat history lists are cached outside the share query, so a saved grant or
+ * visibility change must tell them to refetch. Other resource types have no
+ * such list to refresh.
+ */
+export function notifyShareChanged(resourceType) {
+    if (resourceType === "chat_thread")
+        notifyChatThreadsUpdated();
+}
 export function optimisticallyUpdateShareCache(queryClient, queryKey, updater) {
     const previous = queryClient.getQueryData(queryKey);
     const next = updater(previous);
@@ -45,8 +55,43 @@ export function rollbackShareCache(queryClient, queryKey, previous) {
     }
     queryClient.setQueryData(queryKey, previous);
 }
-export function useShareMutationGuard() {
+// Ownership follows the cache entry, not the mounted surface. Weak keys also
+// retire it when a query is removed, without retaining resource ids forever.
+const visibilityCacheOwners = new WeakMap();
+export function optimisticallyUpdateShareVisibility(queryClient, queryKey, visibility) {
+    const cacheKey = queryKey;
+    const query = queryClient
+        .getQueryCache()
+        .build(queryClient, { queryKey: cacheKey });
+    const previous = queryClient.getQueryData(queryKey);
+    const owner = {};
+    visibilityCacheOwners.set(query, owner);
+    const isCurrent = () => queryClient.getQueryCache().find({ queryKey, exact: true }) === query &&
+        visibilityCacheOwners.get(query) === owner;
+    const commit = (next) => {
+        if (!isCurrent())
+            return;
+        queryClient.setQueryData(queryKey, (cached) => cached ? { ...cached, visibility: next } : cached);
+    };
+    commit(visibility);
+    return {
+        isCurrent,
+        commit,
+        rollback: () => {
+            if (previous &&
+                queryClient.getQueryData(queryKey)?.visibility === visibility) {
+                commit(previous.visibility);
+            }
+        },
+    };
+}
+export function useShareMutationGuard(scope) {
     const latestRequest = useRef(0);
+    const currentScope = useRef(scope);
+    if (currentScope.current !== scope) {
+        currentScope.current = scope;
+        latestRequest.current += 1;
+    }
     const begin = useCallback(() => {
         latestRequest.current += 1;
         return latestRequest.current;

package/dist/client/sharing/useShareButtonController.d.ts

@@ -1,4 +1,5 @@
 import { useActionQuery } from "../use-action.js";
+import { type ShareVisibilityTransition } from "./useShareVisibilityTransition.js";
 export type ShareButtonVisibility = "private" | "org" | "public";
 export type ShareButtonRole = "viewer" | "commenter" | "editor" | "admin";
 export interface ShareButtonShare {
@@ -68,7 +69,18 @@ export interface ShareButtonController {
     setInviteEmail: (email: string) => void;
     sharesQuery: ReturnType<typeof useActionQuery<ShareButtonSharesResponse>>;
     visibilityOverride: ShareButtonVisibility | null;
+    /**
+     * @deprecated Use `visibilityTransition.request`, which this calls. It
+     * resolves only once the change is persisted. A direct change rejects when
+     * its save fails. A private-to-Organization change stays pending through
+     * `visibilityTransition.confirm()` failures (retry is possible) and rejects
+     * with `ShareVisibilityNotSavedError` once it is cancelled or invalidated.
+     * Without manage rights it
+     * sets `shareError` and resolves, as it always has.
+     */
     handleVisibilityChange: (visibility: ShareButtonVisibility) => Promise<void>;
+    /** Request, confirm and cancel a visibility change that needs confirming. */
+    visibilityTransition: ShareVisibilityTransition;
     data: ShareButtonSharesResponse | undefined;
     policy: {
         allowPublic: boolean;

package/dist/client/sharing/useShareButtonController.js

@@ -1,18 +1,25 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useActionQuery } from "../use-action.js";
-import { DEFAULT_MEMBER_SEARCH_DEBOUNCE_MS, DEFAULT_MEMBER_SUGGESTION_LIMIT, extractShareErrorMessage, optimisticallyUpdateShareCache, rollbackShareCache, useShareOrgMemberSearch, useShareMutationGuard, useShareMutations, useShareQuery, } from "./share-controller-helpers.js";
+import { DEFAULT_MEMBER_SEARCH_DEBOUNCE_MS, DEFAULT_MEMBER_SUGGESTION_LIMIT, extractShareErrorMessage, notifyShareChanged, optimisticallyUpdateShareCache, optimisticallyUpdateShareVisibility, rollbackShareCache, useShareOrgMemberSearch, useShareMutationGuard, useShareMutations, useShareQuery, } from "./share-controller-helpers.js";
+import { useShareVisibilityTransition, } from "./useShareVisibilityTransition.js";
 export function useShareButtonController(options) {
     const [open, setOpen] = useState(false);
     const [inviteEmail, setInviteEmail] = useState("");
     const [selectedGroup, setSelectedGroup] = useState(null);
     const shareTabDefaultValue = options.shareTabs?.defaultValue ?? "share";
     const [activeShareTab, setActiveShareTab] = useState(shareTabDefaultValue);
-    const [visibilityOverride, setVisibilityOverride] = useState(null);
-    const visibilitySequenceStartRef = useRef(null);
+    const resourceKey = `${options.resourceType}:${options.resourceId}`;
+    // Tied to the resource it was made for: a click that lands on a new resource
+    // before any effect runs must not see the previous resource's value.
+    const [visibilityOverrideState, setVisibilityOverrideState] = useState(null);
+    const visibilityOverride = visibilityOverrideState?.resourceKey === resourceKey
+        ? visibilityOverrideState.value
+        : null;
+    const clearVisibilityOverride = useCallback((key, token) => setVisibilityOverrideState((state) => state?.resourceKey === key && state.token === token ? null : state), []);
     const appliedDefaultOpenRef = useRef(false);
     const { queryKey: shareQueryKey, query: sharesQuery, queryClient, } = useShareQuery(options.resourceType, options.resourceId, open, 0);
     const { setVisibility, share, unshare } = useShareMutations();
-    const visibilityGuard = useShareMutationGuard();
+    const visibilityGuard = useShareMutationGuard(resourceKey);
     const data = sharesQuery.data;
     const canManage = data?.role === "owner" || data?.role === "admin";
     const [shareError, setShareError] = useState(null);
@@ -31,7 +38,6 @@ export function useShareButtonController(options) {
         setSelectedGroup(null);
         setShareMessage("");
         setMessageOpen(false);
-        visibilitySequenceStartRef.current = null;
     }, [options.resourceId, options.resourceType]);
     useEffect(() => {
         if (!options.defaultOpen || appliedDefaultOpenRef.current)
@@ -43,62 +49,52 @@ export function useShareButtonController(options) {
         setActiveShareTab(value);
         options.shareTabs?.onValueChange?.(value);
     }, [options.shareTabs]);
-    const handleVisibilityChange = useCallback((next) => {
+    const applyVisibility = useCallback(async (next) => {
         if (!canManage) {
             setShareError("Only owners and admins can change access.");
-            return Promise.resolve();
+            return;
         }
         const requestId = visibilityGuard.begin();
-        const previous = optimisticallyUpdateShareCache(queryClient, shareQueryKey, (prev) => (prev ? { ...prev, visibility: next } : prev));
-        visibilitySequenceStartRef.current ??= { visibility, shares: previous };
-        setVisibilityOverride(next);
-        return new Promise((resolve, reject) => {
-            setVisibility.mutate({
+        const token = {};
+        const mutation = optimisticallyUpdateShareVisibility(queryClient, shareQueryKey, next);
+        setVisibilityOverrideState({ resourceKey, token, value: next });
+        let result;
+        try {
+            // Settles for this call alone: per-call mutate callbacks are skipped
+            // once a newer call supersedes it or the observer unmounts.
+            result = await setVisibility.mutateAsync({
                 resourceType: options.resourceType,
                 resourceId: options.resourceId,
                 visibility: next,
-            }, {
-                onSuccess: (result) => {
-                    const resultVisibility = typeof result === "object" &&
-                        result !== null &&
-                        "visibility" in result &&
-                        result.visibility;
-                    if (visibilityGuard.isLatest(requestId)) {
-                        if (visibilitySequenceStartRef.current?.visibility ===
-                            "private" &&
-                            (resultVisibility === "org" || resultVisibility === "public")) {
-                            options.onShareSuccess?.();
-                        }
-                        optimisticallyUpdateShareCache(queryClient, shareQueryKey, (prev) => prev
-                            ? {
-                                ...prev,
-                                visibility: resultVisibility ?? next,
-                            }
-                            : prev);
-                    }
-                    sharesQuery
-                        .refetch()
-                        .then(() => resolve())
-                        .catch(reject)
-                        .finally(() => {
-                        if (visibilityGuard.isLatest(requestId)) {
-                            setVisibilityOverride(null);
-                            visibilitySequenceStartRef.current = null;
-                        }
-                    });
-                },
-                onError: (error) => {
-                    if (visibilityGuard.isLatest(requestId)) {
-                        const sequenceStart = visibilitySequenceStartRef.current;
-                        setVisibilityOverride(null);
-                        visibilitySequenceStartRef.current = null;
-                        rollbackShareCache(queryClient, shareQueryKey, sequenceStart ? sequenceStart.shares : previous);
-                        void sharesQuery.refetch();
-                    }
-                    reject(error);
-                },
             });
-        });
+        }
+        catch (error) {
+            mutation.rollback();
+            clearVisibilityOverride(resourceKey, token);
+            if (visibilityGuard.isLatest(requestId)) {
+                void sharesQuery.refetch();
+            }
+            throw error;
+        }
+        notifyShareChanged(options.resourceType);
+        const resultVisibility = typeof result === "object" &&
+            result !== null &&
+            "visibility" in result &&
+            result.visibility;
+        mutation.commit(resultVisibility ?? next);
+        if (visibilityGuard.isLatest(requestId)) {
+            if (visibility === "private" &&
+                (resultVisibility === "org" || resultVisibility === "public")) {
+                options.onShareSuccess?.();
+            }
+        }
+        try {
+            if (visibilityGuard.isLatest(requestId))
+                await sharesQuery.refetch();
+        }
+        finally {
+            clearVisibilityOverride(resourceKey, token);
+        }
     }, [
         options.resourceId,
         options.resourceType,
@@ -110,6 +106,8 @@ export function useShareButtonController(options) {
         visibilityGuard,
         options.onShareSuccess,
         visibility,
+        resourceKey,
+        clearVisibilityOverride,
     ]);
     const policy = data?.policy ?? {
         allowPublic: true,
@@ -187,6 +185,17 @@ export function useShareButtonController(options) {
         setSelectedGroup(group);
         setInviteEmail(group.name);
     }, []);
+    const visibilityTransition = useShareVisibilityTransition({
+        resourceType: options.resourceType,
+        resourceId: options.resourceId,
+        current: visibility,
+        orgId: data?.orgId ?? null,
+        canManage,
+        active: open,
+        apply: applyVisibility,
+        onDirectError: (error) => setShareError(extractShareErrorMessage(error)),
+    });
+    const requestVisibility = visibilityTransition.request;
     const handleVisibility = useCallback((next) => {
         if (next === visibility)
             return;
@@ -195,10 +204,16 @@ export function useShareButtonController(options) {
             return;
         }
         setShareError(null);
-        void handleVisibilityChange(next).catch((error) => {
-            setShareError(extractShareErrorMessage(error));
-        });
-    }, [canManage, handleVisibilityChange, visibility]);
+        void requestVisibility(next);
+    }, [canManage, requestVisibility, visibility]);
+    const handleVisibilityChange = useCallback((next) => {
+        if (!canManage) {
+            setShareError("Only owners and admins can change access.");
+            return Promise.resolve();
+        }
+        setShareError(null);
+        return requestVisibility(next);
+    }, [canManage, requestVisibility]);
     const handleHideInSearch = useCallback(() => {
         const control = options.hideInSearchControl;
         if (!control || control.pending || !canManage)
@@ -248,6 +263,7 @@ export function useShareButtonController(options) {
             ...(message ? { message } : {}),
         }, {
             onSuccess: (result) => {
+                notifyShareChanged(options.resourceType);
                 if (!(typeof result === "object" &&
                     result !== null &&
                     "updated" in result &&
@@ -315,6 +331,7 @@ export function useShareButtonController(options) {
             notify: false,
         }, {
             onSuccess: () => {
+                notifyShareChanged(options.resourceType);
                 void sharesQuery.refetch().then(() => {
                     setRoleOverrides((previous) => {
                         const { [key]: _removed, ...rest } = previous;
@@ -367,6 +384,7 @@ export function useShareButtonController(options) {
             principalId: currentShare.principalId,
         }, {
             onSuccess: () => {
+                notifyShareChanged(options.resourceType);
                 void sharesQuery.refetch().then(() => {
                     setPendingRemoves((previous) => {
                         const next = new Set(previous);
@@ -408,6 +426,7 @@ export function useShareButtonController(options) {
         sharesQuery,
         visibilityOverride,
         handleVisibilityChange,
+        visibilityTransition,
         data,
         policy,
         visibility,

package/dist/client/sharing/useShareDialogController.d.ts

@@ -1,3 +1,4 @@
+import { type ShareVisibilityTransition } from "./useShareVisibilityTransition.js";
 export type ShareVisibility = "private" | "org" | "public";
 export type ShareRole = "viewer" | "commenter" | "editor" | "admin";
 export type ShareDialogTab = "link" | "invite" | "embed";
@@ -82,7 +83,9 @@ export interface ShareDialogController {
         options: Array<ShareOption<ShareVisibility>>;
         disabled: boolean;
         pending: boolean;
+        /** Saves at once, or holds a broadening change for `transition`. */
         set: (visibility: ShareVisibility) => void;
+        transition: ShareVisibilityTransition;
     };
     invite: {
         email: string;

package/dist/client/sharing/useShareDialogController.js

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { trackEvent } from "../analytics.js";
 import { useT } from "../i18n.js";
-import { extractShareErrorMessage, optimisticallyUpdateShareCache, rollbackShareCache, useShareMutationGuard, useShareMutations, useShareOrgMemberSearch, useShareQuery, } from "./share-controller-helpers.js";
+import { extractShareErrorMessage, notifyShareChanged, optimisticallyUpdateShareCache, optimisticallyUpdateShareVisibility, rollbackShareCache, useShareMutationGuard, useShareMutations, useShareOrgMemberSearch, useShareQuery, } from "./share-controller-helpers.js";
+import { useShareVisibilityTransition, } from "./useShareVisibilityTransition.js";
 async function writeBrowserClipboardText(text) {
     if (typeof navigator === "undefined" || !navigator.clipboard?.writeText) {
         return false;
@@ -34,9 +35,16 @@ export function useShareDialogController({ open, onClose, resourceType, resource
     const [message, setMessage] = useState("");
     const [messageOpen, setMessageOpen] = useState(false);
     const [copiedField, setCopiedField] = useState(null);
-    const [visibilityOverride, setVisibilityOverride] = useState(null);
+    const resourceKey = `${resourceType}:${resourceId}`;
+    // Tied to the resource it was made for: a click that lands on a new resource
+    // before any effect runs must not see the previous resource's value.
+    const [visibilityOverrideState, setVisibilityOverrideState] = useState(null);
+    const visibilityOverride = visibilityOverrideState?.resourceKey === resourceKey
+        ? visibilityOverrideState.value
+        : null;
+    const clearVisibilityOverride = useCallback((key, token) => setVisibilityOverrideState((state) => state?.resourceKey === key && state.token === token ? null : state), []);
     const [mutationError, setMutationError] = useState(null);
-    const visibilityGuard = useShareMutationGuard();
+    const visibilityGuard = useShareMutationGuard(resourceKey);
     const copyResetTimer = useRef(null);
     useEffect(() => {
         if (open)
@@ -56,61 +64,76 @@ export function useShareDialogController({ open, onClose, resourceType, resource
         .map((value) => visibilityOption(value, t)), [data?.policy?.allowPublic, t, visibility]);
     const roleOptions = useMemo(() => ["viewer", "commenter", "editor", "admin"].map((value) => roleOption(value, t)), [t]);
     const refetch = useCallback(() => sharesQuery.refetch(), [sharesQuery]);
-    const setVisibility = useCallback((next) => {
-        if (!canManage || next === visibility)
-            return;
+    const applyVisibility = useCallback(async (next) => {
         const requestId = visibilityGuard.begin();
-        const previous = optimisticallyUpdateShareCache(queryClient, shareQueryKey, (cached) => (cached ? { ...cached, visibility: next } : cached));
+        const token = {};
+        const mutation = optimisticallyUpdateShareVisibility(queryClient, shareQueryKey, next);
         setMutationError(null);
-        setVisibilityOverride(next);
-        visibilityMutation.mutate({ resourceType, resourceId, visibility: next }, {
-            onSuccess: (result) => {
-                if (visibilityGuard.isLatest(requestId)) {
-                    const resultVisibility = typeof result === "object" &&
-                        result !== null &&
-                        "visibility" in result &&
-                        result.visibility;
-                    optimisticallyUpdateShareCache(queryClient, shareQueryKey, (cached) => cached
-                        ? {
-                            ...cached,
-                            visibility: resultVisibility ??
-                                next,
-                        }
-                        : cached);
-                }
-                if (!visibilityGuard.isLatest(requestId))
-                    return;
-                Promise.resolve(refetch())
-                    .catch((error) => {
-                    if (visibilityGuard.isLatest(requestId)) {
-                        setMutationError(extractShareErrorMessage(error));
-                    }
-                })
-                    .finally(() => {
-                    if (visibilityGuard.isLatest(requestId)) {
-                        setVisibilityOverride(null);
-                    }
-                });
-            },
-            onError: (error) => {
-                if (visibilityGuard.isLatest(requestId)) {
-                    rollbackShareCache(queryClient, shareQueryKey, previous);
-                    setVisibilityOverride(null);
-                    setMutationError(extractShareErrorMessage(error));
-                }
-            },
+        setVisibilityOverrideState({ resourceKey, token, value: next });
+        let result;
+        try {
+            // Settles for this call alone: per-call mutate callbacks are skipped
+            // once a newer call supersedes it or the observer unmounts.
+            result = await visibilityMutation.mutateAsync({
+                resourceType,
+                resourceId,
+                visibility: next,
+            });
+        }
+        catch (error) {
+            mutation.rollback();
+            clearVisibilityOverride(resourceKey, token);
+            if (visibilityGuard.isLatest(requestId) && mutation.isCurrent()) {
+                void queryClient.refetchQueries({ queryKey: shareQueryKey, exact: true, type: "active" }, { throwOnError: false });
+            }
+            throw error;
+        }
+        notifyShareChanged(resourceType);
+        const resultVisibility = typeof result === "object" &&
+            result !== null &&
+            "visibility" in result &&
+            result.visibility;
+        mutation.commit(resultVisibility ?? next);
+        if (!visibilityGuard.isLatest(requestId)) {
+            clearVisibilityOverride(resourceKey, token);
+            return;
+        }
+        void Promise.resolve(refetch())
+            .catch((error) => {
+            if (visibilityGuard.isLatest(requestId)) {
+                setMutationError(extractShareErrorMessage(error));
+            }
+        })
+            .finally(() => {
+            clearVisibilityOverride(resourceKey, token);
         });
     }, [
-        canManage,
         refetch,
         resourceId,
         resourceType,
+        resourceKey,
+        clearVisibilityOverride,
         queryClient,
         shareQueryKey,
-        visibility,
         visibilityGuard,
         visibilityMutation,
     ]);
+    const visibilityTransition = useShareVisibilityTransition({
+        resourceType,
+        resourceId,
+        current: visibility,
+        orgId: data?.orgId ?? null,
+        canManage,
+        active: open,
+        apply: applyVisibility,
+        onDirectError: (error) => setMutationError(extractShareErrorMessage(error)),
+    });
+    const requestVisibility = visibilityTransition.request;
+    // A void setter: callers that return it from a handler must not end up
+    // awaiting a change that may sit waiting for confirmation.
+    const setVisibility = useCallback((next) => {
+        void requestVisibility(next);
+    }, [requestVisibility]);
     const submitInvite = useCallback(() => {
         const principalId = email.trim();
         if (!canManage || !principalId)
@@ -135,6 +158,7 @@ export function useShareDialogController({ open, onClose, resourceType, resource
             ...(notificationMessage ? { message: notificationMessage } : {}),
         }, {
             onSuccess: () => {
+                notifyShareChanged(resourceType);
                 setEmail("");
                 setMessage("");
                 setMessageOpen(false);
@@ -176,7 +200,10 @@ export function useShareDialogController({ open, onClose, resourceType, resource
             principalType: share.principalType,
             principalId: share.principalId,
         }, {
-            onSuccess: refetch,
+            onSuccess: () => {
+                notifyShareChanged(resourceType);
+                return refetch();
+            },
             onError: (error) => {
                 rollbackShareCache(queryClient, shareQueryKey, previous);
                 setMutationError(extractShareErrorMessage(error));
@@ -260,9 +287,10 @@ export function useShareDialogController({ open, onClose, resourceType, resource
             label: currentVisibility.label,
             description: currentVisibility.description,
             options: visibilityOptions,
-            disabled: !canManage,
+            disabled: !canManage || visibilityTransition.submitting,
             pending: visibilityMutation.isPending,
             set: setVisibility,
+            transition: visibilityTransition,
         },
         invite: {
             email,
@@ -290,7 +318,7 @@ export function useShareDialogController({ open, onClose, resourceType, resource
         copiedField,
         copy,
         loading: sharesQuery.isLoading,
-        error: sharesQuery.error ?? mutationError,
+        error: mutationError ?? sharesQuery.error,
         refetch,
         canManage,
         agentReadable: data?.agentReadable === true,

package/dist/client/sharing/useShareVisibilityTransition.d.ts

@@ -0,0 +1,68 @@
+import type { ShareVisibility } from "./useShareDialogController.js";
+/**
+ * Whether moving to `to` shows more of the resource to more people than `from`
+ * does and so needs an explicit confirmation. Public -> organization narrows
+ * access and Public stays confirmation-free, so only private -> organization
+ * asks.
+ */
+export declare function visibilityNeedsConfirmation(from: ShareVisibility, to: ShareVisibility): boolean;
+/**
+ * Why a requested visibility change was never saved: `ignored` when the
+ * request was refused up front (closed surface, no manage rights, a save
+ * already running) and `dropped` when it was held for confirmation and then
+ * cancelled or invalidated.
+ */
+export declare class ShareVisibilityNotSavedError extends Error {
+    readonly reason: "ignored" | "dropped";
+    constructor(reason: "ignored" | "dropped");
+}
+export interface ShareVisibilityTransitionOptions {
+    resourceType: string;
+    resourceId: string;
+    /** The visibility shown right now, including an in-flight optimistic one. */
+    current: ShareVisibility;
+    /** The organization the resource belongs to, from the share listing. */
+    orgId: string | null;
+    canManage: boolean;
+    /** False while the share surface is closed; a pending request is dropped. */
+    active: boolean;
+    /** Saves the visibility. Rejects on failure so the caller can show it. */
+    apply: (next: ShareVisibility) => Promise<void>;
+    /**
+     * Receives a failure of a change that needed no confirmation. Required so a
+     * failed save is never left looking like a successful one.
+     */
+    onDirectError: (error: unknown) => void;
+}
+export interface ShareVisibilityTransitionRequest {
+    from: ShareVisibility;
+    to: ShareVisibility;
+}
+export interface ShareVisibilityTransition {
+    /** The change waiting for confirmation, or null. Nothing is saved yet. */
+    pending: ShareVisibilityTransitionRequest | null;
+    /**
+     * The resource's organization name, only when it was read for that exact
+     * organization. Null means "say your organization" instead of a name.
+     */
+    organizationName: string | null;
+    submitting: boolean;
+    /** Why the last confirmation failed; the request stays pending to retry. */
+    error: string | null;
+    /**
+     * Saves `next` at once, or holds it for confirmation when it broadens.
+     * The promise resolves only once the change is persisted. A change that
+     * needs no confirmation rejects with the save's failure. A held change that
+     * fails when confirmed keeps its `error` and stays pending so the user can
+     * retry, and its promise stays pending too: it resolves after a successful
+     * retry and rejects with `ShareVisibilityNotSavedError` once the change is
+     * cancelled or invalidated (resource change, closed surface, lost manage
+     * rights). A request that is refused up front rejects the same way.
+     * While a save runs, the same target joins it and a different target is
+     * refused with reason `ignored` until the write settles.
+     */
+    request: (next: ShareVisibility) => Promise<void>;
+    confirm: () => Promise<void>;
+    cancel: () => void;
+}
+export declare function useShareVisibilityTransition(options: ShareVisibilityTransitionOptions): ShareVisibilityTransition;