@ai-matrx/sharing 0.0.0-stage → 0.1.0

package/dist/access-react.d.ts

@@ -0,0 +1,682 @@
+import * as react from 'react';
+import { AnchorHTMLAttributes, RefAttributes, ComponentType, ReactNode } from 'react';
+import { ConfirmOptions } from '@ai-matrx/kit/confirm-opener';
+import { JsonObject } from '@ai-matrx/kit/json-format';
+import { RecordUnavailableResolution } from '@ai-matrx/data/db';
+import * as _ai_matrx_data_access from '@ai-matrx/data/access';
+import { AccessRequestCreated, AccessRequestability, AccessDeniedContext, RequestAccessTarget, AccessSupabaseClient, HiddenView, AccessRequestStatus, HiddenItem, RemovalRights, RequestContext } from '@ai-matrx/data/access';
+export { RequestAccessTarget } from '@ai-matrx/data/access';
+
+interface AccessUiLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    href: string;
+}
+/** The person using the screen. Any field may be null while the session boots. */
+interface AccessUiCurrentUser {
+    id: string | null;
+    displayName: string | null;
+    email: string | null;
+}
+interface AccessUiToast {
+    success(message: string): void;
+    error(message: string): void;
+    warning(message: string): void;
+    info?(message: string): void;
+}
+interface AccessUiRouter {
+    push(href: string): void;
+    back(): void;
+    /** Re-render the current URL from the server (Next `router.refresh()`). */
+    refresh(): void;
+}
+/** What the gate needs to know about an entity token to link to a record. */
+interface AccessUiEntityInfo {
+    hrefFor?: (id: string) => string | null | undefined;
+}
+interface AccessUiEntityRefProps {
+    token: string;
+    id: string;
+    name: string;
+    showIcon?: boolean;
+    className?: string;
+}
+interface AccessUiUserIdentityProps {
+    user: {
+        id?: string | null | undefined;
+        displayName?: string | null | undefined;
+        avatarUrl?: string | null | undefined;
+    };
+    size?: "sm" | "md";
+    subtitle?: boolean;
+    avatarOnly?: boolean;
+}
+interface AccessUiErrorMenuProps {
+    size?: "icon" | "default";
+    className?: string;
+    /** The error text (or error) the menu should offer to copy. */
+    error?: unknown;
+    /** Structured description of what failed (title, message, operation, records…). */
+    input?: Record<string, unknown>;
+}
+interface AccessUiTextareaProps {
+    className?: string;
+    value: string;
+    onChange: (event: {
+        target: {
+            value: string;
+        };
+    }) => void;
+    placeholder?: string;
+    maxLength?: number;
+    rows?: number;
+    autoFocus?: boolean;
+    "aria-label"?: string;
+}
+/** A setting-change action an admin completes from a request (messaging registry). */
+interface AccessSettingRequestAction {
+    label: string;
+    completedLabel: string;
+    execute(payload: JsonObject, context: {
+        organizationId: string;
+    }): Promise<void>;
+}
+/** A resource action (e.g. delete) an owner completes from a request. */
+interface AccessResourceActionRequestAction {
+    label: string;
+    completedLabel: string;
+    confirmTitle(name: string): string;
+    confirmDescription: string;
+    execute(context: {
+        resourceType: string;
+        resourceId: string;
+    }): Promise<void>;
+}
+interface AccessUiFeedbackInput {
+    feedback_type: "request";
+    route: string;
+    organization_id: string;
+    description: string;
+    metadata: Record<string, unknown>;
+}
+interface AccessUiEnv {
+    /** The sign-in URL that returns the person to where they are. Hook-shaped. */
+    useLoginHref(): string;
+    /** The current person (replaces the app's redux selectors). Hook-shaped. */
+    useCurrentUser(): AccessUiCurrentUser;
+    /** User-visible notices. */
+    toast: AccessUiToast;
+    /** Client-side navigation link. Default: a plain `<a href>` (full page load). */
+    Link?: ComponentType<AccessUiLinkProps & RefAttributes<HTMLAnchorElement>>;
+    /** Default: `history.back()` / `location.reload()` / `location.assign`. */
+    router?: AccessUiRouter;
+    /** Read one URL query parameter. Default: `window.location.search`. */
+    searchParam?(name: string): string | null;
+    /** Default: the kit's imperative `confirm()` (needs the design-system ConfirmDialogHost mounted). */
+    confirm?(options: ConfirmOptions): Promise<boolean>;
+    /** Default: the design-system `Textarea`. An app may pass its voice-enabled textarea. */
+    Textarea?: ComponentType<AccessUiTextareaProps>;
+    /** Default: avatar + name from the design-system Avatar. */
+    renderUserIdentity?(props: AccessUiUserIdentityProps): ReactNode;
+    /** Default: the plain name — NOT a door. Pass the app's EntityRef to make it one. */
+    renderEntityRef?(props: AccessUiEntityRefProps): ReactNode;
+    /** The error-copy menu slot. Default: renders nothing (it is a convenience, not a feature). */
+    renderErrorMenu?(props: AccessUiErrorMenuProps): ReactNode;
+    /** Classes of the selected / unselected inbox tab. Default: the app-shell nav CSS variables. */
+    navItemClasses?: {
+        selected: string;
+        unselected: string;
+    };
+    /** Label/route lookup per entity token. Absent: owners and records render as plain names. */
+    entityRegistry?: {
+        tryGetEntityInfo(token: string): AccessUiEntityInfo | null;
+    };
+    /** Restore from Trash. Absent: pressing Restore fails visibly naming this field. */
+    trash?: {
+        restore(token: string, id: string): Promise<void>;
+    };
+    /** Reconcile the diagnostics row of a captured read. Absent: no-op. */
+    recordUnavailableCapture?: {
+        resolve(error: unknown, resolution: RecordUnavailableResolution): void;
+    };
+    /** Setting-change actions by key. Absent: requests render without the primary action button. */
+    settingRequestActions?: {
+        get(key: string): AccessSettingRequestAction | undefined;
+    };
+    /** The action key the "request access" flows file. Default `request_access.manual`. */
+    manualRequestActionKey?: string;
+    /** Resource actions by key. Absent: requests render without the primary action button. */
+    resourceActionRequests?: {
+        get(key: string): AccessResourceActionRequestAction | undefined;
+    };
+    /** CMS-resolved tokens file through the host's CMS door. Absent: asking fails visibly. */
+    cms?: {
+        createAccessRequest(args: {
+            token: string;
+            resourceId: string;
+            message?: string;
+            currentUserId?: string | null;
+        }): Promise<AccessRequestCreated>;
+    };
+    /** The URL of an organization setting's door. Absent: asking for a setting change fails visibly. */
+    settingDoorHref?(target: {
+        scope: "organization";
+        organizationSlugOrId: string;
+        controlId: string;
+    }): string;
+    /** File a feedback item (system-owned access requests). Absent: asking the platform team fails visibly. */
+    reportFeedback?(input: AccessUiFeedbackInput): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Show "choose an organization first". Returns true when it handled the error. Default: false. */
+    presentOrganizationRefusal?(error: unknown, options: {
+        act: string;
+        subject: string;
+    }): boolean;
+    /**
+     * The host's overlay doors (AI Matrx: dispatch summon `openOverlay` / `closeOverlay` on its store). The
+     * "can't remove it" screen is the overlay `CANT_REMOVE_DIALOG` opened through them. Absent: that screen
+     * cannot open and says so on the console (the caller gets "closed").
+     */
+    overlays?: {
+        open(overlayId: string, instanceId: string, data: unknown): void;
+        close(overlayId: string, instanceId: string): void;
+    };
+}
+/** The documented default for `manualRequestActionKey`. */
+declare const REQUEST_ACCESS_MANUAL_ACTION = "request_access.manual";
+/** The host's `Link`, resolved at render. Components import this as `Link`. */
+declare const AccessLink: react.ForwardRefExoticComponent<AccessUiLinkProps & RefAttributes<HTMLAnchorElement>>;
+/**
+ * Inject the app inputs the access screens need. Call once at boot. Later
+ * calls MERGE over earlier ones, so a host can configure in two steps.
+ */
+declare function configureAccessUi(env: Partial<AccessUiEnv>): void;
+/** True once every REQUIRED field has been supplied. */
+declare function isAccessUiConfigured(): boolean;
+/** The resolved environment: required fields throw when missing, the rest are defaulted. */
+interface AccessUi {
+    useLoginHref(): string;
+    useCurrentUser(): AccessUiCurrentUser;
+    toast: AccessUiToast;
+    Link: ComponentType<AccessUiLinkProps & RefAttributes<HTMLAnchorElement>>;
+    router: AccessUiRouter;
+    searchParam(name: string): string | null;
+    confirm(options: ConfirmOptions): Promise<boolean>;
+    Textarea: ComponentType<AccessUiTextareaProps>;
+    renderUserIdentity(props: AccessUiUserIdentityProps): ReactNode;
+    renderEntityRef(props: AccessUiEntityRefProps): ReactNode;
+    renderErrorMenu(props: AccessUiErrorMenuProps): ReactNode;
+    navItemClasses: {
+        selected: string;
+        unselected: string;
+    };
+    manualRequestActionKey: string;
+    tryGetEntityInfo(token: string): AccessUiEntityInfo | null;
+    restoreFromTrash(token: string, id: string): Promise<void>;
+    resolveRecordUnavailableCapture(error: unknown, resolution: RecordUnavailableResolution): void;
+    getSettingRequestAction(key: string): AccessSettingRequestAction | undefined;
+    getResourceActionRequestAction(key: string): AccessResourceActionRequestAction | undefined;
+    /** Whether the host wired the CMS door (cms.createAccessRequest). */
+    createCmsAccessRequest(args: {
+        token: string;
+        resourceId: string;
+        message?: string;
+        currentUserId?: string | null;
+    }): Promise<AccessRequestCreated>;
+    settingDoorHref(target: {
+        scope: "organization";
+        organizationSlugOrId: string;
+        controlId: string;
+    }): string;
+    reportFeedback(input: AccessUiFeedbackInput): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    presentOrganizationRefusal(error: unknown, options: {
+        act: string;
+        subject: string;
+    }): boolean;
+    /** Open an overlay through the host's doors; throws `notConfigured("overlays")` without them. */
+    openOverlay(overlayId: string, instanceId: string, data: unknown): void;
+    closeOverlay(overlayId: string, instanceId: string): void;
+}
+/** The module-level environment, for code that is not a component (openers, stores). */
+declare function getAccessUi(): AccessUi;
+/** Override fields for one subtree (tests, a second host). Merges over `configureAccessUi`. */
+declare function AccessUiProvider({ env, children, }: {
+    env: Partial<AccessUiEnv>;
+    children: ReactNode;
+}): react.JSX.Element;
+/** The merged, defaulted environment. Stable while neither the provider value nor the configuration changes. */
+declare function useAccessUi(): AccessUi;
+
+/**
+ * One concrete way forward, offered by the surface that knows the feature.
+ * The gate cannot invent these — only the CMS knows that "create a website" is
+ * the useful thing to offer someone whose website link went nowhere.
+ */
+interface AccessDeniedSuggestion {
+    /** Short imperative label — "Your websites", "Create a website". */
+    title: string;
+    /** One line on what they will get. Optional. */
+    description?: string;
+    /** Where it goes. Must be a route this viewer can actually open (THE DOOR LAW). */
+    href: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+}
+interface AccessDeniedProps {
+    /** Canonical entity token of the thing the user tried to open. */
+    token: string;
+    /** Its id. */
+    id: string;
+    /** The original failed read, so the resolver can reconcile its capture. */
+    readError?: unknown | undefined;
+    /**
+     * Where "go back to what I can see" should land when the platform can't find
+     * a reachable ancestor — usually the feature's own list route.
+     */
+    fallbackHref?: string | undefined;
+    fallbackLabel?: string | undefined;
+    /** Retry the surface's own read, offered only where retrying can work. */
+    onRetry?: (() => void) | undefined;
+    /** Concrete next steps in THIS feature. See AccessDeniedSuggestion. */
+    suggestions?: AccessDeniedSuggestion[] | undefined;
+    /**
+     * Whether asking is a real option here. Defaults to `"requestable"` — the
+     * behavior every existing caller already has. Pass `"absolute"` when the
+     * door is closed by law and the ask itself would leak. See
+     * `AccessRequestability`.
+     */
+    requestability?: AccessRequestability | undefined;
+    /**
+     * The surface's own worded reason, shown in place of the generic explanation.
+     * On an `absolute` door this sentence must not confirm the record exists.
+     */
+    reason?: string | undefined;
+    /** The surface's own headline, in place of the kind-naming generic one. */
+    headline?: string | undefined;
+    /** The surface's own trailing disclosure (a reference code, an audit id). */
+    footer?: React.ReactNode | undefined;
+}
+/**
+ * The resolved surface. Split from the loader so a bespoke variant can reuse
+ * the same body with different chrome.
+ */
+declare function AccessDeniedView({ context, id, fallbackHref, fallbackLabel, onRetry, onChanged, suggestions, requestability, reason, headline: headlineOverride, footer, }: {
+    context: AccessDeniedContext;
+    id: string;
+    fallbackHref?: string | undefined;
+    fallbackLabel?: string | undefined;
+    onRetry?: (() => void) | undefined;
+    onChanged: () => void;
+    suggestions?: AccessDeniedSuggestion[] | undefined;
+    /** See `AccessRequestability`. `absolute` removes the request affordance entirely. */
+    requestability?: AccessRequestability | undefined;
+    /** The surface's own worded reason, in place of the generic explanation. */
+    reason?: string | undefined;
+    /** The surface's own headline, in place of the kind-naming generic one. */
+    headline?: string | undefined;
+    /**
+     * The surface's own trailing disclosure — a reference code, an audit id, the
+     * things a feature earned the right to show and the frame cannot know about.
+     * Rendered above the doors. Machine tokens belong in here behind a
+     * `<details>`, never in the body: that rule predates this slot and outlives it.
+     */
+    footer?: React.ReactNode | undefined;
+}): react.JSX.Element;
+/**
+ * The loader. Resolves why the record couldn't be opened, then renders it.
+ *
+ * A feature that genuinely earns a bespoke screen composes `AccessDeniedView`
+ * (exported above) at its own call site — it does NOT register a variant here.
+ * A token→component registry consulted during render is a dynamic component
+ * boundary (react-hooks/static-components) for an extension point that has
+ * exactly zero users, which is the speculative abstraction docs/reuse-first
+ * bans. Passing your own component down is simpler and has no such hazard.
+ */
+declare function AccessDenied({ token, id, readError, fallbackHref, fallbackLabel, onRetry, suggestions, requestability, reason, headline, footer, }: AccessDeniedProps): react.JSX.Element;
+
+interface AccessGateProps {
+    /** Canonical entity token of the record the surface tried to open. */
+    token: string;
+    id: string;
+    /**
+     * The error the read produced, if any. A null-row read (no error at all) is
+     * the common case and is exactly what this gate is for.
+     */
+    error?: unknown | undefined;
+    onRetry?: (() => void) | undefined;
+    fallbackHref?: string | undefined;
+    fallbackLabel?: string | undefined;
+    /**
+     * Parallel failed reads hidden by this gate's early return. Each is resolved
+     * independently for truthful diagnostics; none renders a second surface.
+     */
+    relatedReads?: ReadonlyArray<{
+        token: string;
+        id: string;
+        error: unknown;
+    }>;
+    /**
+     * Render this instead when the failure was a genuine fault rather than an
+     * access state. Defaults to the access surface, which handles faults with an
+     * honest "something went wrong on our side" + retry.
+     */
+    renderFault?: (error: unknown) => React.ReactNode;
+    /**
+     * Two or three concrete things to do instead, in THIS feature — "your
+     * websites", "create one". Without them the gate is honest and still a dead
+     * end: it says what went wrong and leaves the user to re-navigate.
+     */
+    suggestions?: AccessDeniedSuggestion[] | undefined;
+    /**
+     * `"absolute"` removes the request affordance entirely — for a door closed by
+     * law, where the ask itself would leak. Defaults to `"requestable"`.
+     */
+    requestability?: AccessRequestability | undefined;
+    /** The surface's own worded reason, in place of the generic explanation. */
+    reason?: string | undefined;
+    /** The surface's own headline, in place of the kind-naming generic one. */
+    headline?: string | undefined;
+    /** The surface's own trailing disclosure (a reference code, an audit id). */
+    footer?: React.ReactNode | undefined;
+}
+declare function AccessGate({ token, id, error, onRetry, fallbackHref, fallbackLabel, relatedReads, renderFault, suggestions, requestability, reason, headline, footer, }: AccessGateProps): react.JSX.Element;
+
+interface SlugAccessGateProps {
+    /** Entity tokens to try, in the page's own resolution order. */
+    tokens: readonly string[];
+    /** The raw route slug (already decoded by the App Router). */
+    slug: string;
+    /** What the thing is called in the "didn't match" sentence, e.g. "shape". */
+    noun: string;
+    fallbackHref: string;
+    fallbackLabel: string;
+    /**
+     * The page also filters by publication state (not just RLS), so a miss can
+     * be a row the viewer may read that simply is not published.
+     */
+    publishFiltered?: boolean;
+}
+declare function SlugAccessGate({ tokens, slug, noun, fallbackHref, fallbackLabel, publishFiltered, }: SlugAccessGateProps): react.JSX.Element | null;
+
+declare function SettingAccessGate({ canManage, organizationId, organizationSlugOrId, settingKey, settingLabel, actionKey, actionPayload, defaultMessage, requestReady, children, }: {
+    canManage: boolean;
+    organizationId: string;
+    organizationSlugOrId: string;
+    settingKey: string;
+    settingLabel: string;
+    actionKey: string;
+    actionPayload: JsonObject;
+    defaultMessage: string;
+    requestReady?: boolean;
+    children: React.ReactNode;
+}): react.JSX.Element;
+
+/**
+ * WHAT THE APP'S SERVER BOUNDARY READS AND HANDS DOWN. The package cannot call
+ * `headers()` or the session verdict (no `next/*`, no app imports, and an async
+ * Server Component cannot live in a client entry). The app's `forbidden.tsx`
+ * keeps a ~10-line server wrapper: read the verdict + the stamped request path,
+ * build `signInHref`, and render `<ForbiddenSurfaceView …/>`.
+ */
+interface ForbiddenSurfaceViewProps {
+    /** `unverified` = the session could not be confirmed (neither "no access" nor "sign in"). */
+    state: "authenticated" | "anonymous" | "unverified";
+    isAuthenticated: boolean;
+    /** The path the person was trying to open (the app stamps it on the request). */
+    pathname: string;
+    search?: string;
+    /** Sign-in URL that returns to `pathname`+`search`. */
+    signInHref: string;
+    /** Where "Back to what you can see" goes. Default `/dashboard`. */
+    homeHref?: string;
+}
+declare function ForbiddenSurfaceView({ state, isAuthenticated, pathname, search, signInHref, homeHref, }: ForbiddenSurfaceViewProps): react.JSX.Element;
+
+declare function RequestAccess({ target, variant, reason, className, }: {
+    target: RequestAccessTarget;
+    /** `inline` = one line + button; `icon` = key icon only (tight headers). */
+    variant?: "inline" | "icon";
+    /** Inline only: the one-line why. Defaults from the owner. */
+    reason?: string;
+    className?: string;
+}): react.JSX.Element;
+
+interface RequestAccessPanelProps {
+    context: AccessDeniedContext;
+    /**
+     * The record's id. It is NOT on the context — the RPC never echoes back an id
+     * the caller already had, so the surface that knows it passes it through.
+     */
+    resourceId: string;
+    /** Where the record lives, passed to the recipient's DM chip. */
+    href?: string | null;
+    onChanged: () => void;
+}
+declare function RequestAccessPanel({ context, resourceId, href, onChanged, }: RequestAccessPanelProps): react.JSX.Element | null;
+
+declare function BlindAccessAsk({ token, id, href, }: {
+    token: string;
+    id: string;
+    href?: string | null;
+}): react.JSX.Element;
+
+interface UnresolvedEntityRefProps {
+    /** The record's id — the resolver never echoes back an id the caller had. */
+    id: string;
+    /**
+     * The resolved answer, or null while `useAccessStates` is still asking.
+     * Never synthesize one: a guessed state is the defect this component fixes.
+     */
+    context: AccessDeniedContext | null;
+    /** Re-resolve after the owner grants, so the row heals in place. */
+    onChanged?: () => void;
+    /**
+     * The surface's own repair for a record it cannot resolve — "Remove from
+     * outreach list", "Detach", "Replace". Rendered inside the popover under the
+     * platform's own actions. THE DOOR LAW's third corollary: a problem you can
+     * detect ships with its fix.
+     */
+    repairAction?: React.ReactNode;
+    className?: string;
+}
+declare function UnresolvedEntityRef({ id, context, onChanged, repairAction, className, }: UnresolvedEntityRefProps): react.JSX.Element;
+
+type BrowserClient = AccessSupabaseClient;
+/** Row readers per canonical entity token. Add a token when a page adopts this. */
+declare const ROW_READERS: {
+    conversation: (supabase: BrowserClient, id: string) => Promise<boolean>;
+};
+type ServerReadRecheckToken = keyof typeof ROW_READERS;
+declare function ServerReadRecheck({ token, id, children, pending, }: {
+    token: ServerReadRecheckToken;
+    id: string;
+    /** The access gate. */
+    children: ReactNode;
+    /** What shows while the browser re-reads. */
+    pending?: ReactNode;
+}): react.JSX.Element;
+
+declare function GovernedActionDialog({ open, onOpenChange, resourceType, resourceId, itemName, itemLabel, href, action, onHidden, }: {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    resourceType: string;
+    resourceId: string;
+    itemName: string;
+    itemLabel?: string;
+    href?: string | null;
+    /** The word for the removal the person tried: "archive" or "delete". */
+    action?: "archive" | "delete";
+    /** Called after the person hid the item (re-read a list that narrows server-side). */
+    onHidden?: () => void;
+}): react.JSX.Element;
+
+declare function HiddenByMeButton({ token, pluralLabel, }: {
+    /** Platform entity token of the list (`note`, `transcript`, …). */
+    token: string;
+    /** "notes" — the list's own word for its records. */
+    pluralLabel: string;
+}): react.JSX.Element | null;
+
+declare function HiddenFilter({ count, value, onValueChange, }: {
+    /** How many items of this list the person has hidden. */
+    count: number;
+    value: HiddenView;
+    onValueChange: (value: HiddenView) => void;
+}): react.JSX.Element | null;
+
+declare function ResourceActionRequestButtons({ requestId, actionKey, href, itemName, isOwn, compact, onDone, }: {
+    requestId: string;
+    actionKey: string;
+    href?: string | null;
+    itemName: string;
+    isOwn?: boolean;
+    compact?: boolean;
+    onDone?: (status: AccessRequestStatus) => void;
+}): react.JSX.Element;
+
+declare function SettingRequestActionButtons({ requestId, href, actionKey, isOwn, compact, onDone, }: {
+    requestId: string;
+    href: string;
+    actionKey: string;
+    isOwn?: boolean;
+    compact?: boolean;
+    onDone?: (status: AccessRequestStatus) => void;
+}): react.JSX.Element;
+
+/** The one address of this inbox: the settings tab `accessRequests`. */
+declare const ACCESS_REQUESTS_HREF = "/user-settings/access-requests";
+declare function AccessRequestsSurface(): react.JSX.Element;
+
+interface UseAccessGateResult {
+    context: AccessDeniedContext | null;
+    status: AccessDeniedContext["status"] | "loading";
+    isLoading: boolean;
+    /** Re-resolve — used after a request is sent, granted, or withdrawn. */
+    refresh: () => void;
+}
+declare function useAccessGate(token: string | null | undefined, id: string | null | undefined, options?: {
+    enabled?: boolean;
+    readError?: unknown;
+}): UseAccessGateResult;
+
+interface UseAccessStatesResult {
+    /** Resolved answers by record id. An absent id is still resolving. */
+    states: ReadonlyMap<string, AccessDeniedContext>;
+    /** True while at least one id on this page has no answer yet. */
+    isLoading: boolean;
+    /** Drop the cached answers for these ids and ask again. */
+    refresh: () => void;
+}
+/**
+ * Resolve the true access state of every id in `ids` for one entity token.
+ *
+ * Pass ONLY the ids that actually failed to resolve. Asking about records the
+ * caller can already read is a wasted round trip per row, and the resolver is
+ * deliberately a per-record call.
+ */
+declare function useAccessStates(token: string, ids: readonly string[]): UseAccessStatesResult;
+
+/** (Re)read one token's hidden items into the store. Signed out → nothing is hidden. */
+declare function refreshHiddenByMe(token: string): Promise<void>;
+declare function useHiddenByMe(token: string, enabled?: boolean): {
+    data: string[] | undefined;
+    isPending: boolean;
+};
+declare function useHiddenItems(token: string, enabled?: boolean): {
+    data: HiddenItem[] | undefined;
+    isPending: boolean;
+};
+declare function useRemovalRights(token: string, id: string | null): {
+    data: RemovalRights | undefined;
+    error: unknown;
+    isLoading: boolean;
+    isPending: boolean;
+    isError: boolean;
+    refetch: () => void;
+};
+type HideArgs = string | {
+    id: string;
+    label?: string | null;
+};
+/** Hide / unhide for the person. `onChanged` runs after the store refreshed. */
+declare function useHideForMe(token: string, onChanged?: () => void | Promise<void>): {
+    hide: {
+        isPending: boolean;
+        mutateAsync: (args: HideArgs) => Promise<void>;
+    };
+    unhide: {
+        isPending: boolean;
+        mutateAsync: (id: string) => Promise<void>;
+    };
+};
+
+interface RequestAccessResult {
+    /** A pending ask already existed — nothing new was sent. */
+    already: boolean;
+    /** Sentence for the confirmation toast. */
+    message: string;
+    /** Warning, not success: the ask is saved but no admin was messaged. */
+    undelivered: boolean;
+}
+declare function useRequestAccess(target: RequestAccessTarget): {
+    owner: _ai_matrx_data_access.ResolvedOwner;
+    destination: string;
+    context: () => RequestContext;
+    send: (note: string) => Promise<RequestAccessResult>;
+    sending: boolean;
+    sent: boolean;
+};
+
+/**
+ * THE imperative door to "you can't remove this: ask the owner, or hide it for me" (2026-10-14). Any code
+ * that tried to archive or delete a record the person may not remove calls `offerOwnerChoices(...)`.
+ * The screen is the summon overlay `CANT_REMOVE_DIALOG` (render: `./cantRemoveDialog.render`), opened
+ * through the host's overlay doors (`configureAccessUi({ overlays })`) and answered through summon's
+ * one-shot request (`requestOverlay`, `@ai-matrx/summon/request`, loaded on the first ask).
+ */
+interface CantRemoveRequest {
+    /** Platform entity token (`web_brand`, `note`, …). */
+    token: string;
+    id: string;
+    /** The record as a person says it ("Kiln log"). */
+    itemName: string;
+    /** The kind as a person says it ("note"). */
+    itemLabel: string;
+    action: "archive" | "delete";
+    href?: string | null;
+}
+/** "hidden" when the person hid it for themselves; "closed" otherwise. */
+type CantRemoveOutcome = "hidden" | "closed";
+/** The overlay id a host registers with `./cantRemoveDialog.render` as its render. */
+declare const CANT_REMOVE_DIALOG = "cantRemoveDialog";
+/**
+ * Open the owner-choices screen and await it: "hidden" when the person hid the record for themselves,
+ * "closed" otherwise (also when the host has no overlay doors). One screen per record at a time.
+ */
+declare function requestCantRemove(request: CantRemoveRequest): Promise<CantRemoveOutcome>;
+/** Thrown by a removal path that checked first and found the record isn't the person's to remove. */
+declare class RemovalNotYoursError extends Error {
+    readonly token: string;
+    readonly id: string;
+    constructor(token: string, id: string);
+}
+/** True for a check-first refusal or the database's governed refusal. */
+declare function isRemovalNotYours(error: unknown): boolean;
+/**
+ * When `error` means "not yours to remove", open the owner-choices screen and
+ * answer true (the caller shows nothing else). Otherwise answer false.
+ */
+declare function offerOwnerChoices(error: unknown, request: CantRemoveRequest): boolean;
+/**
+ * CHECK FIRST, before any archive/delete confirm: answers true when the person
+ * may remove the record (show your confirm), or opens the owner-choices screen
+ * and answers false. An unreadable answer is true — the write's own refusal
+ * still lands on `offerOwnerChoices`.
+ */
+declare function ensureRemovable(request: CantRemoveRequest): Promise<boolean>;
+
+export { ACCESS_REQUESTS_HREF, AccessDenied, type AccessDeniedProps, type AccessDeniedSuggestion, AccessDeniedView, AccessGate, type AccessGateProps, AccessLink, AccessRequestsSurface, type AccessResourceActionRequestAction, type AccessSettingRequestAction, type AccessUi, type AccessUiCurrentUser, type AccessUiEntityInfo, type AccessUiEntityRefProps, type AccessUiEnv, type AccessUiErrorMenuProps, type AccessUiFeedbackInput, type AccessUiLinkProps, AccessUiProvider, type AccessUiRouter, type AccessUiTextareaProps, type AccessUiToast, type AccessUiUserIdentityProps, BlindAccessAsk, CANT_REMOVE_DIALOG, type CantRemoveOutcome, type CantRemoveRequest, ForbiddenSurfaceView, type ForbiddenSurfaceViewProps, GovernedActionDialog, HiddenByMeButton, HiddenFilter, REQUEST_ACCESS_MANUAL_ACTION, RemovalNotYoursError, RequestAccess, RequestAccessPanel, type RequestAccessResult, ResourceActionRequestButtons, ServerReadRecheck, type ServerReadRecheckToken, SettingAccessGate, SettingRequestActionButtons, SlugAccessGate, type SlugAccessGateProps, UnresolvedEntityRef, type UnresolvedEntityRefProps, type UseAccessGateResult, type UseAccessStatesResult, configureAccessUi, ensureRemovable, getAccessUi, isAccessUiConfigured, isRemovalNotYours, offerOwnerChoices, refreshHiddenByMe, requestCantRemove, useAccessGate, useAccessStates, useAccessUi, useHiddenByMe, useHiddenItems, useHideForMe, useRemovalRights, useRequestAccess };