From 3275fcf24da95ab6797e3e3711fce4cbf9d0ca36 Mon Sep 17 00:00:00 2001 From: Renfei Zhou Date: Thu, 19 Nov 2026 06:51:53 +0000 Subject: [PATCH 1/3] test(fork): the whiteboard tab must keep its board loaded while hidden On a board host the Whiteboard tab reloads its board each time the tab is shown again, and a board link clicked while the tab is hidden lands only after that reload. These browser tests show the board page surviving a hide, a show, a move to the other pane and a phone sheet that closes or maximizes, and a link reaching the loaded board once. They fail on main. Co-Authored-By: Claude Opus 5.5 --- .../WhiteboardPanel.browser.test.tsx | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 apps/web/src/fork/whiteboard/WhiteboardPanel.browser.test.tsx diff --git a/apps/web/src/fork/whiteboard/WhiteboardPanel.browser.test.tsx b/apps/web/src/fork/whiteboard/WhiteboardPanel.browser.test.tsx new file mode 100644 index 0000000000000..cf6fa15ea86a1 --- /dev/null +++ b/apps/web/src/fork/whiteboard/WhiteboardPanel.browser.test.tsx @@ -0,0 +1,172 @@ +import { scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime/environment"; +import { EnvironmentId, ThreadId } from "@t3tools/contracts"; +import { describe, expect, it, vi } from "vite-plus/test"; + +import { render } from "../../../test/render"; +import { useRightPanelStore } from "../../rightPanelStore"; +import { postWhiteboardHover, showBoardRef } from "./boardChannel"; +import { WhiteboardPanel } from "./WhiteboardPanel"; + +const role = vi.hoisted(() => ({ projectRoot: "/project" })); + +vi.mock("./role", () => ({ + useBoardHostRole: () => ({ menu: {} }), + isBoardHost: () => true, + isTopWindow: () => true, + boardOfferedFor: () => true, + useBoardOfferedFor: () => true, + readThreadProjectRoot: () => role.projectRoot, + useThreadProjectRoot: () => role.projectRoot, +})); + +type BoardWindow = Window & { kept?: boolean; received?: unknown[] }; + +// Each test has its own thread and project, so boards a test leaves loaded never meet another test. +function setup(name: string) { + role.projectRoot = `/project-${name}`; + const threadRef = scopeThreadRef(EnvironmentId.make("env"), ThreadId.make(`thread-${name}`)); + useRightPanelStore.getState().open(threadRef, "whiteboard"); + return threadRef; +} + +function Panes(props: { + readonly at: "left" | "right" | null; + readonly threadRef: ReturnType; + readonly sheet?: boolean; +}) { + const pane = (side: "left" | "right") => ( +
+ {props.at === side ? : null} +
+ ); + return ( +
+ {pane("left")} + {pane("right")} +
+ ); +} + +const shownFrame = (container: HTMLElement) => + container.querySelector('iframe[title="Whiteboard"]'); + +// The board page's own `wb-ready`, posted from inside the frame so the frame is its source. +async function loadedBoard(container: HTMLElement): Promise { + const board = await vi.waitFor(() => { + const window = shownFrame(container)?.contentWindow as BoardWindow | null | undefined; + expect(window?.location.search).toContain("embed=panel"); + expect(window?.document.readyState).toBe("complete"); + return window!; + }); + board.kept = true; + board.received = []; + board.addEventListener("message", (event) => board.received!.push(event.data)); + (board as Window & { eval: (code: string) => void }).eval( + 'parent.postMessage({ type: "wb-ready" }, location.origin)', + ); + return board; +} + +// Hover with no reference only clears a mark, which is harmless at any time. +const isNotAHoverEnd = (message: unknown) => { + const { type, ref } = message as { type?: unknown; ref?: unknown }; + return type !== "wb-hover" || ref !== null; +}; + +function closeWhiteboardTab(threadRef: ReturnType) { + const surfaces = useRightPanelStore.getState().byThreadKey[scopedThreadKey(threadRef)]?.surfaces; + for (const surface of surfaces ?? []) + if (surface.kind === "whiteboard") + useRightPanelStore.getState().closeSurface(threadRef, surface.id); +} + +describe("WhiteboardPanel", () => { + it("keeps its board page loaded while hidden and when it moves to the other pane", async () => { + const threadRef = setup("keep"); + await using screen = await render(, { router: false }); + const board = await loadedBoard(screen.container); + + for (const at of [null, "left", null, "right", "left"] as const) { + await screen.rerender(); + if (at === null) continue; + expect(shownFrame(screen.container)?.closest("[data-pane]")?.getAttribute("data-pane")).toBe( + at, + ); + expect((shownFrame(screen.container)?.contentWindow as BoardWindow | null)?.kept).toBe(true); + } + expect(shownFrame(screen.container)?.contentWindow).toBe(board); + closeWhiteboardTab(threadRef); + }); + + it("highlights a link clicked while hidden in the loaded board, once, and pauses it while hidden", async () => { + const threadRef = setup("link"); + await using screen = await render(, { router: false }); + const board = await loadedBoard(screen.container); + await screen.rerender(); + + postWhiteboardHover("board://r/1,2,3,4", document.createElement("a")); + showBoardRef("board://r/5,6,7,8", threadRef); + await screen.rerender(); + + await vi.waitFor(() => + expect(board.received).toContainEqual({ type: "wb-highlight", ref: "board://r/5,6,7,8" }), + ); + expect(shownFrame(screen.container)?.contentWindow).toBe(board); + expect(board.received!.filter(isNotAHoverEnd)).toEqual([ + { type: "wb-visible", visible: false }, + { type: "wb-visible", visible: true }, + { type: "wb-highlight", ref: "board://r/5,6,7,8" }, + ]); + closeWhiteboardTab(threadRef); + }); + + it("keeps a click that opened the board while it moves to the other pane before it is ready", async () => { + const threadRef = setup("move"); + await using screen = await render(, { router: false }); + showBoardRef("board://r/5,6,7,8", threadRef); + await screen.rerender(); + + const board = await loadedBoard(screen.container); + await vi.waitFor(() => + expect(board.received).toEqual([{ type: "wb-highlight", ref: "board://r/5,6,7,8" }]), + ); + closeWhiteboardTab(threadRef); + }); + + it.each([ + [ + "closes", + "close", + (ref: ReturnType) => useRightPanelStore.getState().close(ref), + ], + [ + "maximizes", + "maximize", + (ref: ReturnType) => useRightPanelStore.getState().setMaximized(ref, true), + ], + ] as const)( + "keeps its board page loaded when its sheet %s and its portal node leaves first", + async (_, name, sheetGoes) => { + const threadRef = setup(name); + await using screen = await render(, { + router: false, + }); + const board = await loadedBoard(screen.container); + sheetGoes(threadRef); + // The sheet's portal node leaves the document before React detaches the refs inside it. + screen.container.remove(); + await screen.unmount(); + + useRightPanelStore.getState().open(threadRef, "whiteboard"); + await using reopened = await render(, { + router: false, + }); + expect(shownFrame(reopened.container)?.contentWindow).toBe(board); + expect(board.kept).toBe(true); + closeWhiteboardTab(threadRef); + }, + ); +}); From 491b0fe55c7c97c9a7fa53f9f41079a119b04078 Mon Sep 17 00:00:00 2001 From: Renfei Zhou Date: Thu, 19 Nov 2026 06:52:49 +0000 Subject: [PATCH 2/3] fix(fork): keep the right-panel board loaded while its tab is hidden The Whiteboard tab's frame lived inside the shown tab, so another tab, a closed panel or another thread removed it, and showing it again reloaded the board. The board channel now owns one frame per board page and moves it with Element.moveBefore between the tab and a hidden holder, so the page stays loaded. A board in the phone sheet moves out when the panel closes or maximizes, before the sheet leaves the page. At most two boards stay loaded per window; closing a board's last Whiteboard tab unloads it. A board link while the tab is hidden shows the loaded board and highlights at once. A hidden board stops drawing (wb-visible) and stops again if tldraw restarts its loop, while its store and sync keep running, so edits made just before hiding still reach the server. A board page that reloads itself tells T3 (wb-unload), which waits for its next wb-ready. A board showing a sync error reloads when its tab is shown again. A highlight reads the board's current size first. Browsers without moveBefore reload as before. Co-Authored-By: Claude Opus 5.5 --- .../WhiteboardPanel.browser.test.tsx | 61 +++++ .../src/fork/whiteboard/WhiteboardPanel.tsx | 27 +- .../whiteboard/boardChannel.logic.test.ts | 35 +++ .../src/fork/whiteboard/boardChannel.logic.ts | 16 +- apps/web/src/fork/whiteboard/boardChannel.ts | 257 ++++++++++++++---- fork/whiteboard/run-t3.md | 2 +- fork/whiteboard/web/board.tsx | 17 +- fork/whiteboard/web/bridge.ts | 10 + fork/whiteboard/web/panelHost.ts | 14 +- fork/whiteboard/web/refs.tsx | 45 ++- 10 files changed, 404 insertions(+), 80 deletions(-) diff --git a/apps/web/src/fork/whiteboard/WhiteboardPanel.browser.test.tsx b/apps/web/src/fork/whiteboard/WhiteboardPanel.browser.test.tsx index cf6fa15ea86a1..6fddea4450904 100644 --- a/apps/web/src/fork/whiteboard/WhiteboardPanel.browser.test.tsx +++ b/apps/web/src/fork/whiteboard/WhiteboardPanel.browser.test.tsx @@ -169,4 +169,65 @@ describe("WhiteboardPanel", () => { closeWhiteboardTab(threadRef); }, ); + + it("shows its board again when its sheet reopens before it is removed", async () => { + const threadRef = setup("reopen"); + await using screen = await render(, { + router: false, + }); + const board = await loadedBoard(screen.container); + useRightPanelStore.getState().close(threadRef); + expect(shownFrame(screen.container)).toBeNull(); + useRightPanelStore.getState().open(threadRef, "whiteboard"); + expect(shownFrame(screen.container)?.contentWindow).toBe(board); + closeWhiteboardTab(threadRef); + }); + + it("leaves its board unloaded when the sheet opens again after its last tab closed", async () => { + const threadRef = setup("evicted"); + await using screen = await render(, { + router: false, + }); + const frame = shownFrame(screen.container)!; + await loadedBoard(screen.container); + closeWhiteboardTab(threadRef); + useRightPanelStore.getState().toggleVisibility(threadRef); + expect(frame.isConnected).toBe(false); + }); + + it("holds a link for a board page that reloads until that page is ready again", async () => { + const threadRef = setup("reload"); + await using screen = await render(, { router: false }); + const board = await loadedBoard(screen.container); + await expect.element(screen.getByText("Loading board...")).not.toBeInTheDocument(); + (board as Window & { eval: (code: string) => void }).eval( + 'parent.postMessage({ type: "wb-unload" }, location.origin)', + ); + await expect.element(screen.getByText("Loading board...")).toBeInTheDocument(); + showBoardRef("board://r/5,6,7,8", threadRef); + // Messages from one window arrive in order, so a highlight sent now would arrive before this. + board.postMessage({ type: "probe" }, location.origin); + await vi.waitFor(() => expect(board.received).toContainEqual({ type: "probe" })); + expect(board.received!.filter(isNotAHoverEnd)).toEqual([{ type: "probe" }]); + board.received = []; + + (board as Window & { eval: (code: string) => void }).eval( + 'parent.postMessage({ type: "wb-ready" }, location.origin)', + ); + await vi.waitFor(() => + expect(board.received).toEqual([{ type: "wb-highlight", ref: "board://r/5,6,7,8" }]), + ); + closeWhiteboardTab(threadRef); + }); + + it("unloads its board when the Whiteboard tab closes", async () => { + const threadRef = setup("close"); + await using screen = await render(, { router: false }); + const frame = shownFrame(screen.container)!; + await loadedBoard(screen.container); + await screen.rerender(); + + closeWhiteboardTab(threadRef); + expect(frame.isConnected).toBe(false); + }); }); diff --git a/apps/web/src/fork/whiteboard/WhiteboardPanel.tsx b/apps/web/src/fork/whiteboard/WhiteboardPanel.tsx index b0dfb6bb196ce..ec09c4d54c53a 100644 --- a/apps/web/src/fork/whiteboard/WhiteboardPanel.tsx +++ b/apps/web/src/fork/whiteboard/WhiteboardPanel.tsx @@ -2,10 +2,10 @@ import { scopedThreadKey } from "@t3tools/client-runtime/environment"; import type { ScopedThreadRef } from "@t3tools/contracts"; import { useState } from "react"; -import { registerBoardFrame } from "./boardChannel"; +import { boardUrl, showBoard } from "./boardChannel"; import { useBoardHostRole, useBoardOfferedFor, useThreadProjectRoot } from "./role"; -/** The right panel's Whiteboard tab: the project's board, framed from the board page. */ +/** The right panel's Whiteboard tab: the project's board, which stays loaded while the tab is hidden. */ export function WhiteboardPanel(props: { readonly threadRef: ScopedThreadRef }) { const role = useBoardHostRole(); const projectRoot = useThreadProjectRoot(props.threadRef); @@ -19,36 +19,29 @@ export function WhiteboardPanel(props: { readonly threadRef: ScopedThreadRef }) ); } return ( - ); } -function BoardFrame(props: { readonly threadKey: string; readonly projectRoot: string }) { +function BoardSlot(props: { readonly url: string; readonly threadKey: string }) { const [ready, setReady] = useState(false); - // The React Compiler keeps this callback stable, so a re-render does not unregister the frame - // (which drops a click still waiting for it). - const registerFrame = (element: HTMLIFrameElement | null) => - element === null + // The React Compiler keeps this callback stable, so a re-render does not park and show the board. + const attachBoard = (slot: HTMLDivElement | null) => + slot === null ? undefined - : registerBoardFrame(element, props.threadKey, () => setReady(true)); + : showBoard(slot, { url: props.url, threadKey: props.threadKey, onReady: setReady }); return (
+
{ready ? null : (

Loading board...

)} - {/* oxlint-disable-next-line react/iframe-missing-sandbox -- the board is this origin's own page; it needs scripts and same-origin storage, which together make a sandbox moot. */} -