From ee04add0bc37885f3105cd2891df774b928edb82 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 6 Aug 2026 08:18:51 +0000
Subject: [PATCH 1/2] Keep views mounted instead of animating the switch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Switching views crossfaded the outgoing view out, but the applet's scoped
<style> is unmounted with its component — so the view spent its exit
unstyled. Rather than time the styles against the animation, views now stay
mounted: ViewManager keeps the active view visible and recently-visited ones
parked offscreen behind React's <Activity>, so switching is instant and a
view loads once.

- First open shows a centered splash (delayed, so a fast load never flashes
  it); every later switch is immediate and keeps the view's state.
- Parked views keep their DOM and their styles; the style tag is acquired
  above the Activity boundary, which unmounts its children's effects.
- Residency policy (retention window, LRU cap, deleted-view pruning) is pure
  and tested in view-residency.ts; the workspace unmount disposes everything.
- A rebuild swaps the view in place, keeping the previous build on screen
  until the new one is ready, so agent edits no longer flash a spinner.

AppletMount loses `asChild` (only the view path used it) and shares the
`data-applet` scope helper with the view slot.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PaXfVTPUsTUpLkFhjFNU3y
---
 client/features/applets/AppletMount.tsx       |  31 +--
 client/features/applets/applet-cache.ts       |   7 +
 client/features/applets/useApplet.ts          |   2 +-
 client/features/views/ViewManager.tsx         | 187 ++++++++++++++++++
 client/features/views/view-residency.test.ts  | 176 +++++++++++++++++
 client/features/views/view-residency.ts       |  77 ++++++++
 client/features/workspace/WorkspaceScreen.tsx |  80 ++------
 docs/moi-views.md                             |  30 ++-
 8 files changed, 493 insertions(+), 97 deletions(-)
 create mode 100644 client/features/views/ViewManager.tsx
 create mode 100644 client/features/views/view-residency.test.ts
 create mode 100644 client/features/views/view-residency.ts

diff --git a/client/features/applets/AppletMount.tsx b/client/features/applets/AppletMount.tsx
index d0cff83f..83c78e20 100644
--- a/client/features/applets/AppletMount.tsx
+++ b/client/features/applets/AppletMount.tsx
@@ -1,43 +1,30 @@
-import { type ReactElement, type ReactNode, cloneElement, isValidElement } from 'react'
+import { type ReactNode } from 'react'
 
 import { useWorkspaceId } from '@/client/features/workspace/WorkspaceContext'
 
-import { type AppletSegment, appletStyleKey } from './applet-cache'
+import { type AppletSegment, appletScope, appletStyleKey } from './applet-cache'
 import { useAppletStyle } from './applet-styles'
 
 type AppletMountProps = {
   segment: AppletSegment
   name: string
   version: number
-  // Merge the scope attribute into the single child element instead of
-  // rendering a wrapper — use when the caller already has a filled container
-  // (e.g. the shells' motion.div), so no extra node enters the DOM. The child
-  // must forward unknown props to its DOM element.
-  asChild?: boolean
   children: ReactNode
 }
 
 // The style scope for one mounted applet: puts the `data-applet` attribute the
 // bundle's scoped CSS selectors key off (see server/bundler/applet-css.ts) on a
