@agent-native/core 0.137.5 → 0.137.7

package/corpus/templates/clips/desktop/src/components/MediaDeviceRow.tsx

@@ -104,7 +104,7 @@ export function MediaDeviceRow({
   const { open, setOpen, rowRef } = useRowMenu();
 
   const disabled = !on;
-  const canOpenMenu = !disabled || (kind === "mic" && !!onSystemAudioToggle);
+  const canOpenMenu = on || (kind === "mic" && !!onSystemAudioToggle);
   const defaultLabel = kind === "camera" ? "Default camera" : "Default mic";
   const accessLabel =
     kind === "camera" ? "Allow camera access" : "Allow microphone access";
@@ -112,106 +112,125 @@ export function MediaDeviceRow({
     kind === "camera" ? "Refresh cameras" : "Refresh microphones";
 
   return (
-    <div className={`row ${on ? "row-on" : "row-off"}`} ref={rowRef}>
-      <span className="row-icon">
-        <Icon />
-      </span>
-      <button
-        type="button"
-        className="row-button"
-        onClick={() => {
-          if (canOpenMenu) setOpen((v) => !v);
-        }}
-        disabled={!canOpenMenu}
-        title={label}
-      >
-        <span className="row-label">{label}</span>
-        {kind === "mic" && on ? (
-          <MicWave deviceId={selectedId} active={on && meterActive} />
-        ) : (
-          <span className="row-flex" aria-hidden />
-        )}
-        <span className="row-chev" aria-hidden>
-          <ChevronDown />
+    <div className="media-device-row" ref={rowRef}>
+      <div className={`row ${on ? "row-on" : "row-off"}`}>
+        <span className="row-icon">
+          <Icon />
         </span>
-      </button>
-      <Toggle
-        on={on}
-        onChange={(v) => {
-          if (!v) setOpen(false);
-          onToggle(v);
-        }}
-        label={kind === "camera" ? "Camera" : "Microphone"}
-      />
-      {open ? (
-        <div className="row-menu" role="menu">
+        <button
+          type="button"
+          className="row-button"
+          onClick={() => setOpen((v) => !v)}
+          disabled={disabled}
+          title={label}
+        >
+          <span className="row-label">{label}</span>
+          {kind === "mic" && on ? (
+            <MicWave deviceId={selectedId} active={on && meterActive} />
+          ) : (
+            <span className="row-flex" aria-hidden />
+          )}
+        </button>
+        {canOpenMenu ? (
           <button
             type="button"
-            className={`row-menu-item ${!selectedId ? "selected" : ""}`}
-            role="menuitemradio"
-            aria-checked={!selectedId}
-            onClick={() => {
-              onSelect("", "");
-              setOpen(false);
-            }}
+            className="row-menu-trigger"
+            onClick={() => setOpen((value) => !value)}
+            aria-label={on ? `Choose ${kind}` : "System audio settings"}
+            aria-expanded={open}
+            aria-haspopup="menu"
           >
-            <span className="row-menu-check" aria-hidden>
-              {!selectedId ? <CheckIcon /> : null}
-            </span>
-            <span className="row-menu-label">{defaultLabel}</span>
+            <ChevronDown />
           </button>
-          {devices.length === 0 ? (
-            <button
-              type="button"
-              className="row-menu-item row-menu-action"
-              role="menuitem"
-              onClick={() => {
-                onRefresh();
-                setOpen(false);
-              }}
-            >
-              <span className="row-menu-check" aria-hidden />
-              <span className="row-menu-label">{accessLabel}</span>
-            </button>
-          ) : (
+        ) : (
+          <span className="row-chev" aria-hidden>
+            <ChevronDown />
+          </span>
+        )}
+        <Toggle
+          on={on}
+          onChange={(v) => {
+            if (!v) setOpen(false);
+            onToggle(v);
+          }}
+          label={kind === "camera" ? "Camera" : "Microphone"}
+        />
+      </div>
+      {open && canOpenMenu ? (
+        <div className="row-menu" role="menu">
+          {on ? (
             <>
-              {devices.map((d) => {
-                const isSelected = !!selectedId && d.deviceId === selectedId;
-                return (
-                  <button
-                    key={d.deviceId}
-                    type="button"
-                    className={`row-menu-item ${isSelected ? "selected" : ""}`}
-                    role="menuitemradio"
-                    aria-checked={isSelected}
-                    onClick={() => {
-                      onSelect(d.deviceId, d.label);
-                      setOpen(false);
-                    }}
-                  >
-                    <span className="row-menu-check" aria-hidden>
-                      {isSelected ? <CheckIcon /> : null}
-                    </span>
-                    <span className="row-menu-label">
-                      {d.label || (kind === "camera" ? "Camera" : "Microphone")}
-                    </span>
-                  </button>
-                );
-              })}
               <button
                 type="button"
-                className="row-menu-item row-menu-action"
-                role="menuitem"
+                className={`row-menu-item ${!selectedId ? "selected" : ""}`}
+                role="menuitemradio"
+                aria-checked={!selectedId}
                 onClick={() => {
-                  onRefresh();
+                  onSelect("", "");
                   setOpen(false);
                 }}
               >
-                <span className="row-menu-check" aria-hidden />
-                <span className="row-menu-label">{refreshLabel}</span>
+                <span className="row-menu-check" aria-hidden>
+                  {!selectedId ? <CheckIcon /> : null}
+                </span>
+                <span className="row-menu-label">{defaultLabel}</span>
               </button>
+              {devices.length === 0 ? (
+                <button
+                  type="button"
+                  className="row-menu-item row-menu-action"
+                  role="menuitem"
+                  onClick={() => {
+                    onRefresh();
+                    setOpen(false);
+                  }}
+                >
+                  <span className="row-menu-check" aria-hidden />
+                  <span className="row-menu-label">{accessLabel}</span>
+                </button>
+              ) : (
+                <>
+                  {devices.map((d) => {
+                    const isSelected =
+                      !!selectedId && d.deviceId === selectedId;
+                    return (
+                      <button
+                        key={d.deviceId}
+                        type="button"
+                        className={`row-menu-item ${isSelected ? "selected" : ""}`}
+                        role="menuitemradio"
+                        aria-checked={isSelected}
+                        onClick={() => {
+                          onSelect(d.deviceId, d.label);
+                          setOpen(false);
+                        }}
+                      >
+                        <span className="row-menu-check" aria-hidden>
+                          {isSelected ? <CheckIcon /> : null}
+                        </span>
+                        <span className="row-menu-label">
+                          {d.label ||
+                            (kind === "camera" ? "Camera" : "Microphone")}
+                        </span>
+                      </button>
+                    );
+                  })}
+                  <button
+                    type="button"
+                    className="row-menu-item row-menu-action"
+                    role="menuitem"
+                    onClick={() => {
+                      onRefresh();
+                      setOpen(false);
+                    }}
+                  >
+                    <span className="row-menu-check" aria-hidden />
+                    <span className="row-menu-label">{refreshLabel}</span>
+                  </button>
+                </>
+              )}
             </>
-          )}
+          ) : null}
           {kind === "mic" && onSystemAudioToggle ? (
             <div className="row-menu-toggle">
               <span className="row-menu-toggle-label">Record System audio</span>

package/corpus/templates/clips/desktop/src/styles.css

@@ -605,6 +605,10 @@ body[data-clips-route="recording-pill"] #root {
 }
 
 /* Popover menu rendered below a device row. */
+.media-device-row {
+  position: relative;
+}
+
 .row-menu {
   position: absolute;
   top: calc(100% + 4px);
@@ -645,7 +649,21 @@ body[data-clips-route="recording-pill"] #root {
   background: var(--surface-hover);
 }
 
-/* System-audio toggle sits below the device list, separated by a divider. */
+.row-menu-trigger {
+  display: inline-flex;
+  align-items: center;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: var(--fg-muted);
+  cursor: pointer;
+}
+
+.row-menu-trigger:focus-visible {
+  box-shadow: 0 0 0 2px var(--brand-ring);
+  border-radius: 4px;
+}
+
 .row-menu-toggle {
   display: flex;
   align-items: center;

package/corpus/templates/design/app/components/design/DesignCanvas.tsx

@@ -1293,6 +1293,10 @@ export function DesignCanvas({
     [probeBridgeReadinessUntilDrained],
   );
   const [renderedContent, setRenderedContent] = useState(content);
+  // What a freshly loaded document already contains, since srcdoc is built from
+  // it. The load handler below needs this to skip redundant pushes.
+  const renderedContentRef = useRef(renderedContent);
+  renderedContentRef.current = renderedContent;
   // True while a drawing send is capturing/compositing/uploading the
   // annotated screenshot (see design-canvas/annotation-snapshot.ts). Drives
   // SharedDrawOverlay's busy Send state so a slow capture can't be triggered
@@ -4043,6 +4047,9 @@ export function DesignCanvas({
     const replaceLatestRuntimeContent = () => {
       const nextContent = runtimeReplacementContentRef.current;
       if (nextContent === undefined) return;
+      // The document that just loaded was built from these bytes; swapping it
+      // for itself only costs a blank frame.
+      if (renderedContentRef.current === nextContent) return;
       if (replaceRuntimeContentInPlace(nextContent)) {
         lastRuntimeReplacementKeyRef.current = runtimeReplacementKeyRef.current;
         lastRuntimeReplacementContentRef.current = nextContent;

package/corpus/templates/design/app/components/design/MultiScreenCanvas.tsx

@@ -244,7 +244,10 @@ import {
   sameResolvedMetadata,
   type ResolvedMetadataCacheEntry,
 } from "./multi-screen/screen-content-cache";
-import { setWheelCameraGestureActive } from "./multi-screen/wheel-gesture-state";
+import {
+  isWheelCameraGestureActive,
+  setWheelCameraGestureActive,
+} from "./multi-screen/wheel-gesture-state";
 
 // Figma parity: a plain click (no drag) with the rectangle or ellipse tool
 // places a 100x100 shape. Both tools share this default via the "else"
@@ -340,6 +343,13 @@ import {
   screenPxToCanvasPx,
   stopPercentFromDraggedPoint,
 } from "./multi-screen/gradient-overlay-geometry";
+import {
+  applyScreenPaintSuppression,
+  collectScreenPaintTargets,
+  resolveSuppressedScreenIds,
+  type ScreenPaintCandidate,
+  type ScreenPaintTarget,
+} from "./multi-screen/paint-suppression";
 import {
   getPrimitiveDropTargetForPoint,
   getPrimitiveLowZoomHitRect,
@@ -651,26 +661,33 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         : null,
     [boardFrameGeometry],
   );
+  // Both board layers must ask this one question: an empty <body> is a truthy
+  // string, and the replica is opaque, so a string-only gate slabs the board.
+  const boardSurfaceHtml = hasBoardSurfaceContent(boardFileContent)
+    ? boardFileContent
+    : undefined;
+  const boardHasSurfaceContent = boardSurfaceHtml !== undefined;
   const boardStaticPreviewContent = useMemo(() => {
     if (
       !boardFrameGeometry ||
       !boardStaticPreviewViewport ||
-      !boardFileContent
+      !boardSurfaceHtml
     ) {
       return null;
     }
     return getBoardSurfaceStaticPreviewContent({
-      html: boardFileContent,
+      html: boardSurfaceHtml,
       logicalGeometry: boardFrameGeometry,
       viewport: boardStaticPreviewViewport,
     });
-  }, [boardFileContent, boardFrameGeometry, boardStaticPreviewViewport]);
+  }, [boardSurfaceHtml, boardFrameGeometry, boardStaticPreviewViewport]);
   const showBoardStaticPreview = Boolean(
     boardFrameGeometry &&
     boardSurfaceRenderGeometry &&
     boardStaticPreviewContent &&
     shouldRenderBoardSurfaceStaticPreview({
       zoom: canvasZoom,
+      hasSurfaceContent: boardHasSurfaceContent,
       viewportGeometry: boardViewportGeometry,
       renderGeometry: boardSurfaceRenderGeometry,
     }),
@@ -960,6 +977,12 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   const liveScreenIdsRef = useRef<Set<string>>(new Set());
   const lastVisibleEpochByScreenIdRef = useRef<Map<string, number>>(new Map());
   const cullAccessEpochRef = useRef(0);
+  const wheelGestureFilteredIframesRef = useRef<HTMLElement[]>([]);
+  // Paint suppression is resolved imperatively against the live camera, so its
+  // inputs live in refs readable from applyViewToDom's render-free tick.
+  const screenPaintCandidatesRef = useRef<ScreenPaintCandidate[]>([]);
+  const screenPaintTargetsRef = useRef<ScreenPaintTarget[]>([]);
+  const surfaceSizeRef = useRef({ width: 0, height: 0 });
   useEffect(() => {
     const liveScreenIds = new Set(screens.map((screen) => screen.id));
     for (const id of hasBeenVisibleScreenIdsRef.current) {
@@ -992,6 +1015,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     const surface = surfaceRef.current;
     if (!surface) return;
     const updateSize = (width: number, height: number) => {
+      surfaceSizeRef.current = { width, height };
       setSurfaceSize((current) =>
         current.width === width && current.height === height
           ? current
@@ -6643,6 +6667,24 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     [activeTool, localActiveTool, updateAltHoverMeasurement, updatePenPointer],
   );
 
+  // Overscan is deliberately excluded: this answers "is it on screen right
+  // now", and anything off screen costs nothing to leave unpainted.
+  const syncScreenPaintSuppression = useCallback(() => {
+    applyScreenPaintSuppression(
+      screenPaintTargetsRef.current,
+      resolveSuppressedScreenIds(
+        screenPaintCandidatesRef.current,
+        getOverscannedViewportCanvasBounds(
+          surfaceSizeRef.current,
+          panRef.current,
+          zoomRef.current,
+          0,
+        ),
+      ),
+      { relaxOnly: isWheelCameraGestureActive() },
+    );
+  }, []);
+
   // Push the current pan/zoom straight to the DOM. A wheel/pinch gesture must
   // NEVER re-render React's canvas tree during the gesture: each render re-runs
   // renderScreenContent (which re-creates the active screen's live DesignCanvas
@@ -6688,7 +6730,10 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       marqueeOverlay.style.width = `${Math.max(1, activeMarquee.width * nextScale)}px`;
       marqueeOverlay.style.height = `${Math.max(1, activeMarquee.height * nextScale)}px`;
     }
-  }, []);
+    // Same tick as the transform: a screen this move brings on screen must
+    // paint in the frame it becomes visible, not at the debounced commit.
+    syncScreenPaintSuppression();
+  }, [syncScreenPaintSuppression]);
 
   const startChromeSettle = useCallback(() => {
     if (chromeSettleTimerRef.current !== null) {
@@ -6714,6 +6759,10 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     if (wheelGestureActiveRef.current) {
       wheelGestureActiveRef.current = false;
       setWheelCameraGestureActive(false);
+      wheelGestureFilteredIframesRef.current.forEach((iframe) => {
+        if (iframe.isConnected) iframe.style.filter = "";
+      });
+      wheelGestureFilteredIframesRef.current = [];
       const muted = wheelGestureMutedElementsRef.current;
       wheelGestureMutedElementsRef.current = null;
       if (muted) {
@@ -6864,6 +6913,18 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         element.style.pointerEvents = "none";
       });
     wheelGestureMutedElementsRef.current = muted;
+    // A nested frame re-rasters on every scale change no matter what layer the
+    // canvas gets, starving the renderer. A filter — a no-op at this radius —
+    // gives each one a surface the compositor scales from cache. commitView must
+    // clear it, or they stay soft at rest.
+    const filtered: HTMLElement[] = [];
+    surface
+      .querySelectorAll<HTMLElement>("[data-screen-content] iframe")
+      .forEach((iframe) => {
+        iframe.style.filter = "blur(0.001px)";
+        filtered.push(iframe);
+      });
+    wheelGestureFilteredIframesRef.current = filtered;
   }, [cancelPendingStaticBoardSelection]);
 
   const flushPendingWheelGesture = useCallback(() => {
@@ -7615,23 +7676,23 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       pan,
       canvasZoom,
     );
+    const candidates = canvasFrames.map(({ screen, metadata, geometry }) => ({
+      id: screen.id,
+      geometry: getResponsiveScreenCullGeometry(
+        screen,
+        geometry,
+        (widthPx) =>
+          measuredIframeHeights[getBreakpointIframeId(screen.id, widthPx)],
+      ),
+      // Count only the breakpoint frames actually mounted (the row filters
+      // duplicates of the device width) so the iframe budget isn't
+      // over-consumed, prematurely evicting visible frames.
+      iframeCount:
+        1 +
+        visibleBreakpointWidths(screen.breakpointWidths, metadata.width).length,
+    }));
     const next = computeBoundedScreenCullState({
-      candidates: canvasFrames.map(({ screen, metadata, geometry }) => ({
-        id: screen.id,
-        geometry: getResponsiveScreenCullGeometry(
-          screen,
-          geometry,
-          (widthPx) =>
-            measuredIframeHeights[getBreakpointIframeId(screen.id, widthPx)],
-        ),
-        // Count only the breakpoint frames actually mounted (the row filters
-        // duplicates of the device width) so the iframe budget isn't
-        // over-consumed, prematurely evicting visible frames.
-        iframeCount:
-          1 +
-          visibleBreakpointWidths(screen.breakpointWidths, metadata.width)
-            .length,
-      })),
+      candidates,
       viewport,
       protectedScreenIds: protectedLiveScreenIds,
       previousLiveScreenIds: liveScreenIdsRef.current,
@@ -7642,6 +7703,11 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     liveScreenIdsRef.current = next.liveScreenIds;
     hasBeenVisibleScreenIdsRef.current = next.everVisibleScreenIds;
     lastVisibleEpochByScreenIdRef.current = next.lastVisibleEpochByScreenId;
+    screenPaintCandidatesRef.current = candidates.map(({ id, geometry }) => ({
+      id,
+      geometry,
+      tier: next.tierByScreenId.get(id) ?? "visible",
+    }));
     return next.tierByScreenId;
   }, [
     canvasFrames,
@@ -7651,6 +7717,16 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     protectedLiveScreenIds,
     surfaceSize,
   ]);
+  // No dependency array on purpose: any render can mount, unmount, or reorder a
+  // screen's content wrapper, and a wrapper React just mounted carries none of
+  // the suppression state this owns.
+  useEffect(() => {
+    screenPaintTargetsRef.current = collectScreenPaintTargets(
+      surfaceRef.current,
+    );
+    syncScreenPaintSuppression();
+  });
+
   const topScreenId = useMemo(
     () =>
       selectedIds.find((id) =>
@@ -7897,7 +7973,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
         {boardFileId &&
           boardFileContent !== undefined &&
-          hasBoardSurfaceContent(boardFileContent) &&
+          boardHasSurfaceContent &&
           (() => {
             const boardGeo = boardSurfaceRenderGeometry ?? {
               x: 0,
@@ -9448,18 +9524,10 @@ const Screen = memo(function Screen({
   const previewUrl = metadata.previewUrl ?? getPreviewUrl(screen.content);
   const previewViewport = getScreenPreviewViewport(metadata, geometry);
   const suppressNextClick = useRef(false);
-  // Overview viewport culling (PF22): a "culled" screen keeps its content
-  // (iframe/DesignCanvas) fully mounted — unmounting would lose all internal
-  // iframe state (scroll position, form input, in-progress Alpine/JS state)
-  // — but skips paint/layout cost for it via visibility:hidden +
-  // contentVisibility:"hidden" on the content wrapper. Deliberately NOT
-  // display:none (can drop layout/scroll state on some engines) and NOT
-  // will-change (a prior perf attempt using will-change on this same overview
-  // caused permanent blur by pinning a low-res compositor layer — see the
-  // world-transform comment near applyViewToDom). "placeholder" and
-  // "evicted" tiers have no mounted browsing context, so they render the
-  // chrome-only placeholder below regardless of this flag.
-  const { shouldMount: shouldMountContent, isHidden: isCulled } =
+  // Overview viewport culling (PF22): mounting only. Unmounting a culled screen
+  // would lose its iframe's scroll/form/Alpine state, so it stays mounted and
+  // paint-suppression.ts decides paint against the live camera instead.
+  const { shouldMount: shouldMountContent } =
     getScreenContentCullState(cullTier);
   const [directlyHovered, setDirectlyHovered] = useState(false);
   const frameDirectlyHovered =
@@ -9786,16 +9854,6 @@ const Screen = memo(function Screen({
           )}
           style={{
             pointerEvents: screenContentInteractive ? "auto" : "none",
-            // Tier B (PF22): keep the mounted iframe/DesignCanvas alive (see
-            // the isCulled comment above) but skip its paint/layout cost.
-            // visibility:hidden (not display:none) keeps the box in the
-            // layout/measurement tree; contentVisibility:"hidden" skips
-            // rendering its subtree entirely until it's shown again. Neither
-            // property touches will-change/compositor layers, so this can't
-            // reproduce the permanent-blur regression a prior will-change
-            // attempt on this same surface caused.
-            visibility: isCulled ? "hidden" : undefined,
-            contentVisibility: isCulled ? "hidden" : undefined,
           }}
         >
           {!shouldMountContent ? (
@@ -10167,7 +10225,7 @@ function BreakpointPreviewRow({
   // draft value of its width input.
   const [menuOpenForWidth, setMenuOpenForWidth] = useState<number | null>(null);
   const [widthDraft, setWidthDraft] = useState("");
-  const { shouldMount: shouldMountContent, isHidden: isCulled } =
+  const { shouldMount: shouldMountContent } =
     getScreenContentCullState(cullTier);
 
   return (
@@ -10476,10 +10534,6 @@ function BreakpointPreviewRow({
                 data-screen-content
                 data-cull-tier={cullTier}
                 className="relative block h-full w-full overflow-hidden rounded-[inherit] bg-white ring-1 ring-inset ring-border"
-                style={{
-                  visibility: isCulled ? "hidden" : undefined,
-                  contentVisibility: isCulled ? "hidden" : undefined,
-                }}
               >
                 {!shouldMountContent ? (
                   <div

package/corpus/templates/design/app/components/design/multi-screen/overview-layout.ts

@@ -96,9 +96,13 @@ export function getBoardSurfaceLayerStyle(args: {
  */
 export function shouldRenderBoardSurfaceStaticPreview(args: {
   zoom: number;
+  hasSurfaceContent: boolean;
   viewportGeometry?: FrameGeometry | null;
   renderGeometry: FrameGeometry;
 }) {
+  // The replica is opaque. Backing a layer that is not rendering just slabs the
+  // board in its own colour, which reads as a themed background gone wrong.
+  if (!args.hasSurfaceContent) return false;
   if (args.viewportGeometry) {
     return (
       args.viewportGeometry.width > args.renderGeometry.width ||

package/corpus/templates/design/app/components/design/multi-screen/paint-suppression.ts

@@ -0,0 +1,85 @@
+import {
+  getScreenContentCullState,
+  isFrameWithinOverscannedViewport,
+  type OverscannedViewportBounds,
+  type ScreenCullTier,
+} from "./culling";
+import type { FrameGeometry } from "./types";
+
+// Zoom scales the world viewport rather than translating it, so no overscan
+// covers a gesture's lag. React must never also write visibility here: its style
+// diff would stop re-applying a value this owner has since cleared.
+
+/** Lets a freshly mounted wrapper still be written while an unchanged one is
+ *  skipped. */
+const SUPPRESSED_MARKER_ATTRIBUTE = "screenPaintSuppressed";
+
+export interface ScreenPaintCandidate {
+  id: string;
+  geometry: FrameGeometry;
+  tier: ScreenCullTier;
+}
+
+export interface ScreenPaintTarget {
+  element: HTMLElement;
+  screenId: string;
+}
+
+/** Every content wrapper belonging to a screen, including its breakpoint
+ *  previews — paint is decided per screen, so the whole shell moves together. */
+export function collectScreenPaintTargets(
+  surface: HTMLElement | null,
+): ScreenPaintTarget[] {
+  if (!surface) return [];
+  const targets: ScreenPaintTarget[] = [];
+  surface
+    .querySelectorAll<HTMLElement>("[data-screen-content]")
+    .forEach((element) => {
+      const screenId = element.closest<HTMLElement>("[data-screen-shell]")
+        ?.dataset.frameId;
+      if (screenId) targets.push({ element, screenId });
+    });
+  return targets;
+}
+
+/** Screens whose paint the browser may skip for the camera passed in. A
+ *  `liveViewport` of `null` (surface not measured yet) suppresses nothing. */
+export function resolveSuppressedScreenIds(
+  candidates: readonly ScreenPaintCandidate[],
+  liveViewport: OverscannedViewportBounds | null,
+): Set<string> {
+  const suppressed = new Set<string>();
+  if (!liveViewport) return suppressed;
+  for (const candidate of candidates) {
+    if (!getScreenContentCullState(candidate.tier).isHidden) continue;
+    if (isFrameWithinOverscannedViewport(candidate.geometry, liveViewport)) {
+      continue;
+    }
+    suppressed.add(candidate.id);
+  }
+  return suppressed;
+}
+
+export function applyScreenPaintSuppression(
+  targets: readonly ScreenPaintTarget[],
+  suppressedScreenIds: ReadonlySet<string>,
+  options?: { relaxOnly?: boolean },
+): void {
+  for (const { element, screenId } of targets) {
+    const suppress = suppressedScreenIds.has(screenId);
+    const applied = element.dataset[SUPPRESSED_MARKER_ATTRIBUTE] === "true";
+    if (applied === suppress) continue;
+    // Mid-gesture, only relax: hiding a screen the camera is still crossing
+    // guarantees an unpainted frame when it returns.
+    if (options?.relaxOnly && suppress) continue;
+    if (suppress) {
+      // Never content-visibility: it discards the subtree's rendering state, so
+      // un-hiding blanks the iframe for a frame.
+      element.style.setProperty("visibility", "hidden");
+      element.dataset[SUPPRESSED_MARKER_ATTRIBUTE] = "true";
+    } else {
+      element.style.removeProperty("visibility");
+      delete element.dataset[SUPPRESSED_MARKER_ATTRIBUTE];
+    }
+  }
+}

package/corpus/templates/design/changelog/2026-08-03-zoom-screen-blink.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-03
+---
+
+Screens no longer blink out and back in while zooming a multi-screen canvas.