@marver-design/marver 0.17.0 → 0.18.0

package/src/client/frame-host/main.tsx

@@ -3,7 +3,7 @@
  * Boot failures (theme, providers, layouts, the frame itself) render a plain-DOM error card
  * and post sh:error; an ErrorBoundary catches render-time throws the same way.
  */
-import { Component, createElement, type ReactNode } from 'react'
+import { Component, createElement, useLayoutEffect, type ReactNode } from 'react'
 import { createRoot } from 'react-dom/client'
 
 import './bridge.js'
@@ -53,9 +53,18 @@ class Boundary extends Component<{ children: ReactNode }, { err: Error | null }>
   }
 }
 
+/** Posts sh:ready once the scene has COMMITTED (render() only schedules; a layout effect on the
+ *  outermost element runs after every child's, before the first paint of the tree). */
+function Committed({ onCommit, children }: { onCommit: () => void; children?: ReactNode }) {
+  useLayoutEffect(onCommit, [])
+  return children
+}
+
 async function boot() {
+  const phases: Record<string, number> = { boot: Math.round(performance.now()) }   // ms since navigation: where a boot spends its time (research/hifi/bootscale.ts)
   try {
     await import('virtual:sh-theme' as string)
+    phases.theme = Math.round(performance.now())
 
     const fileKey = frameFile(id)
     // Honest copy: the id usually IS valid on disk - this document's frame registry is
@@ -63,6 +72,7 @@ async function boot() {
     if (!fileKey) return fail(`frame "${id}" is not in this canvas's registry yet - the file was likely just added or renamed. The canvas should recover on its own; if this card persists, reload it.`)
 
     const frameMod: any = await frames[fileKey]()
+    phases.scene = Math.round(performance.now())
     const Frame = frameMod.default
     // No typeof gate: memo()/forwardRef() components are objects, not functions.
     // React + the ErrorBoundary validate the element type better than we can.
@@ -73,17 +83,21 @@ async function boot() {
     if (providerKey) wrappers.push((await providers[providerKey]() as any).default)
     for (const lk of layoutChain(fileKey)) wrappers.push((await layouts[lk]() as any).default)
 
+    phases.wrappers = Math.round(performance.now())
     let tree: ReactNode = createElement(Frame)
     for (const W of wrappers.reverse()) if (W != null) tree = createElement(W, null, tree)
 
-    createRoot(document.getElementById('root')!).render(createElement(Boundary, null, tree))
-    // stamp the URL revision so the shell can drop a ready queued by a superseded document (one it
-    // auto-renavigated past) - a WindowProxy survives navigation, so a stale ready could otherwise
-    // mark a reloading frame ready. Mirrors the sh:measure generation guard.
-    post({ type: 'sh:ready', id, gen: params.get('r') ?? '', meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined })
+    // sh:ready on the first COMMIT, stamped with the URL revision so the shell can drop a ready queued
+    // by a superseded document (one it auto-renavigated past) - a WindowProxy survives navigation, so
+    // a stale ready could otherwise mark a reloading frame ready. Mirrors the sh:measure generation guard.
+    const ready = () => { phases.commit = Math.round(performance.now()); post({ type: 'sh:ready', id, gen: params.get('r') ?? '', meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined, phases }) }
+    createRoot(document.getElementById('root')!).render(createElement(Boundary, null, createElement(Committed, { onCommit: ready }, tree)))
   } catch (err) {
     fail((err as Error).message)
   }
 }
 
 boot()
+// Fast Refresh keeps this document alive across edits: tell the shell its source changed, so a
+// sleeping frame wakes and compiles again (a texture describes a source revision).
+if (import.meta.hot) import.meta.hot.on('vite:afterUpdate', () => post({ type: 'sh:hmr', id }))

package/src/client/shell/App.tsx

@@ -550,11 +550,18 @@ export function App() {
         // sh:measure does, so a stale ready never marks a reloading frame ready.
         const gen = el.src.match(/[?&]r=(\d+)/)?.[1] ?? ''
         if (String(data.gen ?? '') !== gen) return
+        // a document that loaded again on its own (a full reload) is a new source revision: the
+        // sleeping override of the previous document must not be trusted for this one
+        if (s.nodes.find((n) => n.key === nodeKey)?.status === 'ready') s.bumpRev(nodeKey)
         s.setStatus(nodeKey, 'ready')
       } else if (data.type === 'sh:error') {
         s.setStatus(nodeKey, 'error', String(data.message ?? 'unknown error'))
       } else if (data.type === 'sh:exit-interact') {
         if (s.interact === nodeKey) setInteract(null)
+      } else if (data.type === 'sh:theme-applied') {
+        if (typeof data.theme === 'string') s.setThemeOn(nodeKey, data.theme)
+      } else if (data.type === 'sh:hmr') {
+        s.bumpRev(nodeKey)
       } else if (data.type === 'sh:measure') {
         // Generation guard: the sender echoes ITS document's URL rev; a
         // WindowProxy survives navigation, so a stale pre-navigation message would

package/src/client/shell/Comments.tsx

@@ -935,8 +935,8 @@ export function CommentsController() {
     return () => window.removeEventListener('hashchange', onHash)
   }, [])
 
-  // broadcast pick mode to every LIVE frame (laser rides along inside the bridge). Scoped to
-  // .sh-live so the lean cover (.sh-lean, a scriptless snapshot) is never messaged.
+  // broadcast pick mode to every frame (laser rides along inside the bridge); a sleeping frame
+  // is the live document itself, so it is messaged like any other
   useEffect(() => {
     for (const f of document.querySelectorAll('iframe.sh-live'))
       (f as HTMLIFrameElement).contentWindow?.postMessage({ type: 'sh:pick', on: commentMode, quiet: !ctlShowAnchor }, location.origin)

package/src/client/shell/canvas/Canvas.tsx

@@ -246,8 +246,8 @@ export function Canvas() {
     if (!app || !canvas) return
     let settle = 0
     const beginGesture = (panning: boolean) => {
-      // sh-camera = a CANVAS pan/zoom (drives the snapshot cover); sh-gesturing also drops iframe
-      // pointer-events. A frame click/drag sets only sh-gesturing, so it never flashes a snapshot.
+      // sh-camera = a CANVAS pan/zoom (the image-LOD freeze signal); sh-gesturing also drops iframe
+      // pointer-events. A frame click/drag sets only sh-gesturing.
       document.getElementById('sh-world')?.classList.add('sh-gesturing', 'sh-camera')
       document.body.classList.toggle('sh-panning', panning)
       clearTimeout(settle)

package/src/client/shell/canvas/FrameNode.tsx

@@ -1,12 +1,13 @@
-import { memo, useCallback, useEffect, useRef } from 'react'
+import { memo, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
+import { admit, release } from './admission.ts'
 import { CopyIcon, IntentGlyph, ParallelogramFillIcon, ReloadIcon, SlideFrameIcon, XIcon } from '../icons.tsx'
 import { CommentLayer } from '../Comments.tsx'
 import { useComments } from '../comments-store.ts'
 import { threadHostKey } from '../keys.ts'
 import { registerFrame, unregisterFrame } from './frame-registry.ts'
 import { primeCameraFor } from './camera-broadcast.ts'
-import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from './snapshots.ts'
+import { sleep, wake } from './sleep.ts'
 import { canAutoReload, shouldArmReadyWatch } from './ready-watch.ts'
 
 export const HEADER = 28
@@ -34,6 +35,12 @@ function WorkShimmer({ belowBadge }: { belowBadge: boolean }) {
  * One frame on the canvas. Iframe laws: the iframe element is created once per node key
  * and never remounted - theme changes go through sh:set-theme, size changes are CSS only.
  *
+ * At rest the frame SLEEPS in place (sleep.ts, spec 16): the same live document, its animations
+ * paused and its backdrop-filters replaced by certified textures. Interact mode wakes it; laser,
+ * comment pins and selection act on the sleeping document as it is. A frame the human has
+ * interacted with is a state the compiler cannot reproduce from its URL: it stays awake until
+ * it is reloaded. Any change of theme, size or source wakes first and sleeps again once settled.
+ *
  * Every interactive element carries `sh-no-pan` (rzpp's panning.excluded checks the event
  * TARGET's classList, nothing else), and drags additionally raise the store gesture flag,
  * which hard-disables canvas panning for the duration. Both are needed: the class stops the
@@ -51,21 +58,46 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, reloadFrame, setGesture, toast } = useStore.getState()
   const iframeRef = useRef<HTMLIFrameElement>(null)
   const themeRef = useRef(node.theme)
-  // src is frozen at mount: theme changes ride sh:set-theme (never navigation), so
-  // frame state (forms, scroll, dialogs) survives a theme flip. Real file changes below.
-  const initialSrc = useRef<string | null>(null)
-  if (frame && initialSrc.current === null) initialSrc.current = frameUrl(frame, node.theme)
+  // The JSX src is set ONCE, at ADMISSION, with the theme and revision of that moment, and never
+  // changes again (React would write it back after any later navigation and load the frame twice):
+  // theme changes ride sh:set-theme (never navigation), so frame state (forms, scroll, dialogs)
+  // survives a theme flip; file changes and reloads navigate imperatively below, only once
+  // admitted - a queued frame takes the fresh revision when its turn comes.
+  const [src, setSrc] = useState<string>()
+  const admitted = src !== undefined
+  const admittedRef = useRef(false)
   const fileRef = useRef(frame ? `${frame.kind}:${frame.file}` : null)
 
-  // theme switch without remount: the live iframe flips via message (no navigation). The lean is
-  // INVALIDATED (not mutated) - a baked mermaid SVG can't be re-themed in place, so we drop it, show
-  // live while it re-renders in the new theme, and the capture effect (theme is a dep) rebuilds a
-  // fresh lean that is only shown once ready. No light-on-dark flash.
+  // admission (admission.ts): the iframe gets its src when a boot slot is free, nearest the centre
+  // of the view first; the slot goes back when the frame is ready, errored, gone, or its watchdog acts
+  const navigate = (url: string) => { if (admittedRef.current && iframeRef.current) iframeRef.current.src = url }
+  useEffect(() => {
+    if (!frame || node.missing) { admittedRef.current = false; setSrc(undefined); return }   // gone: the card replaces the iframe; a return is a new document, admitted anew
+    if (admittedRef.current) return   // the document exists (the frame's id changed under it): no slot
+    const rank = () => {   // visible first, then by distance to the centre of the canvas (the panel offsets the window's)
+      const r = iframeRef.current?.getBoundingClientRect(), c = document.querySelector('.sh-canvas')?.getBoundingClientRect()
+      if (!r || !c) return Infinity
+      const visible = r.right > c.left && r.left < c.right && r.bottom > c.top && r.top < c.bottom
+      return (visible ? 0 : 1e7) + Math.hypot(r.x + r.width / 2 - c.x - c.width / 2, r.y + r.height / 2 - c.y - c.height / 2)
+    }
+    const start = () => {
+      const s = useStore.getState(), n = s.nodes.find((x) => x.key === node.key), f = n && s.frameFor(n)
+      if (!n || !f) { release(node.key); return }
+      if (n.status !== 'loading') setStatus(node.key, 'loading')   // a returning frame boots under the watchdog like any other
+      admittedRef.current = true
+      setSrc(frameUrl(f, n.theme))
+    }
+    admit({ key: node.key, rank, start })
+    return () => release(node.key)
+  }, [frame?.id, node.key, node.missing])
+  useEffect(() => { if (node.status !== 'loading') release(node.key) }, [node.status, node.key])
+
+  // theme switch without remount: the live iframe flips via message (no navigation); the frame
+  // reports sh:theme-applied and only then sleeps again under the new theme (node.themeOn)
   useEffect(() => {
     if (themeRef.current !== node.theme) {
       themeRef.current = node.theme
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:set-theme', theme: node.theme }, '*')
-      invalidateLean(node.key)
     }
   }, [node.theme, node.key])
 
@@ -90,53 +122,6 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     registerWin()
   }, [node.key])
 
-  // Register the facade <iframe> so the lean coordinator can drive its srcdoc imperatively.
-  const bindLean = useCallback((el: HTMLIFrameElement | null) => { registerLeanFrame(node.key, el) }, [node.key])
-  // capture a fresh lean snapshot once the frame is ready and quiet, and whenever its CONTENT changes
-  // (nav). Resize needs no re-capture (the lean doc reflows) and theme needs none (attribute flip),
-  // so neither is a dep - keeping captures rare. Never during a gesture; the coordinator serialises.
-  useEffect(() => {
-    // capture reads the live iframe's same-origin document - true in dev AND publish (published frames
-    // are bundled same-origin and served by `marver serve`), so the lean tier works in both via this
-    // client-side capture. Fail-soft: a frame that can't serialise stays live (publish == today's
-    // behaviour in the worst case). No headless build step / heavy dependency needed.
-    if (node.status !== 'ready' || node.missing) return
-    const iframe = iframeRef.current
-    if (!iframe) return
-    const t = setTimeout(() => {
-      // never re-admit a cover while this frame hosts an open thread / draft: the live app
-      // must stay visible (its highlight updates in real time). A status/theme change would
-      // otherwise capture the live DOM WITH the highlight baked in and re-cover it. The
-      // hostsCard rail recaptures a clean lean once the card closes.
-      const c = useComments.getState()
-      // hosting goes through the resolver (keys.ts): an adopted thread's card renders
-      // here even though its stored nodeKey names a node that no longer exists
-      const hosting = (!!c.active && c.threads.some((th) =>
-        th.id === c.active && !th.resolved && threadHostKey(th, useStore.getState().nodes) === node.key)) || c.draft?.nodeKey === node.key
-      if (hosting) return
-      scheduleCapture(node.key, iframe, { sourceRevision: String(node.nav ?? 0), theme: node.theme })
-    }, 450)
-    return () => clearTimeout(t)
-    // node.theme IS a dep: baked content (mermaid SVG) can't be re-themed by the cover's attribute
-    // flip, so a theme change re-captures after the live frame re-renders (key includes theme).
-  }, [node.status, node.nav, node.key, node.missing, node.theme])
-  useEffect(() => () => dropSnapshot(node.key), [node.key])   // drop the snapshot on unmount
-  // a reload / file-swap / error takes the frame out of 'ready': drop its cover so a stale picture
-  // never lingers (nav may not bump on a same-file reload). The next 'ready' re-captures.
-  useEffect(() => { if (node.status !== 'ready') dropSnapshot(node.key) }, [node.status, node.key])
-  // LEAN-PRIMARY focus handoff: entering interact shows the live app (drop the now-stale lean at
-  // once); leaving it recaptures the live frame's CURRENT state (the user may have typed/toggled)
-  // and only swaps back to lean once that fresh capture is admitted. force=true: same nav/theme.
-  const prevInteract = useRef(interact)
-  useEffect(() => {
-    if (prevInteract.current === interact) return
-    const wasInteract = prevInteract.current
-    prevInteract.current = interact
-    if (interact) invalidateLean(node.key)
-    else if (wasInteract && node.status === 'ready' && iframeRef.current)
-      scheduleCapture(node.key, iframeRef.current, { sourceRevision: String(node.nav ?? 0), theme: node.theme }, true)
-  }, [interact, node.key, node.nav, node.theme, node.status])
-
   // laser mode rides the same rail; re-sent when a frame becomes ready
   // so late loaders join an already-lasered board
   const laser = useStore((s) => s.laser)
@@ -147,21 +132,6 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   const hostsCard = useComments((s) =>
     (!!s.active && s.threads.some((t) =>
       t.id === s.active && !t.resolved && threadHostKey(t, useStore.getState().nodes) === node.key)) || s.draft?.nodeKey === node.key)
-  // a frame hosting an OPEN thread or a draft must show its LIVE app, not the frozen lean
-  // cover: the active-element highlight lives in the live DOM and updates in real time
-  // (open -> lit, close -> cleared). Without this the cover re-freezes the moment comment
-  // mode ends and either bakes a stale highlight or hides the live one. Mirror the interact
-  // rail: drop the cover while hosting, rebuild a fresh lean once the card closes (the
-  // highlight is cleared by then, so the recapture is clean).
-  const prevHostsCard = useRef(hostsCard)
-  useEffect(() => {
-    if (prevHostsCard.current === hostsCard) return
-    const wasHosting = prevHostsCard.current
-    prevHostsCard.current = hostsCard
-    if (hostsCard) invalidateLean(node.key)
-    else if (wasHosting && node.status === 'ready' && iframeRef.current)
-      scheduleCapture(node.key, iframeRef.current, { sourceRevision: String(node.nav ?? 0), theme: node.theme }, true)
-  }, [hostsCard, node.key, node.nav, node.theme, node.status])
   useEffect(() => {
     if (node.status === 'ready' || !laser)
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:laser', on: laser }, location.origin)
@@ -179,6 +149,32 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     if (node.status === 'ready' || !interact)
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:interactive', on: interact }, location.origin)
   }, [interact, node.status])
+  // SLEEP lifecycle. Interact = awake and DIRTY (the app's state is now its own); a resize drag =
+  // awake for the whole drag; any other change of the key (theme once applied, size, source revision,
+  // navigation) wakes first - the old override describes another state - and sleeps again once the
+  // new one has settled. Laser and comment mode need nothing: the sleeping document IS the live one.
+  const dirty = useRef(false)
+  const lastDoc = useRef<Document | null>(null)   // a new document (reload, self-reload) is pristine again
+  const resizing = useRef(false)
+  const [resizeTick, setResizeTick] = useState(0)
+  useEffect(() => { dirty.current = false }, [node.nav])   // a fresh document is pristine again
+  const w = Math.round(node.w), h = Math.round(node.h)
+  // a layout effect: the wake lands BEFORE the first paint of the new state (a stretched texture
+  // must never be painted at a new size)
+  useLayoutEffect(() => {
+    const iframe = iframeRef.current
+    if (!iframe || !frame || node.missing) { wake(node.key, null); return }   // nothing to keep (a deleted frame's card must not retain its old document)
+    const doc = iframe.contentDocument
+    if (doc && doc !== lastDoc.current) { lastDoc.current = doc; dirty.current = false }
+    if (interact) dirty.current = true
+    wake(node.key, iframe)
+    if (interact || dirty.current || resizing.current || node.status !== 'ready') return
+    if (node.themeOn !== undefined && node.themeOn !== node.theme) return   // the frame has not painted the new theme yet
+    const t = setTimeout(() => { void sleep(node.key, iframe, { frame: frame.id, theme: node.theme, w, h }) }, 250)
+    return () => clearTimeout(t)
+  }, [interact, node.status, node.theme, node.themeOn, node.rev, node.nav, w, h, node.missing, frame?.id, node.key, resizeTick])
+  useEffect(() => () => wake(node.key, iframeRef.current), [node.key])
+
   // image-LOD: once the frame is ready its content listener is live, so send the settled zoom - a static
   // board that never gets a gesture then still sharpens its images from the cheap low-res first paint.
   useEffect(() => {
@@ -191,7 +187,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     const sig = `${frame.kind}:${frame.file}`
     if (fileRef.current !== null && fileRef.current !== sig && iframeRef.current) {
       setStatus(node.key, 'loading')
-      iframeRef.current.src = frameUrl(frame, node.theme)
+      navigate(frameUrl(frame, node.theme))
     }
     fileRef.current = sig
   }, [frame?.kind, frame?.file])
@@ -202,7 +198,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   useEffect(() => {
     if ((node.nav ?? 0) === navRef.current) return
     navRef.current = node.nav ?? 0
-    if (frame && iframeRef.current) iframeRef.current.src = frameUrl(frame, node.theme)
+    if (frame) navigate(frameUrl(frame, node.theme))
   }, [node.nav])
 
   // Reload the frame, assigning the fresh URL SYNCHRONOUSLY so the live iframe's src is current the
@@ -215,8 +211,8 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     reloadFrame(node.key, automatic)
     const after = useStore.getState().nodes.find((x) => x.key === node.key)
     const f = useStore.getState().frameFor(node)
-    if (after && f && iframeRef.current) {
-      iframeRef.current.src = frameUrl(f, node.theme)
+    if (after && f) {
+      navigate(frameUrl(f, node.theme))
       navRef.current = after.nav ?? 0
     }
   }
@@ -231,14 +227,16 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   // auto-renavigates ONCE on a fresh rev; a second silence stays 'loading' (never a red error card).
   // node.nav is a dep so a fresh navigation restarts the full budget; readyRetried flips true on the
   // retry and bounds it to exactly one.
+  // The budget counts from ADMISSION (a queued frame is not silent). The retried document keeps its
+  // boot slot - its boot is still running - and gives it back after a second silence.
   useEffect(() => {
-    if (!shouldArmReadyWatch(node, !!frame)) return
-    const t = setTimeout(() => reloadRef.current(true), 10_000)
+    if (!admitted || node.status !== 'loading' || !frame || node.missing) return
+    const t = setTimeout(() => { if (shouldArmReadyWatch(node, true)) reloadRef.current(true); else release(node.key) }, 10_000)
     return () => clearTimeout(t)
     // depend on the frame's stable SIGNATURE, not the manifest object - that object is replaced on
     // every manifest reconcile, so depending on it would reset the budget on unrelated frames during
     // heavy Live Jam churn and starve the retry. kind/file still re-arm on a real file swap.
-  }, [node.status, node.readyRetried, node.nav, node.key, node.missing, frame?.kind, frame?.file])
+  }, [admitted, node.status, node.readyRetried, node.nav, node.key, node.missing, frame?.kind, frame?.file])
 
   const drag = (e: React.PointerEvent, mode: 'move' | 'e' | 's' | 'se') => {
     e.stopPropagation()
@@ -268,8 +266,9 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     const begin = () => {
       if (gesturing) return
       gesturing = true
-      world.classList.add('sh-gesturing')   // drops iframe pointer-events (sh-camera is NOT set, so no cover)
+      world.classList.add('sh-gesturing')   // drops iframe pointer-events
       setGesture(true)
+      if (mode !== 'move') { resizing.current = true; wake(node.key, iframeRef.current); setResizeTick((t) => t + 1) }   // awake before the first resized paint, for the whole resize
     }
     const MOVE_THRESHOLD = 3   // px in screen space before a press counts as a drag
 
@@ -297,6 +296,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
       try { el.releasePointerCapture(e.pointerId) } catch { /* already released */ }
       world.classList.remove('sh-gesturing')
       setGesture(false)
+      if (resizing.current) { resizing.current = false; setResizeTick((t) => t + 1) }   // settle, then sleep again
       el.removeEventListener('pointermove', onMove)
       el.removeEventListener('pointerup', done)
       el.removeEventListener('pointercancel', done)
@@ -398,18 +398,11 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
         <iframe
           ref={bindIframe}
           className="sh-live"
-          src={initialSrc.current ?? frameUrl(frame, node.theme)}
+          src={src}
           title={frame.id}
           onLoad={registerWin}
           style={{ width: node.w, height: node.h, display: node.missing || node.status === 'error' ? 'none' : 'block' }}
         />
-        {/* Lean facade: a DOM-snapshot (static html, 0 JS) covering the live iframe only while
-            the canvas is gesturing (CSS), so a heavy frame never flashes white mid-transform and the
-            device sweep reflows correctly. sandbox WITHOUT allow-scripts = no JS runs; allow-same-origin
-            so fonts/assets resolve and the shell can flip its theme + restore scroll. Never registered,
-            never messaged, pointer-events:none - it is NOT the live iframe (role: .sh-lean).
-            Rendered in dev AND publish (runtime client-side capture; frames are same-origin in both). */}
-        <iframe ref={bindLean} className="sh-lean" sandbox="allow-same-origin" title="" aria-hidden tabIndex={-1} />
         {/* the overlay eats mouse events for drag-by-body; laser and comment mode both
             need the mouse INSIDE the frame for hover highlights, so it steps aside
             (drag still works via the header) */}

package/src/client/shell/canvas/admission.ts

@@ -0,0 +1,70 @@
+/**
+ * Frame admission: how many iframes boot at once.
+ *
+ * Every frame on a board is a document booting on the ONE renderer main thread (~400 ms each for a
+ * lo-fi React frame), and a batch that starts together finishes together: 64 started at once, the
+ * first is ready at 25.6 s and the last at 26.0 s - the board is blank until the end. Admitted a few
+ * at a time, the first is ready at 1.8 s and the board fills in view order for the same total
+ * (research/hifi/bootscale.ts). The ready watchdog counts from admission, not from mount, so a
+ * queued frame is never mistaken for a stalled one.
+ *
+ * A new batch admits ONE frame first (the quickest first content: one boot alone is ~550 ms, four
+ * together ~1.8 s), then up to SLOTS at a time. Pure, apart from its timing: a board that mounts
+ * registers every node, the shell fits the camera (App.tsx, a few tens of ms later), then the first
+ * pump ranks them (visible first, nearest the centre of the canvas first); a freed slot pumps on
+ * the next microtask, ranking again by the view of that moment.
+ */
+export const SLOTS = 4
+/** A new batch's head start: one frame alone until it is done, or until this long - one stalled
+ *  first frame must not hold the whole board. */
+export const HEAD_MS = 2000
+let primed = false   // the batch may use every slot
+let gen = 0          // the batch: a pump scheduled for an earlier one is void
+let timer: ReturnType<typeof setTimeout> | undefined
+
+export interface Admission { key: string; rank: () => number; start: () => void }
+
+const waiting = new Map<string, Admission>()
+const active = new Set<string>()
+let scheduled = false
+
+/** Ask for a slot. Starts once the view has settled (SETTLE ms) when one is free; else queued by rank. */
+export function admit(a: Admission): void {
+  if (active.has(a.key)) return
+  if (!waiting.size && !active.size) {   // a new batch
+    primed = false; gen++; scheduled = false; clearTimeout(timer)
+    timer = setTimeout(() => { primed = true; schedule(0) }, HEAD_MS)
+  }
+  waiting.set(a.key, a)
+  schedule(SETTLE)
+}
+const SETTLE = 350   // the board fit animates ~250 ms from 60 ms after mount: rank the first pick on the settled view
+
+/** The frame is done booting (ready, error, gone, or its watchdog took over): free the slot, or
+ *  leave the queue if it never started. */
+export function release(key: string): void {
+  waiting.delete(key)
+  if (active.delete(key)) { primed = true; schedule(0) }
+}
+
+function schedule(ms: number): void {
+  if (scheduled) return
+  scheduled = true
+  const g = gen, run = () => { if (g === gen) pump() }
+  if (ms) setTimeout(run, ms); else queueMicrotask(run)
+}
+
+function pump(): void {
+  scheduled = false
+  while (active.size < (primed ? SLOTS : 1) && waiting.size) {
+    let best: Admission | undefined, bestRank = Infinity
+    for (const a of waiting.values()) { const r = a.rank(); if (r < bestRank || !best) { best = a; bestRank = r } }
+    waiting.delete(best!.key)
+    active.add(best!.key)
+    ;(globalThis as { __mvAdmitted?: string[] }).__mvAdmitted?.push(best!.key)   // diagnostic: the order, when a probe asks for it
+    best!.start()
+  }
+}
+
+/** For tests: nothing queued, nothing active. */
+export function resetAdmission(): void { waiting.clear(); active.clear(); primed = false; scheduled = false; gen++; clearTimeout(timer) }