@civitai/blocks-react 0.47.0 → 0.49.0

package/README.md

@@ -518,6 +518,58 @@ if (error instanceof WildcardPackError && error.code === 'busy') void refetch();
 if (!loading && pack) console.log(Object.keys(pack.lists));
 ```
 
+### `useCollectionFollow()`
+
+Follow / unfollow a collection **for the viewer**, host-mediated over
+`SET_COLLECTION_FOLLOW`. Returns `{ setFollow, pending, error }`.
+
+**No block scope, and no token on the wire.** The host calls the session-authed
+`collection.follow` / `collection.unfollow` procedures, which self-bind to the
+viewer server-side — `collectionId` is the only thing a block influences.
+
+🔴 **Every call opens a host-chrome consent confirm naming the collection**, and
+that click is the *only* consent this path has ever had: the HTTP predecessor's
+`collections:write:self` scope is consent-exempt server-side and prompted nobody.
+Moving to this bridge **tightens** the flow; what it gives up is the manifest
+`scopes` declaration a moderator reads before install. The host resolves the
+collection's name itself (there is no `name` field on the wire, deliberately) and
+bounds that to **20 distinct ids per block instance** — past the cap it refuses
+with `collection-unavailable`, the same code a collection the viewer cannot see
+gets.
+
+`setFollow` **rejects** with a `CollectionFollowError` on every non-success. Two
+of those are not failures to render:
+
+| | meaning | what to do |
+|---|---|---|
+| `err.declined` | the viewer dismissed the confirm — **no write occurred** | revert, say nothing |
+| `err.signInRequired` | no session | route into `useRequestSignIn()` |
+| `err.timedOut` | no reply arrived within the 10-min consent bound | 🔴 **check this BEFORE `.message`** — it also has no `.code`, and its message is an SDK-internal string. It does **not** mean no write occurred; re-read your state |
+| `err.code` set otherwise | a host refusal (`invalid-request` / `review-mode` / `not-ready` / `collection-unavailable`) | show or ignore per case |
+| `err.code === undefined` **and** `!err.timedOut` | a **server** message the host forwarded verbatim | show `err.message` |
+
+```tsx
+const { setFollow, pending } = useCollectionFollow();
+const { requestSignIn } = useRequestSignIn();
+
+async function toggle() {
+  try {
+    const result = await setFollow({ collectionId, follow: !followed });
+    setFollowed(result.followed); // adopt the host's echo, not the guess
+  } catch (err) {
+    if (err instanceof CollectionFollowError) {
+      if (err.signInRequired) return requestSignIn();
+      if (err.declined) return; // the viewer said no — say nothing
+      if (err.timedOut) return showToast('Still working — check back in a moment.');
+      showToast(err.message); // a real server message, safe to render
+    }
+  }
+}
+```
+
+Most blocks want `<FollowButton>` from `@civitai/blocks-react/ui` instead, which
+wires all of the above.
+
 ### `useAppWorkflows(params?)`
 
 The calling app's **own** generator subqueue — the tag-scoped list of generations
@@ -778,20 +830,48 @@ any request for a scope your dev token lacks produces one.
 
 ### `useDomainMaturity()`
 
-Read the surrounding color-domain's maturity ceiling (civitai #2670) so a block
-can hide/blur mature affordances on a SFW domain. **Fail-closed SFW** until
-`BLOCK_INIT` lands or against a host that predates the field.
+Read the maturity ceiling in force for the current viewer, so a block can
+hide/blur mature affordances. **Fail-closed SFW** until `BLOCK_INIT` lands or
+against a host that projects no ceiling.
 
 ```tsx
 const { isSfw, isLevelAllowed } = useDomainMaturity();
 const showRSlider = isLevelAllowed(BrowsingLevel.R);   // false on a SFW domain
 ```
 
+The gates account for **two** things, and the distinction matters:
+
+| field | answers |
+| --- | --- |
+| `maxBrowsingLevel` | what this **domain** permits anybody (identical for every viewer on it) |
+| `effectiveBrowsingLevel` | what **this viewer** may be shown here — the domain ceiling narrowed by their own NSFW setting |
+
+`isSfw` / `isLevelAllowed` gate on the second, so a viewer who turned NSFW off
+sees SFW affordances even on a mature domain. `effectiveBrowsingLevel` is always
+a subset of `maxBrowsingLevel`, so reading these can only ever show the viewer
+**less** — never more. Compare the two when you want to explain *why* something
+is hidden:
+
+```tsx
+const { maxBrowsingLevel, effectiveBrowsingLevel } = useDomainMaturity();
+const hiddenByYourSettings = effectiveBrowsingLevel !== maxBrowsingLevel;
+```
+
+The hook's name is historic — it shipped when the domain ceiling was the only
+signal. There is deliberately no separate viewer-maturity hook: two hooks would
+mean two answers to "may I show this", and the one named for the domain would be
+the wider of the pair.
+
+Drive it locally with `createMockHost({ domain: 'red', viewerBrowsingLevel: BrowsingLevel.PG })`.
+The mock clamps that option to its own ceiling exactly as the real host does, so
+you cannot test against a viewer wider than the domain — production cannot
+produce one either.
+
 ### `SfwGate`
 
-Convenience component that renders `children` only when the domain permits the
-maturity — no `level` prop gates on the SFW ceiling, a `level` prop gates on that
-browsing-level bit. Fail-closed SFW.
+Convenience component that renders `children` only when the current viewer may be
+shown them — no `level` prop gates on `isSfw`, a `level` prop gates on that
+browsing-level bit. Both account for the domain **and** the viewer. Fail-closed SFW.
 
 ```tsx
 function MatureSection() {
@@ -924,6 +1004,8 @@ export function App() {
 | `Collapse` | controlled disclosure (`open` + `onOpenChange`, `title`, `disabled`) for the "advanced params reveal". `aria-expanded` + `aria-controls`; content region `role="region"`, `hidden` when closed. |
 | `SegmentedControl` | controlled view/tab switcher (`value` + `onChange`, `data: {value,label,disabled}[]`, `fullWidth`, `size`). `role="tablist"` of `role="tab"` buttons; ArrowLeft/ArrowRight rove selection. |
 | `ReportButton` | two-step control that files a shared-board row for platform moderator review via `useSharedStorage().report()`. `noun` + `onReport` (+ `reported` for server truth). 🔴 Its visible copy is deliberately **not** overridable — see the component's JSDoc. |
+| `FollowButton` | follow/unfollow a collection over the host bridge. `collectionId` + `followed` (+ `onChange`, `collectionName`). Flips optimistically, then adopts the **host's echo**; reverts on failure. 🔴 It exists because three outcomes are easy to get wrong: `declined` reverts **silently** (the viewer dismissed the host's confirm — nothing was written), `sign-in-required` routes into `REQUEST_SIGN_IN` rather than an error line, and every other rejection reverts with a `role="alert"` note. |
+| `TipButton` | two-step Buzz tip via `useTip()`. `toUserId` + `amount` + `noun` (+ `entityType`/`entityId`, `tipped`, `remaining`, `disabledReason`, `onTipped`). 🔴 **The confirm is the component's, not host chrome** — `useTip` posts directly with the block token, so a one-press money spend is reachable without it. It mints **one idempotency key per logical tip and reuses it on retry**, so a retry after a *lost* response cannot become a second transfer. Pass `remaining` from ONE `useTipAllowance()` held by the view — it deliberately does not fetch, or a screen of cards becomes N HTTP reads. |
 | `ResourceCard` | a picked generation resource (`BlockResourceInfo`) as a grid tile (`variant="card"`) or a compact line (`variant="row"`). `interactive` is an explicit discriminant that requires `onSelect` (+ `selected`/`disabled`); `thumbnailUrl` is optional because **`BlockResourceInfo` carries no image field**, and a missing *or failed* image falls back to a frozen "No preview" frame. `actions` is the trailing flow slot on both variants; `overlay` is the decorative corner badge over the thumbnail and is **`card`-only — a type error on a `row`**. Both render as siblings of the hit area, never inside it. The name fallback, type label, placeholder copy, selected mark and accessible-name order are frozen, not props. |
 
 Every component carries a `data-civitai-ui="<name>"` hook. Most also forward
@@ -985,6 +1067,7 @@ Runnable, minimal blocks — one per feature, each with its own README:
 
 | `@civitai/blocks-react` | pairs with `@civitai/app-sdk` | adds |
 |---|---|---|
+| `0.48.x` | `^0.38.0` | `useCollectionFollow()` + `<FollowButton>` / `<TipButton>` (`SET_COLLECTION_FOLLOW`). 🔴 The `peerDependencies` floor stays the deliberately-wide `>=0.29.0 <1.0.0` (#206 — a per-minor floor forced a major on consumers), so **npm will not warn you**: pairing this with an SDK below `0.38.0` fails at `tsc` with `Cannot find name 'BlockCollectionFollowErrorCode'`, not at install. |
 | `0.36.x` | `^0.27.0` | auto-installs the SDK's opaque-origin web-storage shim (`@civitai/app-sdk/safe-storage`) on import |
 | `0.29.x` | `^0.24.0` | `useAppWorkflows()` — app generator subqueue read + cancel (`QUERY_APP_WORKFLOWS` / `CANCEL_APP_WORKFLOW`) |
 | `0.27.x`–`0.28.x` | `^0.23.0` | async-scan image upload; transport validators for all `SHARED_*` / `APP_STORAGE_*` / picker replies |

package/dist/hooks/SfwGate.d.ts

@@ -8,25 +8,32 @@ export interface SfwGateProps {
     /**
      * When set, gate on `isLevelAllowed(level)` (a single `BrowsingLevel` bit)
      * instead of the coarse `isSfw`. Lets a block reveal a level-specific
-     * affordance (e.g. an R-rated toggle) only when the domain permits that level.
+     * affordance (e.g. an R-rated toggle) only when that level is permitted —
+     * by the domain AND by the viewer's own browsing-level setting.
      */
     level?: number;
     /** Rendered when the gate is closed. Defaults to `null` (render nothing). */
     fallback?: ReactNode;
 }
 /**
- * Convenience wrapper that renders `children` only when the surrounding
- * color-domain permits it, else `fallback` — so a block can hide/blur mature
- * affordances on a SFW domain without wiring {@link useDomainMaturity} by hand.
+ * Convenience wrapper that renders `children` only when the current viewer may
+ * be shown them here, else `fallback` — so a block can hide/blur mature
+ * affordances without wiring {@link useDomainMaturity} by hand.
  *
- * Gating:
- *  - no `level` prop → renders `children` when the domain is SFW (`isSfw`).
+ * Gating (both delegate to the hook, so both account for the DOMAIN's ceiling
+ * AND the VIEWER's own browsing level — see `effectiveBrowsingLevel`):
+ *  - no `level` prop → renders `children` when nothing mature may be shown
+ *    (`isSfw`).
  *  - `level` prop set → renders `children` when that browsing-level bit is
- *    allowed by the domain ceiling (`isLevelAllowed(level)`).
+ *    permitted (`isLevelAllowed(level)`).
+ *
+ * 🔴 A red-domain viewer who turned NSFW off closes this gate. That is the
+ * point: before the per-viewer ceiling existed, the gate opened for everyone on
+ * a mature domain regardless of their own setting.
  *
  * **Fail-closed SFW**: before `BLOCK_INIT` lands, and against a host that
- * predates civitai #2670 (no ceiling field), the gate is treated as SFW —
- * `children` show only for SFW content, mature content shows `fallback`.
+ * projects no ceiling at all, the gate is treated as SFW — `children` show only
+ * for SFW content, mature content shows `fallback`.
  *
  * @example
  * // Hide a mature-only carousel on a SFW domain:

package/dist/hooks/SfwGate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SfwGate.d.ts","sourceRoot":"","sources":["../../src/hooks/SfwGate.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAe,EAAE,EAAE,YAAY,GAAG,SAAS,CAIrF"}
+{"version":3,"file":"SfwGate.d.ts","sourceRoot":"","sources":["../../src/hooks/SfwGate.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAe,EAAE,EAAE,YAAY,GAAG,SAAS,CAIrF"}

package/dist/hooks/SfwGate.js

@@ -1,17 +1,23 @@
 import { useDomainMaturity } from './useDomainMaturity.js';
 /**
- * Convenience wrapper that renders `children` only when the surrounding
- * color-domain permits it, else `fallback` — so a block can hide/blur mature
- * affordances on a SFW domain without wiring {@link useDomainMaturity} by hand.
+ * Convenience wrapper that renders `children` only when the current viewer may
+ * be shown them here, else `fallback` — so a block can hide/blur mature
+ * affordances without wiring {@link useDomainMaturity} by hand.
  *
- * Gating:
- *  - no `level` prop → renders `children` when the domain is SFW (`isSfw`).
+ * Gating (both delegate to the hook, so both account for the DOMAIN's ceiling
+ * AND the VIEWER's own browsing level — see `effectiveBrowsingLevel`):
+ *  - no `level` prop → renders `children` when nothing mature may be shown
+ *    (`isSfw`).
  *  - `level` prop set → renders `children` when that browsing-level bit is
- *    allowed by the domain ceiling (`isLevelAllowed(level)`).
+ *    permitted (`isLevelAllowed(level)`).
+ *
+ * 🔴 A red-domain viewer who turned NSFW off closes this gate. That is the
+ * point: before the per-viewer ceiling existed, the gate opened for everyone on
+ * a mature domain regardless of their own setting.
  *
  * **Fail-closed SFW**: before `BLOCK_INIT` lands, and against a host that
- * predates civitai #2670 (no ceiling field), the gate is treated as SFW —
- * `children` show only for SFW content, mature content shows `fallback`.
+ * projects no ceiling at all, the gate is treated as SFW — `children` show only
+ * for SFW content, mature content shows `fallback`.
  *
  * @example
  * // Hide a mature-only carousel on a SFW domain:

package/dist/hooks/SfwGate.js.map

@@ -1 +1 @@
-{"version":3,"file":"SfwGate.js","sourceRoot":"","sources":["../../src/hooks/SfwGate.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAkB3D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,EAAgB;IACxE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,iBAAiB,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpC,CAAC"}
+{"version":3,"file":"SfwGate.js","sourceRoot":"","sources":["../../src/hooks/SfwGate.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAmB3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,EAAgB;IACxE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,iBAAiB,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpC,CAAC"}

package/dist/hooks/useCollectionFollow.d.ts

@@ -0,0 +1,141 @@
+import type { BlockCollectionFollowErrorCode, BlockCollectionFollowResult } from '@civitai/app-sdk/blocks';
+export type { BlockCollectionFollowErrorCode, BlockCollectionFollowResult };
+/**
+ * The closed set of HOST refusal codes, as a runtime Set.
+ *
+ * 🔴 THIS EXISTS BECAUSE THE ERROR CHANNEL IS NOT AN ENUM. The host sends either
+ * one of these codes or a free-text server message, so "is this a code?" is a
+ * MEMBERSHIP question at runtime, not a type-level one — a `switch` over the
+ * union type would silently treat `"You do not have permission…"` as unmatched
+ * prose while a typo'd literal compiled fine. Derived from the array below so
+ * the two cannot drift.
+ */
+export declare const COLLECTION_FOLLOW_ERROR_CODES: readonly ["invalid-request", "sign-in-required", "review-mode", "not-ready", "declined", "collection-unavailable"];
+/**
+ * `true` when `error` is one of the host's CLOSED refusal codes rather than a
+ * free-text server message.
+ *
+ * Use it before comparing against a code — see
+ * {@link COLLECTION_FOLLOW_ERROR_CODES} for why equality alone is not enough.
+ */
+export declare function isCollectionFollowErrorCode(error: string): error is BlockCollectionFollowErrorCode;
+/**
+ * A collection follow/unfollow failure.
+ *
+ * `.code` is the host's refusal code when the host refused, and `undefined`
+ * otherwise.
+ *
+ * 🔴 `.code === undefined` IS NOT BY ITSELF "A SERVER MESSAGE WORTH SHOWING" —
+ * that reading is why {@link CollectionFollowError.timedOut} exists, and this
+ * paragraph asserted it until an audit caught it. TWO different failures land
+ * here: a server message the host forwarded verbatim, and a TRANSPORT TIMEOUT
+ * whose `.message` is an SDK-internal string. **Check `.timedOut` first**;
+ * `.code === undefined && !timedOut` is the branch whose `.message` is meant to
+ * be rendered.
+ */
+export declare class CollectionFollowError extends Error {
+    /** The closed host refusal code, or `undefined` for a server/transport error. */
+    readonly code?: BlockCollectionFollowErrorCode;
+    /**
+     * The SDK transport gave up waiting — no reply ever arrived.
+     *
+     * 🔴 CHECK THIS BEFORE SHOWING `.message`. A timeout also has
+     * `code === undefined`, so "no code ⇒ a server message worth rendering" is
+     * false, and acting on it puts an SDK-internal string
+     * (`IframeTransport: request "SET_COLLECTION_FOLLOW" timed out after 600000ms`)
+     * in front of a viewer. 🔴 It also does NOT mean no write occurred: the host
+     * may have completed the follow and failed only to deliver the reply, so do
+     * not present a timeout as "nothing happened" — re-read your own state.
+     */
+    readonly timedOut: boolean;
+    /**
+     * The viewer DISMISSED the host's consent confirm, so NO WRITE OCCURRED.
+     *
+     * 🔴 Not an error condition to shout about, and it is trustworthy in the one
+     * direction that matters: the host takes its consent latch synchronously
+     * before the write, so `declined` can never be reported for a follow that
+     * landed. Revert optimistic state and render nothing.
+     */
+    readonly declined: boolean;
+    /**
+     * There is no session. Route this into `useRequestSignIn()` rather than
+     * showing an error — the viewer's next step is signing in, not retrying.
+     */
+    readonly signInRequired: boolean;
+    constructor(error: string, opts?: {
+        timedOut?: boolean;
+    });
+}
+/** What {@link useCollectionFollow} returns. */
+export interface UseCollectionFollow {
+    /**
+     * Ask the host to follow (`follow: true`) or unfollow (`false`) `collectionId`
+     * for the viewer, and resolve with the host's echo of what it wrote.
+     *
+     * REJECTS with a {@link CollectionFollowError} on every non-success — including
+     * `declined`, which means the viewer dismissed the confirm and nothing was
+     * written. Check `.declined` before rendering a failure.
+     */
+    setFollow: (args: {
+        collectionId: number;
+        follow: boolean;
+    }) => Promise<BlockCollectionFollowResult>;
+    /** `true` while a follow request is in flight (including the viewer's confirm). */
+    pending: boolean;
+    /**
+     * The last request's failure, or `null`. Cleared at the start of the next
+     * `setFollow`. A dismissal lands here too — read `.declined`.
+     */
+    error: CollectionFollowError | null;
+}
+/**
+ * Follow / unfollow a collection for the viewer through the host-mediated
+ * `SET_COLLECTION_FOLLOW` → `COLLECTION_FOLLOW_RESULT` bridge.
+ *
+ * TOKEN-INDEPENDENT — this needs NO block scope and sends no token. The host
+ * calls the session-authed `collection.follow` / `collection.unfollow`
+ * procedures, which self-bind to the viewer server-side, so `collectionId` is
+ * the only thing a block influences.
+ *
+ * 🔴 EVERY CALL OPENS A HOST-CHROME CONSENT CONFIRM NAMING THE COLLECTION, and
+ * that click is the ONLY consent this path has ever had. The HTTP predecessor's
+ * `collections:write:self` scope was consent-exempt server-side and prompted
+ * nobody, so moving to this bridge TIGHTENS the path — it does not loosen it.
+ * What it costs is the manifest `scopes` declaration a moderator reads before
+ * install. Do not add a "skip the confirm" option; there is nothing behind it.
+ *
+ * Because the reply waits on a person, the request carries
+ * {@link HUMAN_INTERACTION_TIMEOUT_MS} (10 min) rather than the ~30s protocol
+ * default — it resolves the instant the viewer acts, and the ceiling only bounds
+ * an abandoned dialog.
+ *
+ * 🔴 THE HOST RESOLVES THE COLLECTION'S NAME ITSELF and bounds that to 20
+ * DISTINCT ids per block instance. Past the cap it refuses with
+ * `collection-unavailable` — the SAME code a collection the viewer cannot see
+ * gets — so a block driving many ids degrades into "we cannot act on this",
+ * never into an enumeration oracle. Repeats of an already-admitted id are free
+ * forever, so re-following a collection the viewer has already been asked about
+ * keeps working.
+ *
+ * @example
+ * const { setFollow, pending } = useCollectionFollow();
+ * const { requestSignIn } = useRequestSignIn();
+ *
+ * const toggle = async () => {
+ *   setFollowed((f) => !f); // optimistic
+ *   try {
+ *     const r = await setFollow({ collectionId, follow: !followed });
+ *     setFollowed(r.followed); // adopt the host's echo, not the guess
+ *   } catch (e) {
+ *     setFollowed(followed); // roll back
+ *     if (e instanceof CollectionFollowError) {
+ *       if (e.signInRequired) return requestSignIn();
+ *       if (e.declined) return; // the viewer said no — say nothing
+ *       if (e.timedOut) return showToast('Still working — check back in a moment.');
+ *       showToast(e.message); // a real server message, safe to render
+ *     }
+ *   }
+ * };
+ */
+export declare function useCollectionFollow(): UseCollectionFollow;
+//# sourceMappingURL=useCollectionFollow.d.ts.map

package/dist/hooks/useCollectionFollow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCollectionFollow.d.ts","sourceRoot":"","sources":["../../src/hooks/useCollectionFollow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,8BAA8B,EAC9B,2BAA2B,EAC5B,MAAM,yBAAyB,CAAC;AAMjC,YAAY,EAAE,8BAA8B,EAAE,2BAA2B,EAAE,CAAC;AAE5E;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,oHAOoB,CAAC;AAI/D;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,8BAA8B,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,8BAA8B,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;gBAErB,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE;CAQzD;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,OAAO,CAAC;KACjB,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC3C,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,mBAAmB,IAAI,mBAAmB,CA2EzD"}

package/dist/hooks/useCollectionFollow.js

@@ -0,0 +1,202 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../internal/requestTimeouts.js';
+import { getTransport } from '../internal/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../internal/transport.js';
+/**
+ * The closed set of HOST refusal codes, as a runtime Set.
+ *
+ * 🔴 THIS EXISTS BECAUSE THE ERROR CHANNEL IS NOT AN ENUM. The host sends either
+ * one of these codes or a free-text server message, so "is this a code?" is a
+ * MEMBERSHIP question at runtime, not a type-level one — a `switch` over the
+ * union type would silently treat `"You do not have permission…"` as unmatched
+ * prose while a typo'd literal compiled fine. Derived from the array below so
+ * the two cannot drift.
+ */
+export const COLLECTION_FOLLOW_ERROR_CODES = [
+    'invalid-request',
+    'sign-in-required',
+    'review-mode',
+    'not-ready',
+    'declined',
+    'collection-unavailable',
+];
+const CODE_SET = new Set(COLLECTION_FOLLOW_ERROR_CODES);
+/**
+ * `true` when `error` is one of the host's CLOSED refusal codes rather than a
+ * free-text server message.
+ *
+ * Use it before comparing against a code — see
+ * {@link COLLECTION_FOLLOW_ERROR_CODES} for why equality alone is not enough.
+ */
+export function isCollectionFollowErrorCode(error) {
+    return CODE_SET.has(error);
+}
+/**
+ * A collection follow/unfollow failure.
+ *
+ * `.code` is the host's refusal code when the host refused, and `undefined`
+ * otherwise.
+ *
+ * 🔴 `.code === undefined` IS NOT BY ITSELF "A SERVER MESSAGE WORTH SHOWING" —
+ * that reading is why {@link CollectionFollowError.timedOut} exists, and this
+ * paragraph asserted it until an audit caught it. TWO different failures land
+ * here: a server message the host forwarded verbatim, and a TRANSPORT TIMEOUT
+ * whose `.message` is an SDK-internal string. **Check `.timedOut` first**;
+ * `.code === undefined && !timedOut` is the branch whose `.message` is meant to
+ * be rendered.
+ */
+export class CollectionFollowError extends Error {
+    /** The closed host refusal code, or `undefined` for a server/transport error. */
+    code;
+    /**
+     * The SDK transport gave up waiting — no reply ever arrived.
+     *
+     * 🔴 CHECK THIS BEFORE SHOWING `.message`. A timeout also has
+     * `code === undefined`, so "no code ⇒ a server message worth rendering" is
+     * false, and acting on it puts an SDK-internal string
+     * (`IframeTransport: request "SET_COLLECTION_FOLLOW" timed out after 600000ms`)
+     * in front of a viewer. 🔴 It also does NOT mean no write occurred: the host
+     * may have completed the follow and failed only to deliver the reply, so do
+     * not present a timeout as "nothing happened" — re-read your own state.
+     */
+    timedOut;
+    /**
+     * The viewer DISMISSED the host's consent confirm, so NO WRITE OCCURRED.
+     *
+     * 🔴 Not an error condition to shout about, and it is trustworthy in the one
+     * direction that matters: the host takes its consent latch synchronously
+     * before the write, so `declined` can never be reported for a follow that
+     * landed. Revert optimistic state and render nothing.
+     */
+    declined;
+    /**
+     * There is no session. Route this into `useRequestSignIn()` rather than
+     * showing an error — the viewer's next step is signing in, not retrying.
+     */
+    signInRequired;
+    constructor(error, opts) {
+        super(error);
+        this.name = 'CollectionFollowError';
+        this.timedOut = opts?.timedOut === true;
+        if (isCollectionFollowErrorCode(error))
+            this.code = error;
+        this.declined = error === 'declined';
+        this.signInRequired = error === 'sign-in-required';
+    }
+}
+/**
+ * Follow / unfollow a collection for the viewer through the host-mediated
+ * `SET_COLLECTION_FOLLOW` → `COLLECTION_FOLLOW_RESULT` bridge.
+ *
+ * TOKEN-INDEPENDENT — this needs NO block scope and sends no token. The host
+ * calls the session-authed `collection.follow` / `collection.unfollow`
+ * procedures, which self-bind to the viewer server-side, so `collectionId` is
+ * the only thing a block influences.
+ *
+ * 🔴 EVERY CALL OPENS A HOST-CHROME CONSENT CONFIRM NAMING THE COLLECTION, and
+ * that click is the ONLY consent this path has ever had. The HTTP predecessor's
+ * `collections:write:self` scope was consent-exempt server-side and prompted
+ * nobody, so moving to this bridge TIGHTENS the path — it does not loosen it.
+ * What it costs is the manifest `scopes` declaration a moderator reads before
+ * install. Do not add a "skip the confirm" option; there is nothing behind it.
+ *
+ * Because the reply waits on a person, the request carries
+ * {@link HUMAN_INTERACTION_TIMEOUT_MS} (10 min) rather than the ~30s protocol
+ * default — it resolves the instant the viewer acts, and the ceiling only bounds
+ * an abandoned dialog.
+ *
+ * 🔴 THE HOST RESOLVES THE COLLECTION'S NAME ITSELF and bounds that to 20
+ * DISTINCT ids per block instance. Past the cap it refuses with
+ * `collection-unavailable` — the SAME code a collection the viewer cannot see
+ * gets — so a block driving many ids degrades into "we cannot act on this",
+ * never into an enumeration oracle. Repeats of an already-admitted id are free
+ * forever, so re-following a collection the viewer has already been asked about
+ * keeps working.
+ *
+ * @example
+ * const { setFollow, pending } = useCollectionFollow();
+ * const { requestSignIn } = useRequestSignIn();
+ *
+ * const toggle = async () => {
+ *   setFollowed((f) => !f); // optimistic
+ *   try {
+ *     const r = await setFollow({ collectionId, follow: !followed });
+ *     setFollowed(r.followed); // adopt the host's echo, not the guess
+ *   } catch (e) {
+ *     setFollowed(followed); // roll back
+ *     if (e instanceof CollectionFollowError) {
+ *       if (e.signInRequired) return requestSignIn();
+ *       if (e.declined) return; // the viewer said no — say nothing
+ *       if (e.timedOut) return showToast('Still working — check back in a moment.');
+ *       showToast(e.message); // a real server message, safe to render
+ *     }
+ *   }
+ * };
+ */
+export function useCollectionFollow() {
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    // Same guard as `useTip`/`useWildcardPack`: this request can outlive the
+    // component by up to ten minutes (the viewer may leave the confirm open), so
+    // it is the LONGEST-lived state write in the package. Writing after unmount
+    // is not merely a warning here — a `pending` toggled on an unmounted control
+    // is state nobody can clear.
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const setFollow = useCallback(async (args) => {
+        if (mountedRef.current) {
+            setPending(true);
+            setError(null);
+        }
+        try {
+            const reply = await sendTypedRequest(getTransport(), {
+                type: 'SET_COLLECTION_FOLLOW',
+                payload: { collectionId: args.collectionId, follow: args.follow },
+            }, 'COLLECTION_FOLLOW_RESULT', 
+            // See the `'human'` bucketing in `internal/requestTimeouts.ts`: the
+            // host answers only when the viewer clicks or dismisses its confirm.
+            { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+            if (reply.error || !reply.result) {
+                // 🔴 `||`, NOT `??` — the opposite of `useWildcardPack`, and for the
+                // opposite reason. `isValidCollectionFollowResult` gates `error` on
+                // SHAPE only (it has to: the channel carries free-text server
+                // messages), so a host `error: ''` is a VALID reply that reaches here.
+                // `??` would then throw an Error with an EMPTY message for an account
+                // write, which renders as a blank failure. Fall through to a code that
+                // at least names a real outcome.
+                throw new CollectionFollowError(reply.error || 'collection-unavailable');
+            }
+            return reply.result;
+        }
+        catch (err) {
+            // A transport timeout arrives as a plain Error; wrap it so callers have
+            // ONE error type to test, with `.code` left undefined (it is not a host
+            // refusal). Re-wrapping our own error would lose `.code`, so pass it
+            // through.
+            const wrapped = err instanceof CollectionFollowError
+                ? err
+                : new CollectionFollowError(err instanceof Error ? err.message : String(err), {
+                    // Structural, not a message match — see `RequestTimeoutError`.
+                    timedOut: err instanceof RequestTimeoutError,
+                });
+            if (mountedRef.current)
+                setError(wrapped);
+            // 🔴 THROWN UNCONDITIONALLY, even when unmounted. The caller's `await`
+            // is not the component — an app that persists the result (a toast queue,
+            // a store) must still learn the write failed, and swallowing it here
+            // would make an unmount look like a success.
+            throw wrapped;
+        }
+        finally {
+            if (mountedRef.current)
+                setPending(false);
+        }
+    }, []);
+    return { setFollow, pending, error };
+}
+//# sourceMappingURL=useCollectionFollow.js.map

package/dist/hooks/useCollectionFollow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCollectionFollow.js","sourceRoot":"","sources":["../../src/hooks/useCollectionFollow.ts"],"names":[],"mappings":"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"}