@civitai/blocks-react 0.57.3 → 0.58.0

package/README.md

@@ -211,13 +211,25 @@ const bp = useBlockBreakpoint();
 ### `useBlockToken()`
 
 Current block-scoped JWT, auto-refreshing ~2 min before expiry. Returns the token
-fields plus a `refresh()` for the 401-retry path.
+fields plus a `refresh()` for the 401-retry path, which **resolves with the new
+token**.
 
 ```tsx
 const { raw, scopes, expiresAt, buzzBudget, refresh } = useBlockToken();
-// after a 401: await refresh(); then retry the request once with the new `raw`.
+
+let res = await fetch(url, { headers: { Authorization: `Bearer ${raw}` } });
+if (res.status === 401) {
+  const fresh = await refresh();   // resolves WITH the new token
+  res = await fetch(url, { headers: { Authorization: `Bearer ${fresh.raw}` } });
+}
 ```
 
+> **Retry with the resolved token, not the `raw` you destructured.** That `raw` is
+> a `const` from the render closure that ran *before* the refresh — awaiting
+> `refresh()` re-renders the component but cannot reassign the binding your
+> in-flight callback is already holding. A retry that re-reads the outer `raw`
+> re-sends the stale JWT and 401s for exactly the reason the first call did.
+
 ### `useHostOrigin()`
 
 The validated host origin to direct-fetch the App Blocks HTTP API against —
@@ -1497,30 +1509,6 @@ does not publish — open an issue rather than reaching into `dist/internal/`.
 > exists for one caller: a `pnpm dev:live` harness. **It must never appear in a
 > test suite.** The free one is `createMockHost`, on `./testing`.
 