-// container, and keeps the applet's <style> tag mounted exactly as long as the
-// applet is — unmounting removes the styles from the page. Without `asChild`
-// it renders its own wrapper div filling the parent box (the widget path —
-// merging onto the shell's motion.div interferes with AnimatePresence there);
-// with `asChild` it merges onto the child element instead (the view path).
-export function AppletMount({ segment, name, version, asChild, children }: AppletMountProps) {
+// wrapper filling the parent box, and keeps the applet's <style> tag mounted
+// exactly as long as the applet is — unmounting removes the styles from the
+// page. This is the widget path. Views don't use it: ViewManager parks a view's
+// DOM offscreen instead of unmounting it, so it holds the styles itself, above
+// the boundary that hides the view.
+export function AppletMount({ segment, name, version, children }: AppletMountProps) {
   const workspaceId = useWorkspaceId()
   useAppletStyle(appletStyleKey(segment, workspaceId, name), version)
 
-  const kind = segment === 'widgets' ? 'widget' : 'view'
-  const scope = `${kind}:${name}`
-
-  if (asChild && isValidElement(children)) {
-    return cloneElement(children as ReactElement<{ 'data-applet'?: string }>, {
-      'data-applet': scope
-    })
-  }
   return (
-    <div data-applet={scope} className="size-full">
+    <div data-applet={appletScope(segment, name)} className="size-full">
       {children}
     </div>
   )
diff --git a/client/features/applets/applet-cache.ts b/client/features/applets/applet-cache.ts
index 6a329284..812526da 100644
--- a/client/features/applets/applet-cache.ts
+++ b/client/features/applets/applet-cache.ts
@@ -54,6 +54,13 @@ export function appletStyleKey(segment: AppletSegment, workspaceId: string, name
   return `/api/workspaces/${workspaceId}/${segment}/${name}`
 }
 
+// The `data-applet` value the bundle's scoped CSS selectors key off (see
+// server/bundler/applet-css.ts). It goes on the container wrapping a mounted
+// applet — AppletMount for widgets, the view slot for views.
+export function appletScope(segment: AppletSegment, name: string): string {
+  return `${segment === 'widgets' ? 'widget' : 'view'}:${name}`
+}
+
 export function getCachedApplet(key: string): Promise<unknown> | undefined {
   return moduleCache.get(key)
 }
diff --git a/client/features/applets/useApplet.ts b/client/features/applets/useApplet.ts
index 22da7e80..514addec 100644
--- a/client/features/applets/useApplet.ts
+++ b/client/features/applets/useApplet.ts
@@ -24,7 +24,7 @@ export type AppletComponentProps = {
   params?: Record<string, unknown>
 }
 
-type AppletState =
+export type AppletState =
   | { status: 'loading'; version: number }
   | { status: 'ready'; Component: ComponentType<AppletComponentProps>; version: number }
   | { status: 'error'; error: string; version: number }
diff --git a/client/features/views/ViewManager.tsx b/client/features/views/ViewManager.tsx
new file mode 100644
index 00000000..f7d0fece
--- /dev/null
+++ b/client/features/views/ViewManager.tsx
@@ -0,0 +1,187 @@
+// The workspace's view surface: every view the user has open lives here, and
+// switching tabs picks one of them instead of tearing the old one down and
+// building the new one up.
+//
+// Why not a transition: a view is an agent-authored bundle with its own styles
+// and its own state. Animating the swap means keeping the outgoing DOM alive
+// past the moment React drops the applet's <style> tag, so the view spends its
+// exit unstyled. Keeping views mounted removes the problem instead of timing
+// around it — the switch is instant, and a view only ever loads once.
+import { Activity, type ComponentType, useCallback, useEffect, useRef, useState } from 'react'
+
+import { Spinner } from '@/client/components/ui/spinner'
+import { appletScope, appletStyleKey } from '@/client/features/applets/applet-cache'
+import { useAppletStyle } from '@/client/features/applets/applet-styles'
+import {
+  type AppletComponentProps,
+  type AppletState,
+  useView
+} from '@/client/features/applets/useApplet'
+import { WidgetErrorBoundary } from '@/client/features/applets/WidgetErrorBoundary'
+import { useWorkspaceId } from '@/client/features/workspace/WorkspaceContext'
+import { cn } from '@/client/lib/cn'
+import type { ViewInfo } from '@/lib/types'
+
+import {
+  nextEvictionDelay,
+  reconcileResidents,
+  type ResidentView,
+  sameResidents
+} from './view-residency'
+
+type ViewManagerProps = {
+  views: ViewInfo[]
+  // The view the active tab names, or null when another tab is on screen. The
+  // manager stays mounted either way — that is what makes coming back from the
+  // agent or widgets tab instant too.
+  activeViewId: string | null
+  // The active view's addressable state, read from navigation state (focusTab /
+  // `moi tab focus`). `{}` on a fresh mount, a new browser tab, or a plain
+  // tab-bar click — a view must render sensibly with that.
+  params: Record<string, unknown>
+}
+
+export function ViewManager({ views, activeViewId, params }: ViewManagerProps) {
+  const residents = useResidentViews(activeViewId, views)
+  // Render in workspace order, not residency order: the policy ranks views by
+  // recency, and reordering the children would make React move live DOM around
+  // on every switch. The slots are stacked absolutely with one visible, so
+  // their order on the page carries no meaning.
+  const resident = new Set(residents.map(entry => entry.id))
+
+  return (
+    // Hidden rather than unmounted when no view tab is on screen: the parked
+    // views keep their DOM, and `display: none` keeps this layer out of the
+    // layout and out of the way of pointer events on the tab that IS on screen.
+    <div className={cn('relative min-h-0 flex-1 overflow-hidden', !activeViewId && 'hidden')}>
+      {views
+        .filter(view => resident.has(view.id))
+        .map(view => (
+          <ViewSlot key={view.id} view={view} active={view.id === activeViewId} params={params} />
+        ))}
+    </div>
+  )
+}
+
+// The views mounted right now: the active one, plus the recently-visited ones
+// parked offscreen. The policy (and its timing) lives in view-residency.ts.
+function useResidentViews(activeId: string | null, views: ViewInfo[]): ResidentView[] {
+  const [residents, setResidents] = useState<ResidentView[]>([])
+  // A workspace refetch hands us a new array on every event; residency only
+  // cares whether a view appeared or disappeared. So the effect keys off the id
+  // set, and the reconcile reads the current list through the ref.
+  const viewsRef = useRef(views)
+  viewsRef.current = views
+  const availableIds = views.map(view => view.id).join('\n')
+
+  const reconcile = useCallback(() => {
+    setResidents(current => {
+      const next = reconcileResidents(current, {
+        activeId,
+        available: new Set(viewsRef.current.map(view => view.id)),
+        now: Date.now()
+      })
+      return sameResidents(current, next) ? current : next
+    })
+  }, [activeId])
+
+  // Promote the view the user switched to, and release the one it replaced.
+  useEffect(() => {
+    reconcile()
+  }, [availableIds, reconcile])
+
+  // Then evict on the retention deadline — one timer, for the nearest one.
+  useEffect(() => {
+    const delay = nextEvictionDelay(residents, Date.now())
+    if (delay === null) return
+    const timer = setTimeout(reconcile, delay)
+    return () => clearTimeout(timer)
+  }, [reconcile, residents])
+
+  return residents
+}
+
+type ViewSlotProps = {
+  view: ViewInfo
+  active: boolean
+  params: Record<string, unknown>
+}
+
+// One resident view. The bundle it holds is loaded and kept fresh for as long
+// as the slot lives — a view rebuilt while parked picks the new build up in
+// place, so it is current the moment the user comes back to it.
+function ViewSlot({ view, active, params }: ViewSlotProps) {
+  const workspaceId = useWorkspaceId()
+  const bundle = useView(view.id)
+  const loaded = useLoadedBundle(bundle)
+  // A parked view keeps rendering with the params it was last shown with: the
+  // active view's `focusTab` state is not its to render.
+  const [shownParams, setShownParams] = useState(params)
+  if (active && shownParams !== params) setShownParams(params)
+
+  // The applet's <style> is acquired HERE, outside the Activity below. Hiding
+  // an Activity unmounts its children's effects, which would strip the styles
+  // off the page while the DOM they style is still parked — the exact flash
+  // this component exists to remove. The tag drops when the slot is evicted.
+  useAppletStyle(appletStyleKey('views', workspaceId, view.id), loaded?.version ?? bundle.version)
+
+  const failed = bundle.status === 'error'
+
+  return (
+    <>
+      {active && failed && (
+        <p className="absolute inset-0 p-4 text-xs text-destructive">{bundle.error}</p>
+      )}
+      {active && !failed && !loaded && <ViewSplash />}
+      {loaded && !failed && (
+        <Activity mode={active ? 'visible' : 'hidden'}>
+          {/* React hides this node with `display: none` while the Activity is
+              hidden, so a parked view neither paints nor swallows clicks. */}
+          <div
+            key={loaded.version}
+            data-applet={appletScope('views', view.id)}
+            className="absolute inset-0 overflow-auto"
+          >
+            <WidgetErrorBoundary
+              name={view.id}
+              kind="view"
+              workspaceId={workspaceId}
+              resetKey={loaded.version}
+            >
+              <loaded.Component params={shownParams} />
+            </WidgetErrorBoundary>
+          </div>
+        </Activity>
+      )}
+    </>
+  )
+}
+
+type LoadedView = {
+  Component: ComponentType<AppletComponentProps>
+  version: number
+}
+
+// The last build that actually loaded, held across reloads. A rebuild flips the
+// bundle back to `loading` for as long as the fetch takes, and swapping a live
+// view for a spinner every time the agent edits it is worse than showing the
+// previous build for that moment. The splash is for a view with nothing to show
+// yet — the first time it is opened.
+function useLoadedBundle(bundle: AppletState): LoadedView | null {
+  const [loaded, setLoaded] = useState<LoadedView | null>(null)
+  if (bundle.status === 'ready' && loaded?.version !== bundle.version) {
+    setLoaded({ Component: bundle.Component, version: bundle.version })
+  }
+  return loaded
+}
+
+// A view's one loading moment: the first open, while its bundle is fetched. The
+// delay keeps it off screen entirely for a fast load — the common case, since
+// the module cache outlives eviction and only the network trip is new.
+function ViewSplash() {
+  return (
+    <div className="absolute inset-0 flex animate-in items-center justify-center delay-150 duration-200 fill-mode-both fade-in">
+      <Spinner className="text-muted-foreground" />
+    </div>
+  )
+}
diff --git a/client/features/views/view-residency.test.ts b/client/features/views/view-residency.test.ts
new file mode 100644
index 00000000..c29f2a5f
--- /dev/null
+++ b/client/features/views/view-residency.test.ts
@@ -0,0 +1,176 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  MAX_RESIDENT_VIEWS,
+  nextEvictionDelay,
+  reconcileResidents,
+  type ResidentView,
+  sameResidents,
+  VIEW_RETENTION_MS
+} from '@/client/features/views/view-residency'
+
+const availability = (...ids: string[]) => new Set(ids)
+
+describe('reconcileResidents', () => {
+  test('adds the active view at the front', () => {
+    const residents = reconcileResidents([], {
+      activeId: 'orders',
+      available: availability('orders'),
+      now: 1000
+    })
+
+    expect(residents).toEqual([{ id: 'orders', releasedAt: null }])
+  })
+
+  test('parks the view the active one replaced', () => {
+    const first = reconcileResidents([], {
+      activeId: 'orders',
+      available: availability('orders', 'inbox'),
+      now: 1000
+    })
+    const second = reconcileResidents(first, {
+      activeId: 'inbox',
+      available: availability('orders', 'inbox'),
+      now: 2000
+    })
+
+    expect(second).toEqual([
+      { id: 'inbox', releasedAt: null },
+      { id: 'orders', releasedAt: 2000 }
+    ])
+  })
+
+  test('keeps the release clock running instead of restarting it', () => {
+    const parked: ResidentView[] = [
+      { id: 'inbox', releasedAt: null },
+      { id: 'orders', releasedAt: 2000 }
+    ]
+
+    const residents = reconcileResidents(parked, {
+      activeId: 'inbox',
+      available: availability('orders', 'inbox'),
+      now: 5000
+    })
+
+    expect(residents[1]).toEqual({ id: 'orders', releasedAt: 2000 })
+  })
+
+  test('evicts a parked view once the retention window passes', () => {
+    const parked: ResidentView[] = [
+      { id: 'inbox', releasedAt: null },
+      { id: 'orders', releasedAt: 2000 }
+    ]
+
+    const inside = reconcileResidents(parked, {
+      activeId: 'inbox',
+      available: availability('orders', 'inbox'),
+      now: 2000 + VIEW_RETENTION_MS - 1
+    })
+    const outside = reconcileResidents(parked, {
+      activeId: 'inbox',
+      available: availability('orders', 'inbox'),
+      now: 2000 + VIEW_RETENTION_MS
+    })
+
+    expect(inside.map(resident => resident.id)).toEqual(['inbox', 'orders'])
+    expect(outside.map(resident => resident.id)).toEqual(['inbox'])
+  })
+
+  test('releases every resident when a non-view tab is on screen', () => {
+    const residents = reconcileResidents([{ id: 'orders', releasedAt: null }], {
+      activeId: null,
+      available: availability('orders'),
+      now: 3000
+    })
+
+    expect(residents).toEqual([{ id: 'orders', releasedAt: 3000 }])
+  })
+
+  test('re-promoting a parked view clears its deadline', () => {
+    const residents = reconcileResidents([{ id: 'orders', releasedAt: 3000 }], {
+      activeId: 'orders',
+      available: availability('orders'),
+      now: 4000
+    })
+
+    expect(residents).toEqual([{ id: 'orders', releasedAt: null }])
+  })
+
+  test('drops a view that no longer exists', () => {
+    const residents = reconcileResidents(
+      [
+        { id: 'inbox', releasedAt: null },
+        { id: 'orders', releasedAt: 2000 }
+      ],
+      { activeId: 'inbox', available: availability('inbox'), now: 2500 }
+    )
+
+    expect(residents).toEqual([{ id: 'inbox', releasedAt: null }])
+  })
+
+  test('ignores an active view that does not exist', () => {
+    const residents = reconcileResidents([], {
+      activeId: 'deleted',
+      available: availability('orders'),
+      now: 1000
+    })
+
+    expect(residents).toEqual([])
+  })
+
+  test('caps the resident set, dropping the coldest view first', () => {
+    const parked: ResidentView[] = Array.from({ length: MAX_RESIDENT_VIEWS + 2 }, (_, index) => ({
+      id: `view-${index}`,
+      releasedAt: 1000
+    }))
+
+    const residents = reconcileResidents(parked, {
+      activeId: 'fresh',
+      available: availability('fresh', ...parked.map(resident => resident.id)),
+      now: 1500
+    })
+
+    expect(residents).toHaveLength(MAX_RESIDENT_VIEWS)
+    expect(residents.map(resident => resident.id)).toEqual([
+      'fresh',
+      ...parked.slice(0, MAX_RESIDENT_VIEWS - 1).map(resident => resident.id)
+    ])
+  })
+})
+
+describe('nextEvictionDelay', () => {
+  test('is null while nothing is on the clock', () => {
+    expect(nextEvictionDelay([{ id: 'orders', releasedAt: null }], 1000)).toBeNull()
+  })
+
+  test('reports the nearest deadline', () => {
+    const delay = nextEvictionDelay(
+      [
+        { id: 'inbox', releasedAt: null },
+        { id: 'orders', releasedAt: 2000 },
+        { id: 'reports', releasedAt: 1000 }
+      ],
+      3000
+    )
+
+    expect(delay).toBe(VIEW_RETENTION_MS - 2000)
+  })
+
+  test('never goes negative for an overdue view', () => {
+    expect(nextEvictionDelay([{ id: 'orders', releasedAt: 0 }], VIEW_RETENTION_MS * 2)).toBe(0)
+  })
+})
+
+describe('sameResidents', () => {
+  test('compares ids and deadlines in order', () => {
+    const residents: ResidentView[] = [
+      { id: 'inbox', releasedAt: null },
+      { id: 'orders', releasedAt: 2000 }
+    ]
+
+    expect(sameResidents(residents, [...residents])).toBe(true)
+    expect(sameResidents(residents, [residents[1], residents[0]])).toBe(false)
+    expect(sameResidents(residents, [residents[0]])).toBe(false)
+    expect(sameResidents(residents, [residents[0], { id: 'orders', releasedAt: 2001 }])).toBe(false)
+  })
+})
diff --git a/client/features/views/view-residency.ts b/client/features/views/view-residency.ts
new file mode 100644
index 00000000..d231dc45
--- /dev/null
+++ b/client/features/views/view-residency.ts
@@ -0,0 +1,77 @@
+// Which views the workspace keeps mounted, and for how long.
+//
+// A view is not remounted on every tab switch. The one on screen is visible,
+// recently-visited ones stay mounted but hidden — DOM, component state, and
+// styles intact — so coming back inside the retention window is instant. Past
+// the window the view is disposed and the next visit re-loads it behind the
+// splash. The cap bounds what fast tab-cycling can pin in memory: the least
+// recently visited view is dropped first.
+//
+// The policy is pure so the timing rules stay testable; ViewManager owns the
+// clock and the timers.
+
+export const VIEW_RETENTION_MS = 60_000
+export const MAX_RESIDENT_VIEWS = 4
+
+export type ResidentView = {
+  id: string
+  // When the view stopped being the active one — null while it is active. The
+  // retention deadline is measured from here, and it is set ONCE per departure:
+  // re-running the policy must not restart the clock.
+  releasedAt: number | null
+}
+
+type ReconcileInput = {
+  // The view the active tab names, or null when another tab is on screen —
+  // which releases every resident, so parking on the chat expires them too.
+  activeId: string | null
+  // View ids that still exist. A deleted view is dropped immediately; its
+  // bundle is gone and its parked DOM would only hold dead styles.
+  available: ReadonlySet<string>
+  now: number
+}
+
+// The resident set after promoting the active view and expiring the rest.
+// Ordered most-recently-active first, so the cap drops the coldest view.
+export function reconcileResidents(
+  residents: readonly ResidentView[],
+  { activeId, available, now }: ReconcileInput
+): ResidentView[] {
+  const next: ResidentView[] = []
+  if (activeId !== null && available.has(activeId)) next.push({ id: activeId, releasedAt: null })
+
+  for (const resident of residents) {
+    if (resident.id === activeId || !available.has(resident.id)) continue
+    const releasedAt = resident.releasedAt ?? now
+    if (now - releasedAt >= VIEW_RETENTION_MS) continue
+    if (next.length >= MAX_RESIDENT_VIEWS) break
+    next.push({ id: resident.id, releasedAt })
+  }
+
+  return next
+}
+
+// Milliseconds until the next resident falls out of the retention window, or
+// null when nothing is on the clock (every resident is active). ViewManager
+// arms a single timer on this instead of one timer per view.
+export function nextEvictionDelay(residents: readonly ResidentView[], now: number): number | null {
+  let earliest: number | null = null
+  for (const { releasedAt } of residents) {
+    if (releasedAt === null) continue
+    const deadline = releasedAt + VIEW_RETENTION_MS
+    if (earliest === null || deadline < earliest) earliest = deadline
+  }
+  return earliest === null ? null : Math.max(0, earliest - now)
+}
+
+// Whether a reconcile changed anything — lets the caller keep the previous
+// array identity and skip the re-render (and the timer effect it would rerun).
+export function sameResidents(a: readonly ResidentView[], b: readonly ResidentView[]): boolean {
+  return (
+    a.length === b.length &&
+    a.every((resident, index) => {
+      const other = b[index]
+      return resident.id === other.id && resident.releasedAt === other.releasedAt
+    })
+  )
+}
diff --git a/client/features/workspace/WorkspaceScreen.tsx b/client/features/workspace/WorkspaceScreen.tsx
index 655029df..855f4a29 100644
--- a/client/features/workspace/WorkspaceScreen.tsx
+++ b/client/features/workspace/WorkspaceScreen.tsx
@@ -1,6 +1,6 @@
 import { lazy, Suspense, useEffect, useState } from 'react'
 
-import { AnimatePresence, motion } from 'motion/react'
+import { AnimatePresence } from 'motion/react'
 
 import {
   IconArticle,
@@ -15,9 +15,7 @@ import { IconGhost } from '@/client/components/shared/IconGhost'
 import { ChatPanel } from '@/client/features/chat/ChatPanel'
 import { ChatPopup } from '@/client/features/chat/ChatPopup'
 import { CustomizePanel } from '@/client/features/workspace/CustomizePanel'
-import { AppletMount } from '@/client/features/applets/AppletMount'
 import { useAppletEvent } from '@/client/features/applets/applet-runtime'
-import { WidgetErrorBoundary } from '@/client/features/applets/WidgetErrorBoundary'
 import { Widgets } from '@/client/features/widgets/Widgets'
 import { PanelHeader } from '@/client/components/shared/PanelHeader'
 import { workspaceProviderIcon } from '@/client/features/home/workspace-presentation'
@@ -26,8 +24,8 @@ import { Tooltip, TooltipContent, TooltipTrigger } from '@/client/components/ui/
 import { WorkspaceSettings } from '@/client/features/settings/WorkspaceSettings'
 import { useAppletChatMessage } from '@/client/features/chat/useAppletChatMessage'
 import { useChat } from '@/client/features/chat/useChat'
-import { useView } from '@/client/features/applets/useApplet'
 import { ViewBuilderTab } from '@/client/features/views/ViewBuilderTab'
+import { ViewManager } from '@/client/features/views/ViewManager'
 import { useViewBuilderActions } from '@/client/features/views/useViewBuilderActions'
 import { useFitsSplitLayout } from '@/client/features/workspace/useFitsSplitLayout'
 import { useWorkspaceAvailability } from '@/client/features/workspace/api'
@@ -39,7 +37,6 @@ import {
   isSessionRunning,
   useLive
 } from '@/client/features/chat/chat-store'
-import { useWorkspaceId } from '@/client/features/workspace/WorkspaceContext'
 import { useWorkspaceLayoutCtx } from '@/client/features/workspace/WorkspaceLayoutContext'
 import {
   effectiveOpenTabs,
@@ -100,67 +97,6 @@ function SectionControls({ mode, onToggleMode }: SectionControlsProps) {
   )
 }
 
-type ViewAppProps = {
-  view: ViewInfo
-  // The view's addressable state, read from navigation state (focusTab /
-  // `moi tab focus`). `{}` on a fresh mount, a new browser tab, or a plain
-  // tab-bar click — the view must render sensibly with that.
-  params: Record<string, unknown>
-}
-
-// A view — an agent-defined app — mounted full-area. The bundle owns its own
-// layout + scroll, so we give it a plain filled box and fade it in (mirroring
-// WidgetShell, but full-area instead of a grid cell).
-function ViewApp({ view, params }: ViewAppProps) {
-  const workspaceId = useWorkspaceId()
-  const bundle = useView(view.id)
-
-  return (
-    <div className="relative min-h-0 flex-1 overflow-hidden">
-      <AnimatePresence mode="wait" initial={false}>
-        {bundle.status === 'ready' && (
-          <AppletMount
-            asChild
-            segment="views"
-            name={view.id}
-            version={bundle.version}
-            key={bundle.version}
-          >
-            <motion.div
-              className="absolute inset-0 overflow-auto"
-              initial={{ opacity: 0, filter: 'blur(4px)' }}
-              animate={{ opacity: 1, filter: 'blur(0px)' }}
-              exit={{ opacity: 0, filter: 'blur(4px)' }}
-              transition={{ duration: 0.3, ease: 'easeInOut' }}
-            >
-              <WidgetErrorBoundary
-                name={view.id}
-                kind="view"
-                workspaceId={workspaceId}
-                resetKey={bundle.version}
-              >
-                <bundle.Component params={params} />
-              </WidgetErrorBoundary>
-            </motion.div>
-          </AppletMount>
-        )}
-        {bundle.status === 'error' && (
-          <motion.p
-            key={`err-${bundle.version}`}
-            className="absolute inset-0 p-4 text-xs text-destructive"
-            initial={{ opacity: 0 }}
-            animate={{ opacity: 1 }}
-            exit={{ opacity: 0 }}
-            transition={{ duration: 0.3, ease: 'easeInOut' }}
-          >
-            {bundle.error}
-          </motion.p>
-        )}
-      </AnimatePresence>
-    </div>
-  )
-}
-
 type WorkspaceCustomizeActionProps = {
   active: boolean
   onToggle: () => void
@@ -670,9 +606,17 @@ export function WorkspaceScreen({ widgets, views, builders }: WorkspaceScreenPro
                 }}
                 onDiscard={() => discardBuilder(activeBuilder)}
               />
-            ) : activeView ? (
-              <ViewApp view={activeView} params={appletParams} />
             ) : null}
