fix(review): address all code-review findings from PR #262

github-actions[bot] · AllTerrainDeveloper · github-actions[bot] · commit 4466e89d6b02 · 2026-05-21T17:23:44.000Z
- Remove duplicate 'Wholesale rebuild' comment block in layer.ts
- Harden normalizeLegacyPayload pass-through: check obj.kind !== undefined/null
  instead of an explicit known-kinds allowlist that needs updating per new kind
- Add whenWindowId() non-reject warning + isParentReachable() guard pattern
  to docs/use-from-a-plugin.md and docs/examples/iframe-initiated-window.md

Co-authored-by: Daniel López Sánchez (prismiwi2015) &lt;AllTerrainDeveloper@users.noreply.github.com&gt;
diff --git a/docs/examples/iframe-initiated-window.md b/docs/examples/iframe-initiated-window.md
@@ -68,10 +68,14 @@ function PreviewSidebar() {
     const [ streaming, setStreaming ] = useState( false );
 
     const open = async () => {
-        // We need to know our own window id so we can include it in
-        // diagnostics or sub-topic names. `whenWindowId()` resolves
-        // once the parent has handshaken (always before any user
-        // interaction in practice).
+        // Guard before awaiting the window id. `whenWindowId()` never
+        // rejects — if the parent shell never sends a handshake (e.g.
+        // cross-origin parent, page opened outside Desktop Mode) the
+        // Promise hangs forever. `isParentReachable()` resolves that
+        // ambiguity synchronously.
+        if ( ! wp.desktop.iframe.isParentReachable() ) {
+            return; // Not running inside Desktop Mode — bail silently.
+        }
         const myWindowId = await wp.desktop.iframe.whenWindowId();
 
         // Tell the parent shell to open a Preview window paired with us.
diff --git a/docs/use-from-a-plugin.md b/docs/use-from-a-plugin.md
@@ -87,6 +87,26 @@ We could. We deliberately don't, because:
 
 If you genuinely need a registry-based install (e.g. a CI runner that can't see this repo's filesystem), open an issue and we'll re-evaluate.
 
+## Iframe bridge gotcha — `whenWindowId()` never rejects
+
+If your plugin code runs inside a chromeless wp-admin iframe and calls
+`wp.desktop.iframe.whenWindowId()`, be aware that the returned Promise
+**never rejects**. When the page is not running inside Desktop Mode (a
+cross-origin parent, a direct admin URL visit, a unit-test harness) the
+Promise simply hangs forever — any `await` after it will never resume.
+
+Always guard with `isParentReachable()` first:
+
+```javascript
+if ( ! wp.desktop.iframe.isParentReachable() ) {
+    return; // Not inside Desktop Mode — skip iframe-bridge code.
+}
+const windowId = await wp.desktop.iframe.whenWindowId();
+```
+
+The same caveat applies to `Window.whenContentReady()` on the shell side —
+it never rejects if the content iframe never signals readiness.
+
 ## Troubleshooting
 
 - **`Cannot find module 'desktop-mode'`** — confirm the `file:` path is correct relative to your plugin's `package.json` location, then re-run `npm install`.
diff --git a/src/desktop-files/layer.ts b/src/desktop-files/layer.ts
@@ -534,10 +534,6 @@ export function mountFilesLayer( host: HTMLElement, folderId = 0 ): FilesLayer {
 			return;
 		}
 
-		// Wholesale rebuild — last resort. Pin-flag flips, parent-
-		// folder moves, file-type changes, all land here. Plugins
-		// that want stable decorations re-attach via `tile-rendered`.
-
 		// Wholesale rebuild — last-resort path for transitions the
 		// incremental walker can't handle (pin-flag flips, parent-
 		// folder moves, file-type changes). Plugins that want stable
diff --git a/src/drag-bridge.ts b/src/drag-bridge.ts
@@ -160,11 +160,7 @@ function normalizeLegacyPayload(
 		string,
 		unknown
 	>;
-	if (
-		obj.kind === 'attachment' ||
-		obj.kind === 'post' ||
-		obj.kind === 'user'
-	) {
+	if ( obj.kind !== undefined && obj.kind !== null ) {
 		return payload;
 	}
 	// Look-alike test for the legacy Media Library payload — id +