-### Why it has its own subpath
-
-Until `0.55.0` this code was exported from `./testing`. The argument for moving
-it, in full, is that **a client which spends the caller's money should not be
-reachable through an import path named `testing`** — the import line is the one
-piece of context that travels with every call site, and `…/testing` actively
-asserts the opposite of what this module does. That is
-[#334](https://github.com/civitai/civitai-app-starters/issues/334)'s literal
-closing condition.
-
-Two arguments that were made for this change and **do not hold** — recorded so
-they are not made again:
-
-- **It does not shrink the install.** Measured: **+4,447 B**. See
-  [What the host-simulation subpaths cost you](#what-the-host-simulation-subpaths-cost-you).
-- **It does not close a wrong-autocomplete hazard**, because there was none to
-  close. `createMockHost(options: MockHostOptions = {})` is callable bare;
-  `createLiveHost(options: LiveHostOptions)` takes a **required** argument whose
-  `blockToken` is a **required** short-lived RS256 JWT that a human mints and
-  pastes by hand. `createLiveHost()` and `createLiveHost({})` do not compile, so
-  nobody reaches this module by picking the wrong completion. Earlier revisions
-  of this file, of the changeset, and of #334 called the two signatures
-  "near-identical"; none of them had read the signatures.
-
 ### The whole surface
 
 One value and one type. `test/subpathSurfaces.test.ts` pins the runtime export
@@ -1553,6 +1541,10 @@ The same terms as `./testing`: a normal subpath of a `0.x` package where a minor
 may break it, with the runtime symbol set pinned by
 `test/subpathSurfaces.test.ts` so it cannot change silently.
 
+It moved off `./testing` in `0.55.0`: an import path named `testing` asserts the
+opposite of what this module does, and the import line is the one piece of context
+that travels with every call site.
+
 🔴 One cost worth stating plainly: publishing and documenting this subpath makes
 [#334](https://github.com/civitai/civitai-app-starters/issues/334) **item 3** —
 getting the live-host code out of the tarball entirely — *harder*, not easier.
@@ -1562,42 +1554,14 @@ many on a subpath nobody was told to rely on.
 
 ## What the host-simulation subpaths cost you
 
-Seven `dist/` modules — 266,790 B of JavaScript plus 77,338 B of `.d.ts` — are
-reachable only from `./testing` and `./live`, and from nothing under `.` or
-`./ui`. Measured by walking the built module graph:
-
-```text
-118,590  dist/internal/mockHost.js        ← ./testing  (createMockHost)
- 86,688  dist/internal/liveHost.js        ← ./live     (createLiveHost)
- 29,508  dist/internal/pickerOverlay.js   ← ./live     (via liveHost)
- 15,351  dist/internal/catalog.js         ← ./live     (via pickerOverlay)
-  9,141  dist/testing.js
-  4,697  dist/internal/consent.js         ← BOTH hosts import it
-  2,815  dist/live.js
-```
-
-**They ship in every install**, production dependency trees included. They are
-tree-shaken out of application *bundles* — no block ships a mock host to a
-browser — so this is `node_modules` weight, not bundle weight.
-
-🔴 **Splitting `createLiveHost` onto its own subpath removed none of this — it
-ADDS 4,447 B of code, and trimming the export list moved nothing either.**
-Measured with `pnpm pack` on both sides of the split, in a detached worktree so
-neither pack is contaminated by the other change in this release: **319 → 323
-entries, 1,590,099 B → 1,597,161 B uncompressed.** The only files that differ are
-
-```text
-+6,048  dist/live.*        (new: .js 2,815, .d.ts 2,839, + maps)
--1,692  dist/testing.*     (the re-export and its docblock leaving)
-   +91  package.json       (the new exports-map key)
-+2,615  README.md          (this section)
-```
+The `dist/` modules reachable only from `./testing` and `./live`, and from nothing
+under `.` or `./ui`, **ship in every install**, production dependency trees
+included. They are tree-shaken out of application *bundles* — no block ships a
+mock host to a browser — so this is `node_modules` weight, not bundle weight.
 
-`liveHost.js`, `pickerOverlay.js` and `catalog.js` do not appear in that diff at
-all — they are byte-identical and still in the tarball. `files` is
-`["dist", "README.md"]` and `tsconfig` compiles all of `src/**/*`, so the
-`exports` map has no bearing whatsoever on tarball contents; it decides only what
-a consumer can *name*.
+`files` is `["dist", "README.md"]` and `tsconfig` compiles all of `src/**/*`, so
+the `exports` map has no bearing whatsoever on tarball contents; it decides only
+what a consumer can *name*.
 **The `/live` split buys safety, not size.** Moving these bytes needs the code
 deleted or published as a second artifact; that is
 [#334](https://github.com/civitai/civitai-app-starters/issues/334) item 3, and it

package/dist/hooks/useBlockToken.d.ts

@@ -1,10 +1,11 @@
 import type { BlockToken } from '@civitai/app-sdk/blocks';
 /**
  * What {@link useBlockToken} returns: the live block token plus a manual
- * `refresh`. See `./returnTypeLedger.js`.
+ * `refresh` that resolves WITH the newly-minted token. See
+ * `./returnTypeLedger.js`.
  */
 export type UseBlockToken = BlockToken & {
-    refresh: () => Promise<void>;
+    refresh: () => Promise<BlockToken>;
 };
 /**
  * Returns the current block-scoped JWT and keeps it fresh.
@@ -14,21 +15,48 @@ export type UseBlockToken = BlockToken & {
  * snapshot, and the hook re-renders with the new token.
  *
  * Consumers also get a `refresh()` callable for the 401-retry path. Call it
- * after any API request returns 401 — it forces an immediate token mint and
- * resolves once the new token is applied to the snapshot.
+ * after any API request returns 401 — it forces an immediate token mint,
+ * applies the new token to the snapshot, and RESOLVES WITH that new
+ * {@link BlockToken}.
+ *
+ * 🔴 RETRY WITH THE RESOLVED TOKEN, NOT THE `raw` YOU DESTRUCTURED. The `raw`
+ * in scope was captured from the render closure that ran BEFORE the refresh;
+ * awaiting `refresh()` re-renders the component but cannot reassign a `const`
+ * binding inside an async callback that is already executing. So a retry that
+ * re-reads the outer `raw` re-sends the STALE token and 401s for exactly the
+ * reason the first call did. This is why `refresh()` resolves with the token:
+ * the resolved value is the only in-scope handle on the fresh JWT.
  *
  * @returns The {@link BlockToken} fields (`raw`, `scopes`, `expiresAt`,
- * `buzzBudget`, …) plus a `refresh()` for the 401-retry path.
+ * `buzzBudget`, …) plus a `refresh()` for the 401-retry path, which resolves
+ * with the new {@link BlockToken}.
  *
  * @example
  * const { raw, scopes, expiresAt, buzzBudget, refresh } = useBlockToken();
- * // after a 401: await refresh(); then retry the request once with the new `raw`.
+ * let res = await fetch(url, { headers: { Authorization: `Bearer ${raw}` } });
+ * if (res.status === 401) {
+ *   const fresh = await refresh();        // resolves WITH the new token
+ *   res = await fetch(url, { headers: { Authorization: `Bearer ${fresh.raw}` } });
+ * }
  */
 export declare function useBlockToken(): UseBlockToken;
 /**
  * Mint/await a token refresh for one block instance, coalescing concurrent calls
  * for the SAME `blockInstanceId`. Exported for the inline-mode multi-instance
  * dedup test — hooks call it via `useBlockToken().refresh`.
+ *
+ * Resolves with the REFRESHED {@link BlockToken} so a 401-retry has an in-scope
+ * handle on the new JWT — the caller's destructured `raw` belongs to a closure
+ * that ran before the refresh and cannot be reassigned by it.
+ *
+ * The value is read back off the transport SNAPSHOT rather than re-parsed from
+ * the reply payload, and that is the ordering this depends on:
+ * `IframeTransport.handleMessage` calls `applyTokenRefresh` BEFORE
+ * `pending.resolve`, deliberately (see the comment there), so by the time this
+ * `.then` runs the snapshot already holds the new token. Reading the snapshot
+ * keeps ONE parse of the wire token — the resolved value is the very object the
+ * next render observes, not a second `tokenFromWrapped` of the same bytes that
+ * could drift from it.
  */
-export declare function requestRefresh(blockInstanceId: string): Promise<void>;
+export declare function requestRefresh(blockInstanceId: string): Promise<BlockToken>;
 //# sourceMappingURL=useBlockToken.d.ts.map

package/dist/hooks/useBlockToken.js

@@ -12,15 +12,29 @@ const REFRESH_LEAD_MS = 2 * 60 * 1000;
  * snapshot, and the hook re-renders with the new token.
  *
  * Consumers also get a `refresh()` callable for the 401-retry path. Call it
- * after any API request returns 401 — it forces an immediate token mint and
- * resolves once the new token is applied to the snapshot.
+ * after any API request returns 401 — it forces an immediate token mint,
+ * applies the new token to the snapshot, and RESOLVES WITH that new
+ * {@link BlockToken}.
+ *
+ * 🔴 RETRY WITH THE RESOLVED TOKEN, NOT THE `raw` YOU DESTRUCTURED. The `raw`
+ * in scope was captured from the render closure that ran BEFORE the refresh;
+ * awaiting `refresh()` re-renders the component but cannot reassign a `const`
+ * binding inside an async callback that is already executing. So a retry that
+ * re-reads the outer `raw` re-sends the STALE token and 401s for exactly the
+ * reason the first call did. This is why `refresh()` resolves with the token:
+ * the resolved value is the only in-scope handle on the fresh JWT.
  *
  * @returns The {@link BlockToken} fields (`raw`, `scopes`, `expiresAt`,
- * `buzzBudget`, …) plus a `refresh()` for the 401-retry path.
+ * `buzzBudget`, …) plus a `refresh()` for the 401-retry path, which resolves
+ * with the new {@link BlockToken}.
  *
  * @example
  * const { raw, scopes, expiresAt, buzzBudget, refresh } = useBlockToken();
- * // after a 401: await refresh(); then retry the request once with the new `raw`.
+ * let res = await fetch(url, { headers: { Authorization: `Bearer ${raw}` } });
+ * if (res.status === 401) {
+ *   const fresh = await refresh();        // resolves WITH the new token
+ *   res = await fetch(url, { headers: { Authorization: `Bearer ${fresh.raw}` } });
+ * }
  */
 export function useBlockToken() {
     const snap = useTransportSnapshot();
@@ -64,6 +78,19 @@ const inFlightRefreshByInstance = new Map();
  * Mint/await a token refresh for one block instance, coalescing concurrent calls
  * for the SAME `blockInstanceId`. Exported for the inline-mode multi-instance
  * dedup test — hooks call it via `useBlockToken().refresh`.
+ *
+ * Resolves with the REFRESHED {@link BlockToken} so a 401-retry has an in-scope
+ * handle on the new JWT — the caller's destructured `raw` belongs to a closure
+ * that ran before the refresh and cannot be reassigned by it.
+ *
+ * The value is read back off the transport SNAPSHOT rather than re-parsed from
+ * the reply payload, and that is the ordering this depends on:
+ * `IframeTransport.handleMessage` calls `applyTokenRefresh` BEFORE
+ * `pending.resolve`, deliberately (see the comment there), so by the time this
+ * `.then` runs the snapshot already holds the new token. Reading the snapshot
+ * keeps ONE parse of the wire token — the resolved value is the very object the
+ * next render observes, not a second `tokenFromWrapped` of the same bytes that
+ * could drift from it.
  */
 export async function requestRefresh(blockInstanceId) {
     const existing = inFlightRefreshByInstance.get(blockInstanceId);
@@ -71,7 +98,7 @@ export async function requestRefresh(blockInstanceId) {
         return existing;
     const transport = getTransport();
     const refresh = sendTypedRequest(transport, { type: 'REQUEST_TOKEN', payload: { blockInstanceId } }, 'TOKEN_REFRESH_RESPONSE')
-        .then(() => undefined)
+        .then(() => transport.getSnapshot().token)
         .finally(() => {
         inFlightRefreshByInstance.delete(blockInstanceId);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.57.3",
+  "version": "0.58.0",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@civitai/components": "^0.7.0",
+    "@civitai/components": "^0.7.1",
     "@civitai/theme": "^0.4.0"
   },
   "comment-peerDependencies": "This floor is DERIVED, not chosen — the lowest published app-sdk that exports every symbol this package imports. Do not edit it without reading ./PEER_FLOOR.md (in-repo, unpublished) and tests/guards/blocks-react-peer-floor.test.mjs.",