@civitai/blocks-react 0.53.0 → 0.53.1

package/README.md

@@ -35,7 +35,9 @@ export function App() {
   const rootRef = useRef<HTMLDivElement>(null);
   useBlockResize(rootRef);                 // host fits the iframe to content
 
-  if (!ready) return <div ref={rootRef}>Loading…</div>;
+  // No ref on the pre-init skeleton — useBlockResize observes the real root
+  // whenever it mounts, including on a later render.
+  if (!ready) return <div>Loading…</div>;
   // `context` is a union keyed on slotId — narrow with the guard, not a cast.
   if (!isModelSlotContext(context)) return <div ref={rootRef}>Wrong slot.</div>;
 
@@ -153,6 +155,12 @@ const rootRef = useRef<HTMLDivElement>(null);
 useBlockResize(rootRef);
 ```
 
+**The element may mount on a later render, and that is the normal case** — a
+block renders a skeleton until `BLOCK_INIT` lands. The hook keys on the observed
+*element*, so you do **not** need to pin the same `ref` to every branch of a
+loading/ready conditional to keep the host resizing. Put it on the root you
+actually want measured, in whichever branch renders it.
+
 > Also set `iframe.minHeight` in your manifest to the block's *real* rendered
 > height — a too-small minHeight makes the iframe seed short and grow-jump on
 > `BLOCK_READY` (CLS). Measure it in the dev harness (gotcha #53).
@@ -1039,7 +1047,7 @@ import {
 export function App() {
   const { ready, theme } = useBlockContext();
   const rootRef = useRef<HTMLDivElement>(null);
-  if (!ready) return <div ref={rootRef}>Loading…</div>;
+  if (!ready) return <div>Loading…</div>;
 
   return (
     // GOTCHA #60 — theme your OWN root; that's what the pack reads.

package/dist/hooks/useBlockResize.d.ts

@@ -9,11 +9,37 @@ import { type RefObject } from 'react';
  * - Inline path: `InlineTransport.sendMessage` is a no-op (the host DOM
  *   reflows naturally), so the observer fires but no message goes out.
  *
+ * 🔴 THE ELEMENT MAY MOUNT ON A LATER RENDER, AND THAT IS THE NORMAL CASE.
+ * Every block renders a skeleton until `BLOCK_INIT` lands, so on the first
+ * render there is nothing to observe. This hook therefore keys on the OBSERVED
+ * ELEMENT, not on the ref wrapper's identity — the same reasoning written down
+ * at `useBlockBreakpoint.ts`'s effect, with one mechanical difference that
+ * matters:
+ *
+ *   `useBlockBreakpoint` can compare `ref.current` read DURING RENDER, because
+ *   it re-renders its own caller and so always gets another render in which to
+ *   notice. This hook re-renders nobody. React attaches a ref during COMMIT,
+ *   i.e. AFTER the render that mounts it, so a `[ref.current]` dependency read
+ *   during render is a render behind and — with no further render coming —
+ *   never catches up. Measured: with `[ref.current]` as the dependency, a
+ *   component that mounts its root on the second render still observes
+ *   nothing.
+ *
+ * So the effect runs on every render (no dependency array) and does its own
+ * identity check against the element it is already observing. The check is a
+ * reference compare; the observer is torn down and rebuilt only when the
+ * element actually changes.
+ *
+ * Because of this, a block does NOT need to pin the same `ref` to every branch
+ * of a loading/ready conditional to keep the host resizing. That workaround was
+ * load-bearing before this fix and is not any more.
+ *
  * @param ref - Ref to the block's root DOM element to observe.
  *
  * @example
  * const rootRef = useRef<HTMLDivElement>(null);
  * useBlockResize(rootRef);              // host fits the iframe to content
+ * if (!ready) return <div>Loading…</div>;   // no ref needed on this branch
  * return <div ref={rootRef}>…</div>;
  */
 export declare function useBlockResize(ref: RefObject<HTMLElement | null>): void;

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

@@ -1 +1 @@
-{"version":3,"file":"useBlockResize.d.ts","sourceRoot":"","sources":["../../src/hooks/useBlockResize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAiBvE"}
+{"version":3,"file":"useBlockResize.d.ts","sourceRoot":"","sources":["../../src/hooks/useBlockResize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAyCvE"}

package/dist/hooks/useBlockResize.js

@@ -1,4 +1,4 @@
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { getTransport } from '../internal/singleton.js';
 /**
  * Observes the referenced element's height and asks the host to resize on
@@ -10,20 +10,67 @@ import { getTransport } from '../internal/singleton.js';
  * - Inline path: `InlineTransport.sendMessage` is a no-op (the host DOM
  *   reflows naturally), so the observer fires but no message goes out.
  *
+ * 🔴 THE ELEMENT MAY MOUNT ON A LATER RENDER, AND THAT IS THE NORMAL CASE.
+ * Every block renders a skeleton until `BLOCK_INIT` lands, so on the first
+ * render there is nothing to observe. This hook therefore keys on the OBSERVED
+ * ELEMENT, not on the ref wrapper's identity — the same reasoning written down
+ * at `useBlockBreakpoint.ts`'s effect, with one mechanical difference that
+ * matters:
+ *
+ *   `useBlockBreakpoint` can compare `ref.current` read DURING RENDER, because
+ *   it re-renders its own caller and so always gets another render in which to
+ *   notice. This hook re-renders nobody. React attaches a ref during COMMIT,
+ *   i.e. AFTER the render that mounts it, so a `[ref.current]` dependency read
+ *   during render is a render behind and — with no further render coming —
+ *   never catches up. Measured: with `[ref.current]` as the dependency, a
+ *   component that mounts its root on the second render still observes
+ *   nothing.
+ *
+ * So the effect runs on every render (no dependency array) and does its own
+ * identity check against the element it is already observing. The check is a
+ * reference compare; the observer is torn down and rebuilt only when the
+ * element actually changes.
+ *
+ * Because of this, a block does NOT need to pin the same `ref` to every branch
+ * of a loading/ready conditional to keep the host resizing. That workaround was
+ * load-bearing before this fix and is not any more.
+ *
  * @param ref - Ref to the block's root DOM element to observe.
  *
  * @example
  * const rootRef = useRef<HTMLDivElement>(null);
  * useBlockResize(rootRef);              // host fits the iframe to content
+ * if (!ready) return <div>Loading…</div>;   // no ref needed on this branch
  * return <div ref={rootRef}>…</div>;
  */
 export function useBlockResize(ref) {
+    /** The element the live observer is watching. `null` = watching nothing. */
+    const observedRef = useRef(null);
+    const observerRef = useRef(null);
+    // Unmount-only teardown. Declared FIRST so that on a remount (React
+    // StrictMode's deliberate double-invoke) its cleanup — which clears
+    // `observedRef` — runs before the observe effect's setup re-runs and finds a
+    // clean slate. React runs every cleanup before any setup.
+    useEffect(() => {
+        return () => {
+            observerRef.current?.disconnect();
+            observerRef.current = null;
+            observedRef.current = null;
+        };
+    }, []);
+    // No dependency array on purpose — see the block comment above. The identity
+    // check below, not a dependency list, is what makes this cheap.
     useEffect(() => {
+        if (typeof ResizeObserver === 'undefined')
+            return;
         const el = ref.current;
+        if (el === observedRef.current)
+            return; // already observing exactly this
+        observerRef.current?.disconnect();
+        observerRef.current = null;
+        observedRef.current = el;
         if (!el)
             return;
-        if (typeof ResizeObserver === 'undefined')
-            return;
         const transport = getTransport();
         let lastHeight = -1;
         const observer = new ResizeObserver((entries) => {
@@ -34,7 +81,7 @@ export function useBlockResize(ref) {
             transport.sendMessage({ type: 'RESIZE_IFRAME', payload: { height } });
         });
         observer.observe(el);
-        return () => observer.disconnect();
-    }, [ref]);
+        observerRef.current = observer;
+    });
 }
 //# sourceMappingURL=useBlockResize.js.map

package/dist/hooks/useBlockResize.js.map

@@ -1 +1 @@
-{"version":3,"file":"useBlockResize.js","sourceRoot":"","sources":["../../src/hooks/useBlockResize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAkB,MAAM,OAAO,CAAC;AAElD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,GAAkC;IAC/D,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC;QACvB,IAAI,CAAC,EAAE;YAAE,OAAO;QAChB,IAAI,OAAO,cAAc,KAAK,WAAW;YAAE,OAAO;QAElD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;QACjC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC;QACpB,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,CAAC,OAAO,EAAE,EAAE;YAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,MAAM,IAAI,EAAE,CAAC,YAAY,CAAC,CAAC;YAC5E,IAAI,MAAM,KAAK,UAAU;gBAAE,OAAO;YAClC,UAAU,GAAG,MAAM,CAAC;YACpB,SAAS,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QACxE,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;IACrC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AACZ,CAAC"}
+{"version":3,"file":"useBlockResize.js","sourceRoot":"","sources":["../../src/hooks/useBlockResize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAkB,MAAM,OAAO,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,UAAU,cAAc,CAAC,GAAkC;IAC/D,4EAA4E;IAC5E,MAAM,WAAW,GAAG,MAAM,CAAqB,IAAI,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,MAAM,CAAwB,IAAI,CAAC,CAAC;IAExD,oEAAoE;IACpE,oEAAoE;IACpE,6EAA6E;IAC7E,0DAA0D;IAC1D,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,GAAG,EAAE;YACV,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC;YAClC,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC;YAC3B,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC;QAC7B,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,6EAA6E;IAC7E,gEAAgE;IAChE,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,cAAc,KAAK,WAAW;YAAE,OAAO;QAElD,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC;QACvB,IAAI,EAAE,KAAK,WAAW,CAAC,OAAO;YAAE,OAAO,CAAC,iCAAiC;QAEzE,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC;QAClC,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC;QAC3B,WAAW,CAAC,OAAO,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC,EAAE;YAAE,OAAO;QAEhB,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;QACjC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC;QACpB,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,CAAC,OAAO,EAAE,EAAE;YAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,MAAM,IAAI,EAAE,CAAC,YAAY,CAAC,CAAC;YAC5E,IAAI,MAAM,KAAK,UAAU;gBAAE,OAAO;YAClC,UAAU,GAAG,MAAM,CAAC;YACpB,SAAS,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QACxE,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrB,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.53.0",
+  "version": "0.53.1",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",
@@ -122,7 +122,7 @@
     "react-dom": "^19.0.0",
     "typescript": "^5.9.2",
     "vitest": "^4.1.11",
-    "@civitai/app-sdk": "^0.45.0"
+    "@civitai/app-sdk": "^0.46.0"
   },
   "publishConfig": {
     "access": "public"