+
+            {/* Views are not part of the chain above: ViewManager keeps them
+                mounted across tab switches (and collapses to nothing while
+                another tab is on screen), which is what makes a switch back
+                instant. */}
+            <ViewManager
+              views={views}
+              activeViewId={activeView?.id ?? null}
+              params={appletParams}
+            />
           </div>
         )}
 
diff --git a/docs/moi-views.md b/docs/moi-views.md
index 56ae3265..099b10d8 100644
--- a/docs/moi-views.md
+++ b/docs/moi-views.md
@@ -85,9 +85,27 @@ manifest. Only the _active_ view is client state.
 
 ## Client rendering
 
-- Real view list replaces the hardcoded `DEMO_VIEWS`; `WorkspaceTabs` renders a tab
-  per view (in manifest order) with overflow into the "…" menu (existing UI).
-- Selecting a view mounts its bundle full-screen in the body area via the existing
-  dynamic-import path (`useWidget`-style hook, error boundary, fade-in).
-- **Active view is transient** (local state, like fullscreen chat) — not persisted.
-- **Data refetches on mount** for now (no cross-mount caching).
+- `WorkspaceTabs` renders a tab per open view; the tab address lives in the URL and
+  the open set is persisted in `.moi/.workspace.json`.
+- `client/features/views/ViewManager.tsx` owns the view surface: it loads a view's
+  bundle, mounts it full-area behind an error boundary, and holds its scoped
+  `<style>` for as long as the view is mounted.
+
+### Mounting and lifecycle
+
+A view is **not** remounted on every tab visit. The one on screen is visible;
+recently-visited ones stay mounted but hidden behind React's `<Activity>`, so a
+switch back is instant and the view's component state survives it.
+
+- **First open** — the bundle is fetched behind a centered splash, then rendered.
+- **Switching between loaded views** — instant, no transition. There is no
+  enter/exit animation: a view carries its own styles, and animating the swap
+  means painting frames after the styles are gone.
+- **Parked** — hidden with `display: none`. React unmounts the subtree's effects
+  while it is hidden and runs them again on return, so a view's effects behave
+  like a remount even though its state does not. Scroll position is not kept.
+- **Disposed** — after the retention window (`view-residency.ts`), when the view
+  is deleted, or immediately when the workspace closes.
+- A view rebuilt while parked picks the new build up in place. A view rebuilt
+  while on screen keeps showing the previous build until the new one is ready —
+  no splash between edits.

