de-shell 0.2.0__py3-none-any.whl

de_shell/js/main/window.ts

@@ -0,0 +1,141 @@
+/**
+ * window.ts — the app window, and getting backend messages into it.
+ *
+ * Both live apps had written this identically: create a BrowserWindow with the
+ * preload attached, buffer backend messages until the renderer is listening,
+ * flush them in order, and tee renderer console output to the terminal.
+ *
+ * The buffering is the part that is not obvious. Backend messages can arrive
+ * before the renderer has finished loading and registered its `ipcRenderer`
+ * listener, and `webContents.send()` DROPS anything sent before then — silently.
+ * That swallowed the first message after any quiet period: in SpyDE, the
+ * nav-shape prompt on opening a file (the dialog only appeared once a later load
+ * pushed more messages); in a live app, the very first figure. So messages queue
+ * until `did-finish-load` and are then flushed in order.
+ */
+import { BrowserWindow } from 'electron'
+import { join } from 'path'
+import { channel, shellConfig } from './config'
+
+export interface ShellWindowOptions {
+  /** Directory of the running main bundle — normally `__dirname`. Preload and
+   *  renderer are resolved relative to it (`../preload`, `../renderer`). */
+  mainDir: string
+  width?: number
+  height?: number
+  backgroundColor?: string
+  /** Extra BrowserWindow options, merged last. */
+  browserWindow?: Electron.BrowserWindowConstructorOptions
+  /** Tee renderer + figure-iframe console output to this process's stdout.
+   *  Warnings and errors always; `logFilter` opts extra lines in. */
+  teeConsole?: boolean
+  /** Return true to tee a console message that is below warning level. */
+  logFilter?: (message: string) => boolean
+}
+
+export interface ShellWindow {
+  /** The window. Null once it has been closed. */
+  get(): BrowserWindow | null
+  /** Send a backend message to the renderer, buffering until it is listening. */
+  sendToRenderer(msg: Record<string, unknown>): void
+  /** Raw backend stdout/stderr, on the preload's `onStream` channel. Not
+   *  buffered: a line that arrives before the renderer listens is a line
+   *  nobody was going to read. */
+  sendStream(text: string, kind: 'stdout' | 'stderr'): void
+  /** True when there is a live window whose webContents is not destroyed. */
+  alive(): boolean
+}
+
+/**
+ * Create the app's window and its message pipe.
+ *
+ * Loads `ELECTRON_RENDERER_URL` when electron-vite's dev server set it, and the
+ * built `../renderer/index.html` otherwise.
+ */
+export function createShellWindow(opts: ShellWindowOptions): ShellWindow {
+  const cfg = shellConfig()
+  const messageChannel = channel('message')
+  const streamChannel = channel('stream')
+
+  let win: BrowserWindow | null = null
+  let rendererReady = false
+  const pending: Array<Record<string, unknown>> = []
+
+  const alive = () =>
+    !!win && !win.isDestroyed() && !win.webContents.isDestroyed()
+
+  const flush = () => {
+    if (!alive()) return
+    while (pending.length) win!.webContents.send(messageChannel, pending.shift())
+  }
+
+  const sendToRenderer = (msg: Record<string, unknown>) => {
+    if (!rendererReady || !alive()) { pending.push(msg); return }
+    win!.webContents.send(messageChannel, msg)
+  }
+  const sendStream = (text: string, kind: 'stdout' | 'stderr') => {
+    if (rendererReady && alive()) win!.webContents.send(streamChannel, text, kind)
+  }
+
+  win = new BrowserWindow({
+    width: opts.width ?? 1280,
+    height: opts.height ?? 860,
+    backgroundColor: opts.backgroundColor ?? '#14161c',
+    // Shown on ready-to-show rather than immediately, so the user never sees an
+    // empty white frame while the renderer boots.
+    show: false,
+    webPreferences: {
+      preload: join(opts.mainDir, '..', 'preload', 'index.js'),
+      sandbox: false,
+    },
+    ...opts.browserWindow,
+  })
+
+  win.once('ready-to-show', () => win?.show())
+  win.webContents.on('did-finish-load', () => { rendererReady = true; flush() })
+  // A reload (dev HMR, Ctrl+R) tears the listener down with the page. Close the
+  // gate again so messages queue for the NEW page instead of being sent into a
+  // frame that is going away — the exact loss the buffering exists to prevent.
+  win.webContents.on('did-start-navigation', (_e, _url, isInPlace, isMainFrame) => {
+    if (isMainFrame && !isInPlace) rendererReady = false
+  })
+  win.on('closed', () => { win = null; rendererReady = false })
+
+  if (opts.teeConsole !== false) {
+    // Renderer AND figure-iframe console output, so a JS error inside a figure
+    // frame is visible without opening devtools and switching frame context.
+    //
+    // TWO event signatures, and getting this wrong fails SILENTLY — the tee
+    // simply stops teeing, which is the worst way for a diagnostic to break.
+    // Electron <35: (event, level: number, message, line, sourceId), where
+    // level is 0=log 1=warning 2=error 3=info. Electron >=35: (event, details)
+    // with a STRING level. Reading `level >= 1` off the details OBJECT is
+    // always false, so every message is dropped.
+    win.webContents.on('console-message', (...args: unknown[]) => {
+      const [, second, third] = args
+      let message: string
+      let warnOrWorse: boolean
+      if (second !== null && typeof second === 'object') {
+        const d = second as { message?: string; level?: string | number }
+        message = String(d.message ?? '')
+        warnOrWorse = typeof d.level === 'number'
+          ? d.level >= 1
+          : d.level === 'warning' || d.level === 'error'
+      } else {
+        message = String(third ?? '')
+        warnOrWorse = Number(second) >= 1
+      }
+      if (warnOrWorse || opts.logFilter?.(message)) {
+        console.log(`[${cfg.appId} renderer] ${message}`)
+      }
+    })
+  }
+
+  if (process.env.ELECTRON_RENDERER_URL) {
+    win.loadURL(process.env.ELECTRON_RENDERER_URL)
+  } else {
+    win.loadFile(join(opts.mainDir, '..', 'renderer', 'index.html'))
+  }
+
+  return { get: () => win, sendToRenderer, sendStream, alive }
+}

