@jbrowse/app-core 4.3.0 → 5.0.0-beta.1

package/esm/ui/App/ViewMenu.js

@@ -11,106 +11,101 @@ import MenuIcon from '@mui/icons-material/Menu';
 import OpenInNewIcon from '@mui/icons-material/OpenInNew';
 import VerticalSplitIcon from '@mui/icons-material/VerticalSplit';
 import { observer } from 'mobx-react';
-import { useDockview } from "./DockviewContext.js";
-import { renameIds } from "./copyView.js";
-import { isSessionWithDockviewLayout } from "../../DockviewLayout/index.js";
-function getPanelViewCount(session, viewId) {
-    if (!isSessionWithDockviewLayout(session)) {
-        return 0;
-    }
-    for (const viewIds of session.panelViewAssignments.values()) {
-        if (viewIds.includes(viewId)) {
-            return viewIds.length;
-        }
-    }
-    return 0;
-}
-const ViewMenu = observer(function ViewMenu({ model, IconProps, }) {
+import { renameIds } from './copyView.js';
+// takes the icon's class, not an SvgIconProps object: the object was built
+// inline by ViewHeader and so was new on each of its renders, which defeated
+// mobx-react's memo for this whole menu (a Tooltip and an IconButton) every
+// time anything re-rendered the header
+const ViewMenu = observer(function ViewMenu({ model, className, }) {
     const session = getSession(model);
-    const { moveViewToNewTab, moveViewToSplitRight } = useDockview();
-    const usePanel = session.useWorkspaces && isSessionWithDockviewLayout(session);
-    const viewCount = usePanel
-        ? getPanelViewCount(session, model.id)
-        : session.views.length;
-    const moveView = (panelFn, sessionFn) => {
-        if (usePanel) {
-            panelFn(model.id);
+    const moves = {
+        top: session.moveViewToTop,
+        up: session.moveViewUp,
+        down: session.moveViewDown,
+        bottom: session.moveViewToBottom,
+    };
+    // Give this view a home of its own: its own tab beside the rest, or its own
+    // split to their right. One path, whether or not the workspace is already up
+    // — the layout is session state either way, so there is nothing to defer and
+    // no second implementation for "the panels do not exist yet". That fork is
+    // the reason `init` existed.
+    const moveViewOut = (direction) => {
+        const allViewIds = session.views.map(v => v.id);
+        if (direction === 'tabs') {
+            session.moveViewToNewTab(model.id, allViewIds);
         }
         else {
-            sessionFn(model.id);
+            session.moveViewToSplitRight(model.id, allViewIds);
         }
+        session.setUseWorkspaces(true);
     };
-    return (_jsx(CascadingMenuButton, { "data-testid": "view_menu_icon", menuItems: () => [
-            {
-                label: 'View options',
-                type: 'subMenu',
-                subMenu: [
-                    {
-                        label: 'Copy view',
-                        icon: ContentCopyIcon,
-                        onClick: () => {
-                            session.addView(model.type, renameIds(structuredClone(getSnapshot(model))));
-                        },
-                    },
-                    {
-                        label: 'Move to new tab',
-                        icon: OpenInNewIcon,
-                        onClick: () => {
-                            moveViewToNewTab(model.id);
-                            session.setUseWorkspaces(true);
-                        },
-                    },
-                    {
-                        label: 'Move to split view (right side of screen)',
-                        icon: VerticalSplitIcon,
-                        onClick: () => {
-                            moveViewToSplitRight(model.id);
-                            session.setUseWorkspaces(true);
-                        },
-                    },
-                    ...(viewCount > 2
-                        ? [
-                            {
-                                label: 'Move view to top',
-                                icon: KeyboardDoubleArrowUpIcon,
-                                onClick: () => {
-                                    moveView(session.moveViewToTopInPanel, session.moveViewToTop);
-                                },
+    return (_jsx(CascadingMenuButton, { "data-testid": "view_menu_icon", tooltip: "View menu", menuItems: () => {
+            // The views this move is relative to: in a workspace, the ones sharing
+            // this view's panel; in the classic stack, all of them. `session.views`
+            // is the order either way, so the mode decides the SCOPE of a move and
+            // nothing else. There is one implementation of "move a view" again.
+            //
+            // Resolved here rather than during render. It scans every panel's
+            // assignment list and copies one of them, and reading those lists in
+            // render would also subscribe this menu to them, so a view moving
+            // between panels anywhere re-rendered every view's menu. None of it is
+            // needed until the menu opens.
+            const scopeIds = session.effectiveUseWorkspaces
+                ? session.tabContainingView(model.id)?.tab.viewIds.slice()
+                : undefined;
+            const viewCount = scopeIds?.length ?? session.views.length;
+            return [
+                {
+                    label: 'View options',
+                    type: 'subMenu',
+                    subMenu: [
+                        {
+                            label: 'Copy view',
+                            icon: ContentCopyIcon,
+                            onClick: () => {
+                                session.addView(model.type, renameIds(structuredClone(getSnapshot(model))));
                             },
-                        ]
-                        : []),
-                    ...(viewCount > 1
-                        ? [
-                            {
-                                label: 'Move view up',
-                                icon: KeyboardArrowUpIcon,
-                                onClick: () => {
-                                    moveView(session.moveViewUpInPanel, session.moveViewUp);
-                                },
+                        },
+                        {
+                            label: 'Move to new tab',
+                            icon: OpenInNewIcon,
+                            onClick: () => {
+                                moveViewOut('tabs');
                             },
-                            {
-                                label: 'Move view down',
-                                icon: KeyboardArrowDownIcon,
-                                onClick: () => {
-                                    moveView(session.moveViewDownInPanel, session.moveViewDown);
-                                },
+                        },
+                        {
+                            label: 'Move to split view (right side of screen)',
+                            icon: VerticalSplitIcon,
+                            onClick: () => {
+                                moveViewOut('horizontal');
                             },
-                        ]
-                        : []),
-                    ...(viewCount > 2
-                        ? [
-                            {
-                                label: 'Move view to bottom',
-                                icon: KeyboardDoubleArrowDownIcon,
-                                onClick: () => {
-                                    moveView(session.moveViewToBottomInPanel, session.moveViewToBottom);
+                        },
+                        // 'top'/'bottom' only mean something with a view above *and* below
+                        ...[
+                            ['top', 'Move view to top', KeyboardDoubleArrowUpIcon, 2],
+                            ['up', 'Move view up', KeyboardArrowUpIcon, 1],
+                            ['down', 'Move view down', KeyboardArrowDownIcon, 1],
+                            [
+                                'bottom',
+                                'Move view to bottom',
+                                KeyboardDoubleArrowDownIcon,
+                                2,
+                            ],
+                        ].flatMap(([direction, label, icon, minViews]) => viewCount > minViews
+                            ? [
+                                {
+                                    label,
+                                    icon,
+                                    onClick: () => {
+                                        moves[direction](model.id, scopeIds);
+                                    },
                                 },
-                            },
-                        ]
-                        : []),
-                ],
-            },
-            ...model.menuItems(),
-        ], children: _jsx(MenuIcon, { ...IconProps, fontSize: "small" }) }));
+                            ]
+                            : []),
+                    ],
+                },
+                ...model.menuItems(),
+            ];
+        }, children: _jsx(MenuIcon, { className: className, fontSize: "small" }) }));
 });
 export default ViewMenu;

package/esm/ui/App/ViewStack.d.ts

@@ -0,0 +1,7 @@
+import type { AbstractViewModel, SessionWithFocusedViewAndDrawerWidgets } from '@jbrowse/core/util';
+declare const ViewStack: ({ views, session, className, }: {
+    views: AbstractViewModel[];
+    session: SessionWithFocusedViewAndDrawerWidgets;
+    className?: string;
+}) => import("react").JSX.Element;
+export default ViewStack;

package/esm/ui/App/ViewStack.js

@@ -0,0 +1,42 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { SCROLL_PORT_HEIGHT_VAR, useScrollPortOverflow, } from '@jbrowse/core/util/hooks';
+import { makeStyles } from '@jbrowse/core/util/tss-react';
+import { observer } from 'mobx-react';
+import ViewContainer from './ViewContainer.js';
+// What the trailing space is *for*, which is what sets it: `ViewHeader` brings a
+// newly-added view in with `scrollIntoView({ block: 'center' })`, and centering
+// the last view needs half a port of room below it. Half the port is therefore
+// the amount that makes that gesture reach, and any more is room to scroll the
+// content off its own surface.
+//
+// Capped, because half a port stops being a courtesy on a tall screen. 300px is
+// the cap the classic stack has always had and it stays the answer there — a
+// full window is comfortably past twice it. What the cap was hiding is the
+// workspace panel, where a 2x2 grid's cell can be shorter than 600px and a flat
+// 300px let a view be dragged nearly clear of its own cell.
+const MAX_OVERSCROLL = 300;
+const useStyles = makeStyles()({
+    // trailing space so the last view can scroll up past the bottom of a
+    // container that would otherwise clip its lower edge.
+    //
+    // Rendered only once the views themselves overflow, and that is what makes
+    // the port's scrollbar honest: kept unconditionally, this alone overflowed
+    // the port, so every session — a single short view included — scrolled into
+    // nothing and drew a scrollbar saying so. It is outside the measured element
+    // for the same reason (see `useScrollPortOverflow`).
+    spacer: {
+        height: `min(${MAX_OVERSCROLL}px, calc(var(${SCROLL_PORT_HEIGHT_VAR}, 100vh) / 2))`,
+    },
+});
+const ViewStack = observer(function ViewStack({ views, session, className, }) {
+    const { classes } = useStyles();
+    const viewsRef = useRef(null);
+    const scrollable = useScrollPortOverflow(viewsRef);
+    // View ids present at first render: these arrived with the page (session
+    // restore / initial load), so they must not steal scroll when they mount. A
+    // view whose id isn't in this set was added later and auto-scrolls into view.
+    const [initialViewIds] = useState(() => new Set(views.map(v => v.id)));
+    return (_jsxs(_Fragment, { children: [_jsx("div", { ref: viewsRef, className: className, children: views.map(view => (_jsx(ViewContainer, { view: view, session: session, scrollOnMount: !initialViewIds.has(view.id) }, view.id))) }), scrollable ? _jsx("div", { className: classes.spacer }) : null] }));
+});
+export default ViewStack;

package/esm/ui/App/ViewWrapper.d.ts

@@ -1,6 +1,20 @@
 import type { AbstractViewModel, SessionWithFocusedViewAndDrawerWidgets } from '@jbrowse/core/util';
+/**
+ * A view's body, and the boundary that keeps a view that throws from being an
+ * application-wide failure.
+ *
+ * Without it the next boundary up is the product's own — jbrowse-web's is in
+ * `Loader.tsx` and its fallback is `FatalErrorDialog`, so one bad view replaced
+ * every other view the user had open. The reachable case is not hypothetical: a
+ * display's reads walk to `getContainingView` and throw when the walk finds no
+ * view, which is what ADR-069 is about.
+ *
+ * No reset keys: a view body unmounts on its own when the view is minimized or
+ * scrolls out of the mount band, so remounting is already how a stale banner
+ * clears. What the fallback adds is the deliberate ways out — retry, and close.
+ */
 declare const ViewWrapper: ({ view, session, }: {
     view: AbstractViewModel;
     session: SessionWithFocusedViewAndDrawerWidgets;
-}) => import("react/jsx-runtime").JSX.Element | null;
+}) => import("react").JSX.Element;
 export default ViewWrapper;

package/esm/ui/App/ViewWrapper.js

@@ -1,18 +1,34 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Suspense } from 'react';
+import { ErrorBoundary } from '@jbrowse/core/ui/ErrorBoundary';
 import LoadingEllipses from '@jbrowse/core/ui/LoadingEllipses';
 import { getEnv } from '@jbrowse/core/util';
 import { observer } from 'mobx-react';
-const ViewWrapper = observer(function ViewWrapper({ view, session, }) {
+import ViewErrorFallback from './ViewErrorFallback.js';
+// Separate from the boundary below on purpose: `getViewType` throws when no
+// plugin registered the type, and a lookup done in the boundary's own render is
+// a lookup the boundary cannot catch. This is the one thing in a view's render
+// path that fails without any of the view's own code running.
+const ViewComponent = observer(function ViewComponent({ view, session, }) {
     const { pluginManager } = getEnv(session);
-    const viewType = pluginManager.getViewType(view.type);
-    if (!viewType) {
-        throw new Error(`unknown view type ${view.type}`);
-    }
-    const { ReactComponent } = viewType;
-    if (view.minimized) {
-        return null;
-    }
-    return (_jsx(Suspense, { fallback: _jsx(LoadingEllipses, { variant: "h6" }), children: _jsx(ReactComponent, { model: view, session: session }) }));
+    const { ReactComponent } = pluginManager.getViewType(view.type);
+    return (_jsx(Suspense, { fallback: _jsx(LoadingEllipses, { variant: "h6", "data-view-component-pending": "true" }), children: _jsx(ReactComponent, { model: view, session: session }) }));
+});
+/**
+ * A view's body, and the boundary that keeps a view that throws from being an
+ * application-wide failure.
+ *
+ * Without it the next boundary up is the product's own — jbrowse-web's is in
+ * `Loader.tsx` and its fallback is `FatalErrorDialog`, so one bad view replaced
+ * every other view the user had open. The reachable case is not hypothetical: a
+ * display's reads walk to `getContainingView` and throw when the walk finds no
+ * view, which is what ADR-069 is about.
+ *
+ * No reset keys: a view body unmounts on its own when the view is minimized or
+ * scrolls out of the mount band, so remounting is already how a stale banner
+ * clears. What the fallback adds is the deliberate ways out — retry, and close.
+ */
+const ViewWrapper = observer(function ViewWrapper({ view, session, }) {
+    return (_jsx(ErrorBoundary, { FallbackComponent: ({ error, resetErrorBoundary }) => (_jsx(ViewErrorFallback, { view: view, session: session, error: error, onRetry: resetErrorBoundary })), children: _jsx(ViewComponent, { view: view, session: session }) }));
 });
 export default ViewWrapper;

package/esm/ui/App/ViewsContainer.d.ts

@@ -1,12 +1,7 @@
-import type { SnackbarMessage } from '@jbrowse/core/ui/SnackbarModel';
-import type { AbstractViewContainer, SessionWithFocusedViewAndDrawerWidgets } from '@jbrowse/core/util';
+import type { AppSession } from './types.ts';
 interface Props {
     HeaderButtons?: React.ReactElement;
-    session: SessionWithFocusedViewAndDrawerWidgets & AbstractViewContainer & {
-        renameCurrentSession: (arg: string) => void;
-        snackbarMessages: SnackbarMessage[];
-        popSnackbarMessage: () => unknown;
-    };
+    session: AppSession;
 }
-declare const ViewsContainer: (props: Props) => import("react/jsx-runtime").JSX.Element;
+declare const ViewsContainer: (props: Props) => import("react").JSX.Element;
 export default ViewsContainer;

package/esm/ui/App/ViewsContainer.js

@@ -2,9 +2,13 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { Suspense, lazy } from 'react';
 import { makeStyles } from '@jbrowse/core/util/tss-react';
 import { observer } from 'mobx-react';
-const ClassicViewsContainer = lazy(() => import("./ClassicViewsContainer.js"));
-const TiledViewsContainer = lazy(() => import("./TiledViewsContainer.js"));
-const ViewLauncher = lazy(() => import("./ViewLauncher.js"));
+import { isSessionWithWorkspaceLayout } from '../../WorkspaceLayout/model.js';
+import { lazyChunk } from './lazyChunk.js';
+const ClassicViewsContainer = lazy(lazyChunk('ClassicViewsContainer', () => import('./ClassicViewsContainer.js')));
+const WorkspaceContainer = lazy(lazyChunk('WorkspaceContainer', () => import('../../WorkspaceLayout/WorkspaceContainer.js').then(m => ({
+    default: m.WorkspaceContainer,
+}))));
+const ViewLauncher = lazy(lazyChunk('ViewLauncher', () => import('./ViewLauncher.js')));
 const useStyles = makeStyles()({
     viewsContainer: {
         gridRow: 'components',
@@ -13,9 +17,8 @@ const useStyles = makeStyles()({
 });
 const ViewsContainer = observer(function ViewsContainer(props) {
     const { session } = props;
-    const { views } = session;
+    const { views, effectiveUseWorkspaces } = session;
     const { classes } = useStyles();
-    const useWorkspaces = 'useWorkspaces' in session ? session.useWorkspaces : true;
-    return (_jsx("div", { className: classes.viewsContainer, children: views.length > 0 ? (_jsx(Suspense, { fallback: null, children: useWorkspaces ? (_jsx(TiledViewsContainer, { session: session })) : (_jsx(ClassicViewsContainer, { session: session })) })) : (_jsx(Suspense, { fallback: null, children: _jsx(ViewLauncher, { ...props }) })) }));
+    return (_jsx("div", { className: classes.viewsContainer, children: _jsx(Suspense, { fallback: null, children: views.length > 0 ? (effectiveUseWorkspaces && isSessionWithWorkspaceLayout(session) ? (_jsx(WorkspaceContainer, { session: session })) : (_jsx(ClassicViewsContainer, { session: session }))) : (_jsx(ViewLauncher, { session: session })) }) }));
 });
 export default ViewsContainer;

package/esm/ui/App/copyView.js

@@ -15,7 +15,7 @@ export function renameIds(obj) {
                     if (!idMap.has(val)) {
                         idMap.set(val, createElementId());
                     }
-                    result[key] = `${val}-${idMap.get(val)}`;
+                    result[key] = idMap.get(val);
                 }
                 else {
                     result[key] = transformIds(val);

package/esm/ui/App/index.d.ts

@@ -1,2 +1,3 @@
-export * from './App.tsx';
+export { App } from './App.tsx';
+export { default as AppReadyMarker } from './AppReadyMarker.tsx';
 export { default as DialogQueue } from './DialogQueue.tsx';

package/esm/ui/App/index.js

@@ -1,2 +1,3 @@
-export * from "./App.js";
-export { default as DialogQueue } from "./DialogQueue.js";
+export { App } from './App.js';
+export { default as AppReadyMarker } from './AppReadyMarker.js';
+export { default as DialogQueue } from './DialogQueue.js';

package/esm/ui/App/lazyChunk.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A dynamic import that survives one bad response for its chunk.
+ *
+ * The retry is not a hopeful second roll: `probeChunk` refetches with
+ * `cache: 'reload'`, which both reports what the server really says and
+ * replaces whatever the HTTP cache was holding, and webpack clears its
+ * `installedChunks` entry on failure — so the second `import()` is a real
+ * request against a repaired cache entry. React.lazy cannot do this itself: it
+ * stores the rejection and rethrows it for the life of the page without ever
+ * calling the factory again, so the recovery has to happen here, before the
+ * promise settles.
+ */
+export declare function lazyChunk<T>(name: string, load: () => Promise<T>): () => Promise<T>;

package/esm/ui/App/lazyChunk.js

@@ -0,0 +1,91 @@
+/**
+ * Wraps a dynamic import so a failed chunk fetch says what actually happened.
+ *
+ * Webpack flattens every network-level failure into the same string —
+ * `Loading chunk X failed.\n(error: <url>)` — where `error` only means the
+ * script element fired `error` rather than `load` (a 404, a refused
+ * connection and a dropped socket are indistinguishable). That string is what
+ * jbrowse-web records via `markCrashedSession`, so it is also all a later boot
+ * can show. The immediate refetch below is the part that discriminates:
+ * webpack clears its `installedChunks` entry on failure, so the asset is
+ * really re-requested, and a 200 here means the asset was always fine and the
+ * one request was not.
+ */
+async function probeChunk(url) {
+    try {
+        const response = await fetch(url, { cache: 'reload' });
+        const body = await response.text();
+        return `refetch: HTTP ${response.status} ${response.statusText}, ${response.headers.get('content-type')}, ${body.length} bytes`;
+    }
+    catch (e) {
+        return `refetch also failed: ${e}`;
+    }
+}
+/**
+ * What the browser recorded for the request that failed — the status it
+ * actually saw and whether any bytes crossed the network. A `transferSize` of
+ * 0 alongside a body size says the response came from the cache rather than
+ * the server, which is the one thing `curl` can never show.
+ */
+function resourceTiming(url) {
+    const entry = performance
+        .getEntriesByName(url)
+        .find(e => e instanceof PerformanceResourceTiming);
+    return entry
+        ? {
+            responseStatus: entry.responseStatus,
+            transferSize: entry.transferSize,
+            encodedBodySize: entry.encodedBodySize,
+            duration: Math.round(entry.duration),
+        }
+        : 'no resource timing entry';
+}
+/**
+ * The two fields webpack hangs off a ChunkLoadError: the URL it asked for, and
+ * whether the script element reported `error` (the request failed), `missing`
+ * (it loaded but registered nothing) or `timeout`.
+ */
+function chunkErrorDetail(error) {
+    return error instanceof Error &&
+        error.name === 'ChunkLoadError' &&
+        'request' in error &&
+        typeof error.request === 'string'
+        ? {
+            url: error.request,
+            type: 'type' in error ? String(error.type) : 'unknown',
+        }
+        : undefined;
+}
+/**
+ * A dynamic import that survives one bad response for its chunk.
+ *
+ * The retry is not a hopeful second roll: `probeChunk` refetches with
+ * `cache: 'reload'`, which both reports what the server really says and
+ * replaces whatever the HTTP cache was holding, and webpack clears its
+ * `installedChunks` entry on failure — so the second `import()` is a real
+ * request against a repaired cache entry. React.lazy cannot do this itself: it
+ * stores the rejection and rethrows it for the life of the page without ever
+ * calling the factory again, so the recovery has to happen here, before the
+ * promise settles.
+ */
+export function lazyChunk(name, load) {
+    return () => load().catch(async (error) => {
+        const detail = chunkErrorDetail(error);
+        if (detail) {
+            console.error(`chunk load failed: ${name}`, JSON.stringify({
+                ...detail,
+                online: navigator.onLine,
+                at: new Date().toISOString(),
+                timing: resourceTiming(detail.url),
+                probe: await probeChunk(detail.url),
+            }, undefined, 2));
+            const retried = await load().catch((retryError) => {
+                console.error(`chunk retry failed: ${name}`, retryError);
+                throw error;
+            });
+            console.error(`chunk retry succeeded: ${name}`);
+            return retried;
+        }
+        throw error;
+    });
+}

package/esm/ui/App/types.d.ts

@@ -1,7 +1,16 @@
-import type { SnackbarMessage } from '@jbrowse/core/ui/SnackbarModel';
-import type { AbstractViewContainer, SessionWithFocusedViewAndDrawerWidgets } from '@jbrowse/core/util';
-export type DockviewSessionType = SessionWithFocusedViewAndDrawerWidgets & AbstractViewContainer & {
+import type { Menu } from '../../menus.ts';
+import type { ErrorDialogState, SnackbarMessage } from '@jbrowse/core/ui/SnackbarModel';
+import type { SessionWithFocusedViewAndDrawerWidgets } from '@jbrowse/core/util';
+export { type Menu } from '../../menus.ts';
+export type WorkspaceSessionType = SessionWithFocusedViewAndDrawerWidgets & {
     renameCurrentSession: (arg: string) => void;
     snackbarMessages: SnackbarMessage[];
     popSnackbarMessage: () => unknown;
+    orderViews: (ids: string[]) => void;
+};
+export type AppSession = WorkspaceSessionType & {
+    menus: () => Menu[];
+    errorDialog: ErrorDialogState | undefined;
+    setErrorDialog: (state: ErrorDialogState | undefined) => void;
+    effectiveUseWorkspaces: boolean;
 };

package/esm/ui/App/types.js

@@ -1 +1 @@
-export {};
+export {} from '../../menus.js';

package/esm/ui/App/useViewVisibility.d.ts

@@ -0,0 +1,34 @@
+/**
+ * View-level lazy mounting. A view only mounts its (GPU-heavy) body when it is
+ * within `rootMargin` of the viewport, and collapses to a height-preserving
+ * spacer once scrolled far away. This bounds the number of simultaneously-live
+ * GPU canvases/contexts — the root cause of the "workspaces freeze" with many
+ * stacked views (one WebGL context per display canvas blows past the browser's
+ * per-page cap; see agent-docs/reference/ARCHITECTURAL_LIMITS.md, "One WebGL2
+ * context per display canvas").
+ *
+ * `root: null` (viewport) is container-agnostic: it reports on-screen-ness the
+ * same way whether the views scroll inside the classic container or a workspace
+ * panel, so neither container needs to know about windowing. It also means
+ * **`rootMargin` has no effect** — an observer clips the target against each
+ * scrolling ancestor before intersecting with the root box that the margin
+ * expands, and both containers are `overflow-y: auto`. So this is a hard
+ * window with no hysteresis: a view is torn down the moment it leaves its
+ * container and rebuilt when it returns, which on a GPU backend costs a fresh
+ * WebGL2 context and a full shader recompile per display.
+ *
+ * That is deliberate as of 2026-08-05, not an oversight. Rooting the observer at
+ * the scroll port restores the band and measures as a wash on scroll cost while
+ * roughly doubling live contexts — and the ceiling is 16 live contexts, so the
+ * cap bites before the rebuild saving pays for itself.
+ * agent-docs/reference/GPU_CONTEXT_BUDGET.md has the numbers and the three
+ * other fixes that were measured and eliminated.
+ *
+ * Starts hidden so a cold load with N crammed views doesn't mount them all at
+ * once; the observer's first callback mounts only what's near the viewport.
+ */
+export declare function useViewVisibility(rootMargin: string): {
+    ref: import("react").RefObject<HTMLDivElement | null>;
+    visible: boolean;
+    measuredHeight: number | undefined;
+};

package/esm/ui/App/useViewVisibility.js

@@ -0,0 +1,87 @@
+import { useEffect, useRef, useState } from 'react';
+// No IntersectionObserver (jsdom/SSR): start (and stay) visible, the
+// pre-lazy-mount behavior, so tests and non-browser environments are unchanged.
+function intersectionObserverAvailable() {
+    return typeof window !== 'undefined' && 'IntersectionObserver' in window;
+}
+/**
+ * View-level lazy mounting. A view only mounts its (GPU-heavy) body when it is
+ * within `rootMargin` of the viewport, and collapses to a height-preserving
+ * spacer once scrolled far away. This bounds the number of simultaneously-live
+ * GPU canvases/contexts — the root cause of the "workspaces freeze" with many
+ * stacked views (one WebGL context per display canvas blows past the browser's
+ * per-page cap; see agent-docs/reference/ARCHITECTURAL_LIMITS.md, "One WebGL2
+ * context per display canvas").
+ *
+ * `root: null` (viewport) is container-agnostic: it reports on-screen-ness the
+ * same way whether the views scroll inside the classic container or a workspace
+ * panel, so neither container needs to know about windowing. It also means
+ * **`rootMargin` has no effect** — an observer clips the target against each
+ * scrolling ancestor before intersecting with the root box that the margin
+ * expands, and both containers are `overflow-y: auto`. So this is a hard
+ * window with no hysteresis: a view is torn down the moment it leaves its
+ * container and rebuilt when it returns, which on a GPU backend costs a fresh
+ * WebGL2 context and a full shader recompile per display.
+ *
+ * That is deliberate as of 2026-08-05, not an oversight. Rooting the observer at
+ * the scroll port restores the band and measures as a wash on scroll cost while
+ * roughly doubling live contexts — and the ceiling is 16 live contexts, so the
+ * cap bites before the rebuild saving pays for itself.
+ * agent-docs/reference/GPU_CONTEXT_BUDGET.md has the numbers and the three
+ * other fixes that were measured and eliminated.
+ *
+ * Starts hidden so a cold load with N crammed views doesn't mount them all at
+ * once; the observer's first callback mounts only what's near the viewport.
+ */
+export function useViewVisibility(rootMargin) {
+    const ref = useRef(null);
+    const [state, setState] = useState(() => ({
+        visible: !intersectionObserverAvailable(),
+    }));
+    // Toggle `visible` as the body scrolls in/out of the viewport (root: null),
+    // and record the height it had on the way out.
+    //
+    // The height comes off the entry the observer already handed us. At the
+    // moment the body stops intersecting it is still mounted at full height (the
+    // collapse is what this callback is about to cause), so the entry's rect is
+    // exactly what a ResizeObserver would have reported. Keeping one
+    // meant a second observer per view whose every fire re-rendered the whole
+    // view chrome, and a view's height moves constantly: every track added,
+    // resized, or grown by its own data.
+    useEffect(() => {
+        const node = ref.current;
+        if (node && intersectionObserverAvailable()) {
+            const io = new IntersectionObserver(entries => {
+                const entry = entries.at(-1);
+                if (entry) {
+                    const { isIntersecting } = entry;
+                    setState(prev => {
+                        if (prev.visible === isIntersecting) {
+                            return prev;
+                        }
+                        return {
+                            visible: isIntersecting,
+                            // a minimized view measures 0 here (it renders no body at
+                            // all), which must not become its remembered height
+                            height: isIntersecting
+                                ? prev.height
+                                : entry.boundingClientRect.height || prev.height,
+                        };
+                    });
+                }
+            }, { rootMargin });
+            io.observe(node);
+            return () => {
+                io.disconnect();
+            };
+        }
+        return undefined;
+    }, [rootMargin]);
+    // `measuredHeight` is undefined until the body has been seen at least once.
+    // The caller supplies the estimate, and supplies it lazily. See ViewContainer
+    return {
+        ref,
+        visible: state.visible,
+        measuredHeight: state.height,
+    };
+}