From 283a34b2de0ec47c709a85b780b83decbba3e700 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 6 Aug 2026 09:29:32 +0000
Subject: [PATCH 2/2] Dissolve a rebuilt view in over the build it replaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A view rebuilt while you are looking at it now fades in over the previous
build (200ms, 4px blur) instead of cutting. The outgoing build stays mounted
underneath for the length of the animation, so the incoming one dissolves
over the view rather than over an empty panel — no blank frame. Only that
swap animates: first open and every tab switch stay instant.

Also raise the active view's <style> to the end of <head>. Applet CSS is
scoped per container, but global at-rule names (@keyframes, @property) are
not (server/bundler/applet-css.ts), so with several views mounted at once the
last definition of a shared name wins for all of them. Making that the view
on screen keeps the collision invisible.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PaXfVTPUsTUpLkFhjFNU3y
---
 client/features/applets/applet-styles.ts |  22 +++-
 client/features/views/ViewManager.tsx    | 147 +++++++++++++++++------
 docs/moi-views.md                        |  15 ++-
 3 files changed, 140 insertions(+), 44 deletions(-)

diff --git a/client/features/applets/applet-styles.ts b/client/features/applets/applet-styles.ts
index c86f9c9b..f2bfa265 100644
--- a/client/features/applets/applet-styles.ts
+++ b/client/features/applets/applet-styles.ts
@@ -52,10 +52,30 @@ export function acquireAppletStyle(key: string): () => void {
   }
 }
 