de_shell/js/package.json

@@ -0,0 +1,5 @@
+{
+  "type": "module",
+  "private": true,
+  "//": "Node loads the .ts files here as ES modules (node --test with native type stripping); without this it guesses per file and warns. harness.cjs says what it is by its extension."
+}

de_shell/js/preload/index.ts

@@ -0,0 +1,130 @@
+/**
+ * @de/shell-preload — the contextBridge surface every shell app exposes.
+ *
+ * Both apps had written the same handful of channels by hand: receive backend
+ * messages and raw stdio, send an action, forward a figure event, report a
+ * figure resize. This builds that core from the app's id and lets the app spread
+ * its own extras alongside.
+ *
+ * ## Disposers are the whole point of the `on*` shape
+ *
+ * Every listener registration returns an UNSUBSCRIBE function. The renderer
+ * registers these in a `useEffect`, and without cleanup React StrictMode's
+ * double-invoke — and every HMR remount — stacks duplicate `ipcRenderer`
+ * listeners, so each message is dispatched twice, then three times, and the app
+ * degrades as you work. Returning a disposer lets the effect remove the exact
+ * listener it added. Do not "simplify" these to bare `ipcRenderer.on`.
+ */
+import { contextBridge, ipcRenderer, webUtils } from 'electron'
+
+/** An Electron dialog file filter, restated so the renderer need not depend on
+ *  electron's types. */
+export interface FileFilter { name: string; extensions: string[] }
+
+export interface ShellBridgeOptions {
+  /** Matches @de/shell-main's `appId` — channels are `<appId>:<name>`. */
+  appId: string
+  /** Env var the main process sets from `app.isPackaged`, if the app gates
+   *  test-only hooks on it. Defaults to `<APPID>_PACKAGED`. */
+  packagedEnvVar?: string
+}
+
+/**
+ * The channels every shell app shares. Returned rather than exposed, so an app
+ * can spread its own on top:
+ *
+ *     contextBridge.exposeInMainWorld('myapp', {
+ *       ...createShellBridge({ appId: 'myapp' }),
+ *       myOwnThing: () => ipcRenderer.invoke('myapp:thing'),
+ *     })
+ */
+export function createShellBridge(opts: ShellBridgeOptions) {
+  const { appId } = opts
+  const packagedVar = opts.packagedEnvVar
+    ?? `${appId.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_PACKAGED`
+  const channel = (name: string) => `${appId}:${name}`
+
+  /** Register `handler` on `ch`, returning its exact disposer. */
+  const on = <A extends unknown[]>(
+    ch: string, cb: (...args: A) => void,
+  ): (() => void) => {
+    const h = (_: unknown, ...args: A) => cb(...args)
+    ipcRenderer.on(ch, h as never)
+    return () => { ipcRenderer.removeListener(ch, h as never) }
+  }
+
+  return {
+    /** 'darwin' | 'win32' | 'linux' — hosts lay out the title bar from it. */
+    platform: process.platform,
+
+    /** True only in a packaged production app. Dev and the Playwright e2e
+     *  (which launches the BUILT bundle by path, not a packaged app) leave the
+     *  env var unset, so test-only hooks stay live in both. */
+    isPackaged: process.env[packagedVar] === '1',
+
+    /** Any backend message. Returns an unsubscribe fn. */
+    onMessage: (cb: (msg: Record<string, unknown>) => void) =>
+      on<[Record<string, unknown>]>(channel('message'), cb),
+
+    /** Raw stdout/stderr lines from the backend. Returns an unsubscribe fn. */
+    onStream: (cb: (text: string, kind: 'stdout' | 'stderr') => void) =>
+      on<[string, 'stdout' | 'stderr']>(channel('stream'), cb),
+
+    /** Send an action to the backend. */
+    action: (action: string, payload: Record<string, unknown> = {}, windowId?: number) =>
+      ipcRenderer.send(channel('action'), action, payload, windowId),
+
+    /** Forward an interaction event from an anyplotlib iframe to the backend. */
+    figureEvent: (figId: string, eventJson: string) =>
+      ipcRenderer.send(channel('figure-event'), figId, eventJson),
+
+    /** Tell the backend a figure's container resized, so its layout keeps up. */
+    resizeFigure: (figId: string, width: number, height: number) =>
+      ipcRenderer.send(channel('resize'), figId, width, height),
+
+    /** Open a URL in the user's browser. Main allowlists the protocol. */
+    openExternal: (url: string) => ipcRenderer.send('open-external', url),
+
+    /** OS path of a dropped File. A sandboxed renderer has no `File.path`, so
+     *  drag-and-drop of datasets needs this. */
+    pathForFile: (file: File): string | null => {
+      try {
+        return webUtils.getPathForFile(file) || null
+      } catch {
+        return null
+      }
+    },
+
+    /** Native open dialog. Resolves to a path, or null if cancelled.
+     *
+     *  `invoke`, not `send`: the caller needs the answer, and threading a
+     *  reply back through the message channel would mean correlating requests
+     *  by hand. Main owns the dialog because a sandboxed renderer cannot make
+     *  one, and because main is where the parent window is. */
+    openFile: (filters?: FileFilter[]): Promise<string | null> =>
+      ipcRenderer.invoke(channel('open-file'), filters),
+
+    /** Native directory picker. Resolves to a path, or null if cancelled. */
+    openDirectory: (): Promise<string | null> =>
+      ipcRenderer.invoke(channel('open-directory')),
+
+    /** Native save dialog. Resolves to a path, or null if cancelled. */
+    saveFile: (filters?: FileFilter[], defaultPath?: string): Promise<string | null> =>
+      ipcRenderer.invoke(channel('save-file'), filters, defaultPath),
+
+    /** Escape hatch for an app's own channels, so it does not have to
+     *  re-implement the disposer discipline above. */
+    onChannel: on,
+  }
+}
+
+/** Build the core surface and expose it as `window[appId]`, merged with
+ *  `extra`. The common case; use `createShellBridge` directly if the app needs
+ *  to name the global something else. */
+export function exposeShellBridge(
+  opts: ShellBridgeOptions, extra: Record<string, unknown> = {},
+): void {
+  contextBridge.exposeInMainWorld(opts.appId, {
+    ...createShellBridge(opts), ...extra,
+  })
+}

de_shell/js/renderer/FigureFrame.tsx

@@ -0,0 +1,88 @@
+/**
+ * FigureFrame.tsx — an anyplotlib figure in an iframe, wired to the bridge.
+ *
+ * Handles the three things every host of a figure has to get right, and which
+ * are easy to omit without any error appearing:
+ *
+ * * **Register with the bridge**, so state can be routed to this frame — and
+ *   deregister on unmount, so a dead element is not held.
+ * * **Replay on load**, passing THIS element. State that arrived before the
+ *   frame mounted was posted into the void; replay is the only thing that
+ *   recovers it, and a figure mounted twice must serve itself rather than
+ *   whichever mount happens to hold the registry slot.
+ * * **Report its size**, so the backend can lay the figure out to fit. Without
+ *   it the figure renders at anyplotlib's default size and overflows its pane.
+ *
+ * `srcdoc` vs `src`: a backend that inlines the figure's ESM can be mounted
+ * directly from `html`. One that swaps the bundle for a shared URL (SpyDE does,
+ * so Chromium reuses the V8 code cache across many figure iframes) MUST be
+ * served over a real origin and passes `fileUrl` instead — a srcdoc frame
+ * cannot load it. Note that a srcdoc frame INHERITS the parent page's CSP, so
+ * the host page needs `script-src … blob:` for anyplotlib's ESM boot.
+ */
+import React, { useEffect, useRef } from 'react'
+import type { FigureBridge } from './figureBridge'
+
+export interface FigureFrameProps {
+  bridge: FigureBridge
+  figId: string
+  /** Inline figure HTML (mounted via srcdoc). Ignored when `fileUrl` is set. */
+  html?: string
+  /** Figure URL served over the app's own scheme. Takes precedence over `html`. */
+  fileUrl?: string | null
+  title?: string
+  /** Called with the frame's pixel size whenever it changes. */
+  onResize?: (width: number, height: number) => void
+  className?: string
+  style?: React.CSSProperties
+  'data-testid'?: string
+}
+
+export function FigureFrame({
+  bridge, figId, html, fileUrl, title, onResize, className, style,
+  'data-testid': testId,
+}: FigureFrameProps) {
+  const ref = useRef<HTMLIFrameElement | null>(null)
+
+  // Report size to the backend. Fires once on mount and on every resize; the
+  // zero-size guard skips the frame's first layout pass, which would otherwise
+  // tell the backend to lay the figure out at 0×0.
+  useEffect(() => {
+    const el = ref.current
+    if (!el || !onResize) return
+    const send = () => {
+      const r = el.getBoundingClientRect()
+      if (r.width > 0 && r.height > 0) {
+        onResize(Math.round(r.width), Math.round(r.height))
+      }
+    }
+    send()
+    const ro = new ResizeObserver(send)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [figId, onResize])
+
+  // Deregister on unmount so the bridge never holds a detached element.
+  useEffect(() => () => bridge.registerIframe(figId, null), [bridge, figId])
+
+  return (
+    <iframe
+      ref={(el) => { ref.current = el; bridge.registerIframe(figId, el) }}
+      // Keyed by figId so React REUSES the element across repaints. Remounting
+      // per frame would tear down the figure's WebGPU context and throw away
+      // the user's zoom.
+      key={figId}
+      title={title ?? figId}
+      {...(fileUrl ? { src: fileUrl } : { srcDoc: html })}
+      className={className}
+      // `display: block` FIRST, so a caller's style can still override it. An
+      // iframe is inline by default, which reserves descender space under it:
+      // a host sized to `height: 100%` then overflows by ~4-5 px and grows a
+      // scrollbar around a figure that looks correctly sized.
+      style={{ display: 'block', ...style }}
+      data-testid={testId}
+      // ITSELF, never whichever mount currently holds the registry slot.
+      onLoad={() => bridge.replay(figId, ref.current ?? undefined)}
+    />
+  )
+}

de_shell/js/renderer/figureBridge.react.ts

@@ -0,0 +1,58 @@
+/**
+ * figureBridge.react.ts — the React binding for the figure bridge.
+ *
+ * Split from `figureBridge.ts` so the bridge itself stays plain TypeScript:
+ * it is stateful but not reactive, and keeping it free of React means it can be
+ * unit-tested without a renderer.
+ */
+import { useEffect, useRef } from 'react'
+import { createFigureBridge, type FigureBridge } from './figureBridge'
+
+export { createFigureBridge }
+export type { FigureBridge }
+
+/**
+ * One bridge per component tree, with a STABLE identity for the life of the
+ * component.
+ *
+ * The stability matters: the bridge holds every figure's retained state, so a
+ * bridge rebuilt on re-render would drop it, and any figure that had already
+ * painted would go blank the next time its iframe reloaded. It is also
+ * depended on by effects — a changing identity would re-run them every render.
+ */
+export function useFigureBridge(
+  log?: (label: string, detail: Record<string, unknown>) => void,
+): FigureBridge {
+  const ref = useRef<FigureBridge | null>(null)
+  if (ref.current === null) ref.current = createFigureBridge(log)
+  return ref.current
+}
+
+
+/**
+ * Forward anyplotlib interaction events from the figure iframes to the backend.
+ *
+ * An anyplotlib figure posts `{type: 'awi_event', figId, data}` up to its host
+ * window when the user clicks, drags or presses a key inside it. Nothing
+ * happens to that message unless someone listens and relays it — so WITHOUT
+ * this hook every `plot.add_event_handler(...)` registered in Python is silently
+ * dead, which is exactly how it presented: arming a measurement worked, and the
+ * drag that followed reached nothing.
+ *
+ * Call once, high in the app. `send` is normally the preload's `figureEvent`.
+ */
+export function useFigureEventForwarding(
+  send: (figId: string, eventJson: string) => void,
+): void {
+  useEffect(() => {
+    const onMessage = (e: MessageEvent) => {
+      const d = e.data
+      if (d?.type !== 'awi_event' || !d.figId) return
+      // `data` is already a JSON STRING on the wire; stringify an object form
+      // rather than sending "[object Object]" down the protocol.
+      send(d.figId, typeof d.data === 'string' ? d.data : JSON.stringify(d.data))
+    }
+    window.addEventListener('message', onMessage)
+    return () => window.removeEventListener('message', onMessage)
+  }, [send])
+}

de_shell/js/renderer/figureBridge.test.ts

@@ -0,0 +1,184 @@
+/**
+ * figureBridge.test.ts — the retention rules, pinned.
+ *
+ * Every case here corresponds to a bug that shipped: a blank presented slide, a
+ * multi-panel figure with one panel drawn, a stash emptied by its own replay.
+ * They are cheap to assert and expensive to rediscover.
+ *
+ * Run by `npm run test:unit` (node:test, native TS type-stripping).
+ */
+import { test, describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { createFigureBridge } from './figureBridge.ts'
+
+/** A stand-in iframe that records what was posted into it. */
+function fakeIframe(testid = 'frame') {
+  const posted: Array<{ message: any; transfer: any }> = []
+  return {
+    posted,
+    el: {
+      contentWindow: {
+        postMessage(message: any, _origin: string, transfer?: any) {
+          posted.push({ message, transfer })
+        },
+      },
+      getAttribute: () => testid,
+      getBoundingClientRect: () => ({ width: 10, height: 10 }),
+    } as unknown as HTMLIFrameElement,
+  }
+}
+
+describe('state forwarding and retention', () => {
+  test('a state posted before any iframe mounts is retained and replayed', () => {
+    const bridge = createFigureBridge()
+    // Nothing registered yet — this post goes nowhere, silently. The retention
+    // is the only thing that saves it.
+    bridge.applyState('f1', 'title', 'hello')
+
+    const frame = fakeIframe()
+    bridge.registerIframe('f1', frame.el)
+    bridge.replay('f1')
+
+    assert.deepEqual(frame.posted.map(p => p.message),
+      [{ type: 'awi_state', key: 'title', value: 'hello' }])
+  })
+
+  test('only the latest value per key is retained', () => {
+    const bridge = createFigureBridge()
+    bridge.applyState('f1', 'k', 1)
+    bridge.applyState('f1', 'k', 2)
+    const frame = fakeIframe()
+    bridge.registerIframe('f1', frame.el)
+    bridge.replay('f1')
+    assert.deepEqual(frame.posted.map(p => p.message.value), [2])
+  })
+
+  test('state is posted live to a mounted frame', () => {
+    const bridge = createFigureBridge()
+    const frame = fakeIframe()
+    bridge.registerIframe('f1', frame.el)
+    bridge.applyState('f1', 'k', 'v')
+    assert.equal(frame.posted.length, 1)
+  })
+})
+
+describe('binary frames', () => {
+  test('panels are stashed separately, keyed by geom', () => {
+    // The multi-panel bug: `key` is the pixel FIELD and is identical across
+    // panels, so stashing by key alone left one frame however many panels the
+    // figure had — and a presented copy drew one panel and blanks.
+    const bridge = createFigureBridge()
+    bridge.applyBinary('f1', 'image_b64', { geom: 'panel_a' }, new Uint8Array([1]))
+    bridge.applyBinary('f1', 'image_b64', { geom: 'panel_b' }, new Uint8Array([2]))
+
+    const slot = bridge.binaryStates.current.get('f1')!
+    assert.deepEqual([...slot.keys()].sort(),
+      ['panel_a::image_b64', 'panel_b::image_b64'])
+  })
+
+  test('a frame with no geom falls back to the pixel key', () => {
+    const bridge = createFigureBridge()
+    bridge.applyBinary('f1', 'image_b64', {}, new Uint8Array([1]))
+    assert.deepEqual([...bridge.binaryStates.current.get('f1')!.keys()], ['image_b64'])
+  })
+
+  test('the live post transfers the buffer', () => {
+    const bridge = createFigureBridge()
+    const frame = fakeIframe()
+    bridge.registerIframe('f1', frame.el)
+    const bytes = new Uint8Array([1, 2, 3])
+    bridge.applyBinary('f1', 'image_b64', { geom: 'g' }, bytes)
+    assert.deepEqual(frame.posted[0].transfer, [bytes.buffer])
+  })
+
+  test('the stash survives its own replay, and every replay sends a fresh copy', () => {
+    // Transfer DETACHES the buffer it sends. Replaying the stashed array itself
+    // would empty the stash on first use, so the second mount of a figure — the
+    // presented copy — would get nothing.
+    const bridge = createFigureBridge()
+    bridge.applyBinary('f1', 'image_b64', { geom: 'g' }, new Uint8Array([7, 8]))
+
+    const first = fakeIframe('first')
+    bridge.registerIframe('f1', first.el)
+    bridge.replay('f1')
+
+    const second = fakeIframe('second')
+    bridge.replay('f1', second.el)
+
+    for (const frame of [first, second]) {
+      const msg = frame.posted.at(-1)!.message
+      assert.equal(msg.type, 'awi_state_binary')
+      assert.deepEqual([...msg.buffer], [7, 8], 'replayed into a detached buffer')
+    }
+  })
+
+  test('replay serves the TARGET, not whichever mount holds the registry slot', () => {
+    // The blank-presented-deck bug. Two mounts share a figId; the map holds one.
+    // A freshly-loaded frame passes itself and must be the one served.
+    const bridge = createFigureBridge()
+    bridge.applyState('f1', 'k', 'v')
+
+    const winner = fakeIframe('winner')
+    const loader = fakeIframe('loader')
+    bridge.registerIframe('f1', winner.el)     // last registration wins the map
+    bridge.replay('f1', loader.el)             // ...but THIS frame just loaded
+
+    assert.equal(loader.posted.length, 1)
+    assert.equal(winner.posted.length, 0, 'state went to the sibling mount')
+  })
+})
+
+describe('registry and eviction', () => {
+  test('registering null deregisters', () => {
+    const bridge = createFigureBridge()
+    const frame = fakeIframe()
+    bridge.registerIframe('f1', frame.el)
+    bridge.registerIframe('f1', null)
+    assert.equal(bridge.iframes.current.has('f1'), false)
+  })
+
+  test('evict drops every trace of a figure', () => {
+    // Without this, a long report-editing session grows the maps forever: each
+    // re-render of a cell mints a new figId and the old one's pixels stay.
+    const bridge = createFigureBridge()
+    const frame = fakeIframe()
+    bridge.registerIframe('f1', frame.el)
+    bridge.applyState('f1', 'k', 'v')
+    bridge.applyBinary('f1', 'image_b64', { geom: 'g' }, new Uint8Array([1]))
+
+    bridge.evict('f1')
+
+    assert.equal(bridge.states.current.has('f1'), false)
+    assert.equal(bridge.binaryStates.current.has('f1'), false)
+    assert.equal(bridge.iframes.current.has('f1'), false)
+  })
+
+  test('replaying an unmounted figure is a no-op, not a throw', () => {
+    const bridge = createFigureBridge()
+    bridge.applyState('f1', 'k', 'v')
+    bridge.replay('f1')
+  })
+
+  test('dump reports retained counts per figure', () => {
+    const bridge = createFigureBridge()
+    const frame = fakeIframe()
+    bridge.registerIframe('f1', frame.el)
+    bridge.applyState('f1', 'k', 'v')
+    bridge.applyBinary('f1', 'image_b64', { geom: 'g' }, new Uint8Array([1]))
+
+    const row = bridge.dump().find(r => r.figId === 'f1')!
+    assert.equal(row.jsonKeys, 1)
+    assert.equal(row.binaryKeys, 1)
+    assert.equal(row.binaryKeyNames, 'g::image_b64')
+  })
+
+  test('dump includes figures with retained state but no mounted frame', () => {
+    // The diagnostic's whole job: telling "never arrived" from "arrived, not
+    // mounted". A figure missing from the dump would be indistinguishable.
+    const bridge = createFigureBridge()
+    bridge.applyState('ghost', 'k', 'v')
+    const row = bridge.dump().find(r => r.figId === 'ghost')!
+    assert.equal(row.registeredIn, 'NONE')
+  })
+})