+// Move an applet's <style> to the end of <head>. Everything in an applet sheet
+// is scoped to its `[data-applet]` container and so can't collide — except the
+// names of global at-rules (`@keyframes`, `@property`, `@font-face`), which the
+// scoper leaves alone because they aren't selectors (server/bundler/applet-css.ts).
+// Two applets defining `@keyframes pulse` differently therefore share one
+// document-global name, and the last definition wins for both. Raising the
+// applet the user is looking at makes the winner the one on screen.
+export function raiseAppletStyle(key: string): void {
+  const entry = active.get(key)
+  if (!entry || entry.el === document.head.lastElementChild) return
+  document.head.appendChild(entry.el)
+}
+
 // Keep the applet's <style> mounted for the lifetime of the calling component.
 // `version` re-runs the effect after a rebuild so the tag picks up the fresh
 // registry text. useInsertionEffect runs before layout effects and paint, so
 // the styles are in place before the applet's first frame.
-export function useAppletStyle(key: string, version: number): void {
+//
+// `onTop` marks the applet as the visible one — see `raiseAppletStyle`. Only
+// ever set it on one mounted applet at a time; with several claiming it the
+// winner is whichever effect React happens to run last.
+export function useAppletStyle(key: string, version: number, onTop = false): void {
   useInsertionEffect(() => acquireAppletStyle(key), [key, version])
+  useInsertionEffect(() => {
+    if (onTop) raiseAppletStyle(key)
+  }, [key, onTop, version])
 }
diff --git a/client/features/views/ViewManager.tsx b/client/features/views/ViewManager.tsx
index f7d0fece..98ba6dd1 100644
--- a/client/features/views/ViewManager.tsx
+++ b/client/features/views/ViewManager.tsx
@@ -2,11 +2,17 @@
 // switching tabs picks one of them instead of tearing the old one down and
 // building the new one up.
 //
-// Why not a transition: a view is an agent-authored bundle with its own styles
-// and its own state. Animating the swap means keeping the outgoing DOM alive
-// past the moment React drops the applet's <style> tag, so the view spends its
-// exit unstyled. Keeping views mounted removes the problem instead of timing
-// around it — the switch is instant, and a view only ever loads once.
+// Why no transition between views: a view is an agent-authored bundle with its
+// own styles and its own state. Animating the swap means keeping the outgoing
+// DOM alive past the moment React drops the applet's <style> tag, so the view
+// spends its exit unstyled. Keeping views mounted removes the problem instead
+// of timing around it — the switch is instant, and a view only ever loads once.
+//
+// The one animation left is the rebuild dissolve: when the view you are looking
+// at is rebuilt, the new build fades in over the old one. That is safe here
+// because both builds share the slot's style tag (see ViewSlot), and it is
+// worth the 200ms — it is the only signal that the thing under your cursor just
+// changed underneath you.
 import { Activity, type ComponentType, useCallback, useEffect, useRef, useState } from 'react'
 
 import { Spinner } from '@/client/components/ui/spinner'
@@ -113,7 +119,7 @@ type ViewSlotProps = {
 function ViewSlot({ view, active, params }: ViewSlotProps) {
   const workspaceId = useWorkspaceId()
   const bundle = useView(view.id)
-  const loaded = useLoadedBundle(bundle)
+  const { current, outgoing } = useLoadedBundle(bundle, active)
   // A parked view keeps rendering with the params it was last shown with: the
   // active view's `focusTab` state is not its to render.
   const [shownParams, setShownParams] = useState(params)
@@ -123,7 +129,15 @@ function ViewSlot({ view, active, params }: ViewSlotProps) {
   // an Activity unmounts its children's effects, which would strip the styles
   // off the page while the DOM they style is still parked — the exact flash
   // this component exists to remove. The tag drops when the slot is evicted.
-  useAppletStyle(appletStyleKey('views', workspaceId, view.id), loaded?.version ?? bundle.version)
+  // Holding it here is also what lets the dissolve below overlap two builds:
+  // the styles belong to the slot, not to either frame. The active view's sheet
+  // is raised to the end of <head> so the global at-rule names it shares with
+  // the parked views resolve to the one on screen.
+  useAppletStyle(
+    appletStyleKey('views', workspaceId, view.id),
+    current?.version ?? bundle.version,
+    active
+  )
 
   const failed = bundle.status === 'error'
 
@@ -132,46 +146,103 @@ function ViewSlot({ view, active, params }: ViewSlotProps) {
       {active && failed && (
         <p className="absolute inset-0 p-4 text-xs text-destructive">{bundle.error}</p>
       )}
-      {active && !failed && !loaded && <ViewSplash />}
-      {loaded && !failed && (
-        <Activity mode={active ? 'visible' : 'hidden'}>
-          {/* React hides this node with `display: none` while the Activity is
-              hidden, so a parked view neither paints nor swallows clicks. */}
-          <div
-            key={loaded.version}
-            data-applet={appletScope('views', view.id)}
-            className="absolute inset-0 overflow-auto"
-          >
-            <WidgetErrorBoundary
-              name={view.id}
-              kind="view"
-              workspaceId={workspaceId}
-              resetKey={loaded.version}
-            >
-              <loaded.Component params={shownParams} />
-            </WidgetErrorBoundary>
-          </div>
-        </Activity>
-      )}
+      {active && !failed && !current && <ViewSplash />}
+      {current &&
+        !failed && (
+          // React hides these nodes with `display: none` while the Activity is
+          // hidden, so a parked view neither paints nor swallows clicks.
+          <Activity mode={active ? 'visible' : 'hidden'}>
+            {outgoing && (
+              <ViewFrame key={outgoing.version} view={view} build={outgoing} params={shownParams} />
+            )}
+            <ViewFrame
+              key={current.version}
+              view={view}
+              build={current}
+              params={shownParams}
+              entering={outgoing !== null}
+            />
+          </Activity>
+        )}
     </>
   )
 }
 
-type LoadedView = {
+type ViewFrameProps = {
+  view: ViewInfo
+  build: ViewBuild
+  params: Record<string, unknown>
+  // Play the rebuild dissolve. Set on the incoming build only, and only while
+  // the build it replaced is still rendered underneath it.
+  entering?: boolean
+}
+
+// One build of one view, in its style scope. Frames stack absolutely, so during
+// a rebuild the incoming one dissolves in over the outgoing one still on screen.
+function ViewFrame({ view, build, params, entering }: ViewFrameProps) {
+  const workspaceId = useWorkspaceId()
+
+  return (
+    <div
+      data-applet={appletScope('views', view.id)}
+      className={cn(
+        'absolute inset-0 overflow-auto',
+        entering && 'animate-in duration-200 ease-out blur-in-4 fade-in'
+      )}
+    >
+      <WidgetErrorBoundary
+        name={view.id}
+        kind="view"
+        workspaceId={workspaceId}
+        resetKey={build.version}
+      >
+        <build.Component params={params} />
+      </WidgetErrorBoundary>
+    </div>
+  )
+}
+
+type ViewBuild = {
   Component: ComponentType<AppletComponentProps>
   version: number
 }
 
-// The last build that actually loaded, held across reloads. A rebuild flips the
-// bundle back to `loading` for as long as the fetch takes, and swapping a live
-// view for a spinner every time the agent edits it is worse than showing the
-// previous build for that moment. The splash is for a view with nothing to show
-// yet — the first time it is opened.
-function useLoadedBundle(bundle: AppletState): LoadedView | null {
-  const [loaded, setLoaded] = useState<LoadedView | null>(null)
-  if (bundle.status === 'ready' && loaded?.version !== bundle.version) {
-    setLoaded({ Component: bundle.Component, version: bundle.version })
+type LoadedBundle = {
+  // The build to render, held across reloads. A rebuild flips the bundle back
+  // to `loading` for as long as the fetch takes, and swapping a live view for a
+  // spinner every time the agent edits it is worse than showing the previous
+  // build for that moment. The splash is for a view with nothing to show yet —
+  // the first time it is opened.
+  current: ViewBuild | null
+  // The build `current` just replaced, kept underneath for the length of the
+  // dissolve so the new one fades in over the view instead of over an empty
+  // panel. Null except during a rebuild swap on screen.
+  outgoing: ViewBuild | null
+}
+
+// How long the outgoing build stays underneath. Matches the `duration-200` the
+// incoming frame animates with.
+const DISSOLVE_MS = 200
+
+function useLoadedBundle(bundle: AppletState, dissolve: boolean): LoadedBundle {
+  const [loaded, setLoaded] = useState<LoadedBundle>({ current: null, outgoing: null })
+
+  if (bundle.status === 'ready' && loaded.current?.version !== bundle.version) {
+    const build = { Component: bundle.Component, version: bundle.version }
+    // The first build of a view has nothing to dissolve from, and a parked view
+    // has nobody watching — both swap straight in.
+    setLoaded(previous => ({ current: build, outgoing: dissolve ? previous.current : null }))
   }
+
+  useEffect(() => {
+    if (!loaded.outgoing) return
+    const timer = setTimeout(
+      () => setLoaded(previous => ({ ...previous, outgoing: null })),
+      DISSOLVE_MS
+    )
+    return () => clearTimeout(timer)
+  }, [loaded.outgoing])
+
   return loaded
 }
 
diff --git a/docs/moi-views.md b/docs/moi-views.md
index 099b10d8..ca02fb1c 100644
--- a/docs/moi-views.md
+++ b/docs/moi-views.md
@@ -99,13 +99,18 @@ switch back is instant and the view's component state survives it.
 
 - **First open** — the bundle is fetched behind a centered splash, then rendered.
 - **Switching between loaded views** — instant, no transition. There is no
-  enter/exit animation: a view carries its own styles, and animating the swap
-  means painting frames after the styles are gone.
+  enter/exit animation between views: a view carries its own styles, and
+  animating the swap means painting frames after the styles are gone.
 - **Parked** — hidden with `display: none`. React unmounts the subtree's effects
   while it is hidden and runs them again on return, so a view's effects behave
   like a remount even though its state does not. Scroll position is not kept.
 - **Disposed** — after the retention window (`view-residency.ts`), when the view
   is deleted, or immediately when the workspace closes.
-- A view rebuilt while parked picks the new build up in place. A view rebuilt
-  while on screen keeps showing the previous build until the new one is ready —
-  no splash between edits.
+- **Rebuilt** — a view rebuilt while parked picks the new build up in place. One
+  rebuilt while you are looking at it keeps showing the previous build until the
+  new one is ready, then dissolves the new build in over it (200ms blurred fade,
+  the only animation the view surface has). No splash between edits.
+
+Only the active view's stylesheet is kept last in `<head>`. Applet CSS is scoped
+per container, but the names of global at-rules (`@keyframes`, `@property`) are
+not — so with several views mounted at once, the one on screen wins those names.