From 0ee0422ebf235d0cf244d9e9f52bfb1674a899e2 Mon Sep 17 00:00:00 2001
From: Hannes Hertach <hhertach@adobe.com>
Date: Fri, 24 Jul 2026 10:29:56 +0200
Subject: [PATCH 1/6] fix(ew): rework canvas selection-toolbar visibility
 around an explicit active surface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The toolbar's visibility was derived from the doc view's `view.hasFocus()` while
that same value was faked to keep collab awareness working in WYSIWYG mode — a
self-contradiction that made the toolbar flicker, drop out, or fail to appear
(especially on the WYSIWYG side of split view).

Introduce a single ToolbarController that owns visibility, derived once per frame
from an explicit active surface ('doc' | 'wysiwyg') plus selection/mode — never
from focus. Editors emit intent; nothing else shows/hides the toolbar.

Key fixes:
- Null `cursor-move` (a da-nx per-block blur) is awareness-only, no longer hides
  the toolbar — the dominant drop-out.
- Detect focus entering the cross-origin iframe via `window` blur + shadow-piercing
  active element, since the iframe's own focus events don't fire and da-nx sends no
  message when a click doesn't change the block selection (e.g. end of a line).
- The focus lie is scoped to mirror dispatches (collab awareness only) and never
  read by the visibility layer.
- Coalesce visibility updates to one requestAnimationFrame render.

Design and investigation notes in docs/canvas-toolbar-architecture.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 blocks/canvas/canvas.js                       |   2 +
 blocks/canvas/editor-utils/editor-utils.js    |  27 +-
 .../canvas/editor-utils/selection-toolbar.js  |  47 +--
 .../canvas/editor-utils/toolbar-controller.js | 195 ++++++++++++
 blocks/canvas/ew-editor-doc/ew-editor-doc.js  |  31 +-
 .../ew-editor-wysiwyg/ew-editor-wysiwyg.js    |  19 +-
 .../ew-editor-wysiwyg/utils/handlers.js       |  60 ++--
 .../ew-selection-toolbar.js                   |  35 +--
 docs/canvas-toolbar-architecture.md           | 277 ++++++++++++++++++
 9 files changed, 590 insertions(+), 103 deletions(-)
 create mode 100644 blocks/canvas/editor-utils/toolbar-controller.js
 create mode 100644 docs/canvas-toolbar-architecture.md

diff --git a/blocks/canvas/canvas.js b/blocks/canvas/canvas.js
index 0e7414c53..3ee948d37 100644
--- a/blocks/canvas/canvas.js
+++ b/blocks/canvas/canvas.js
@@ -6,6 +6,7 @@ import {
   persistCanvasEditorView,
 } from './utils/view.js';
 import { shouldAutoOpenAfterPanel } from './utils/panel.js';
+import { toolbarController } from './editor-utils/toolbar-controller.js';
 import './ew-canvas-header/ew-canvas-header.js';
 import './ew-editor-doc/ew-editor-doc.js';
 import './ew-editor-wysiwyg/ew-editor-wysiwyg.js';
@@ -33,6 +34,7 @@ function buildCanvasDocPath(state) {
 
 function notifyCanvasEditorActive(mountRoot, view) {
   const v = normalizeCanvasEditorView(view);
+  toolbarController.setEditorMode(v);
   mountRoot.dispatchEvent(new CustomEvent('nx-canvas-editor-active', {
     bubbles: false,
     detail: { view: v },
diff --git a/blocks/canvas/editor-utils/editor-utils.js b/blocks/canvas/editor-utils/editor-utils.js
index 42bf61e5b..117282608 100644
--- a/blocks/canvas/editor-utils/editor-utils.js
+++ b/blocks/canvas/editor-utils/editor-utils.js
@@ -2,11 +2,31 @@ import { TextSelection } from 'da-y-wrapper';
 import prose2aem from '../../shared/prose2aem.js';
 import { getNx } from '../../../scripts/utils.js';
 import { daFetch, fetchDaConfigs, getFirstSheet } from '../../shared/utils.js';
-import { getSelectionToolbar } from './selection-toolbar.js';
+import { toolbarController } from './toolbar-controller.js';
 import { MESSAGE_TYPES } from '../utils/quick-edit-messages.js';
 
 const { DA_CONTENT } = await import(`${getNx()}/utils/utils.js`);
 
+/**
+ * Dispatch a mirror transaction while temporarily making `view.hasFocus()` return
+ * true, then restore it. y-prosemirror's cursor plugin broadcasts this user's
+ * cursor to collaborators only while the view "has focus"; in WYSIWYG mode the
+ * iframe owns DOM focus, so without this the local cursor would be cleared on
+ * every mirrored edit. Scoped to the dispatch so nothing else ever reads the lie —
+ * toolbar visibility is derived from the active surface, not from focus.
+ */
+export function dispatchWithFakeFocus(view, tr) {
+  const hadOwn = Object.hasOwn(view, 'hasFocus');
+  const prev = hadOwn ? view.hasFocus : undefined;
+  view.hasFocus = () => true;
+  try {
+    view.dispatch(tr);
+  } finally {
+    if (hadOwn) view.hasFocus = prev;
+    else delete view.hasFocus;
+  }
+}
+
 // --- state.js ---
 
 function findInsertedRange(oldText, newText) {
@@ -59,11 +79,10 @@ export function updateState(data, ctx) {
   tr.setSelection(TextSelection.create(tr.doc, restoredFrom, restoredTo));
 
   ctx.suppressRerender = true;
-  view.dispatch(tr);
+  dispatchWithFakeFocus(view, tr);
   ctx.suppressRerender = false;
 
-  const tb = getSelectionToolbar();
-  if (tb.open && !tb.isInteracting) tb.requestUpdate();
+  toolbarController.refresh();
 
   // Sync the updated node (with marks applied) back to the portal's mini editor.
   // Without this, the portal's editor retains the plain-text version, so the next
diff --git a/blocks/canvas/editor-utils/selection-toolbar.js b/blocks/canvas/editor-utils/selection-toolbar.js
index 5cf1da548..2c725f136 100644
--- a/blocks/canvas/editor-utils/selection-toolbar.js
+++ b/blocks/canvas/editor-utils/selection-toolbar.js
@@ -1,5 +1,6 @@
 /* eslint-disable import/no-unresolved -- importmap */
 import { Plugin, PluginKey, NodeSelection } from 'da-y-wrapper';
+import { toolbarController } from './toolbar-controller.js';
 
 const NON_TEXT_NODES = new Set(['table']);
 
@@ -11,42 +12,31 @@ export const NX_QUICK_EDIT_CLEAR_IFRAME_SELECTION_ORIGIN_META = 'nxClearQuickEdi
 
 const selectionToolbarOriginKey = new PluginKey('nxSelectionToolbarOrigin');
 
-function getSelectionOriginFromIframe(state) {
+export function getSelectionOriginFromIframe(state) {
   return selectionToolbarOriginKey.getState(state)?.fromIframe ?? false;
 }
 
-let toolbar;
-let componentLoaded;
-
 export function getSelectionToolbar() {
-  if (toolbar) return toolbar;
-  componentLoaded ??= import('../ew-selection-toolbar/ew-selection-toolbar.js');
-  toolbar = document.createElement('ew-selection-toolbar');
-  document.body.append(toolbar);
-  return toolbar;
+  return toolbarController.ensureToolbar();
 }
 
 export function setSelectionToolbarCtx({ org = null, site = null, sourceUrl = null } = {}) {
-  const tb = getSelectionToolbar();
+  const tb = toolbarController.ensureToolbar();
   tb.org = org;
   tb.site = site;
   tb.sourceUrl = sourceUrl;
 }
 
-export function hideSelectionToolbar() {
-  toolbar?.hide?.();
-}
-
 export function openLinkDialog(view) {
-  getSelectionToolbar().openLinkDialog(view);
+  toolbarController.ensureToolbar().openLinkDialog(view);
 }
 
 export function openAltDialog() {
-  getSelectionToolbar().openAltDialog();
+  toolbarController.ensureToolbar().openAltDialog();
 }
 
 export function triggerAddImage() {
-  getSelectionToolbar().triggerAddImage();
+  toolbarController.ensureToolbar().triggerAddImage();
 }
 
 function isNonTextSelection({ selection }) {
@@ -54,19 +44,6 @@ function isNonTextSelection({ selection }) {
     && NON_TEXT_NODES.has(selection.node.type.name);
 }
 
-function syncToolbar(view) {
-  if (!view) return;
-  const tb = getSelectionToolbar();
-  if (tb.linkDialogOpen || tb.altDialogOpen || tb.isInteracting) return;
-  if (isNonTextSelection(view.state)) {
-    hideSelectionToolbar();
-    return;
-  }
-  if (!view.hasFocus()) return;
-  tb.view = view;
-  tb.show();
-}
-
 export function createSelectionToolbarPlugin() {
   return new Plugin({
     key: selectionToolbarOriginKey,
@@ -84,14 +61,14 @@ export function createSelectionToolbarPlugin() {
     view() {
       return {
         update(view) {
-          const header = document.querySelector('ew-canvas-header');
-          const ev = header?.editorView;
-          if (ev !== 'content' && ev !== 'split') return;
+          // Iframe-origin dispatches are owned by the wysiwyg handlers; the doc
+          // plugin only reports the *doc* selection, and never claims the surface
+          // (activation comes from real focus — see toolbar-controller.js).
           if (getSelectionOriginFromIframe(view.state)) return;
-          syncToolbar(view);
+          toolbarController.setDocSelection({ showable: !isNonTextSelection(view.state) });
         },
         destroy() {
-          hideSelectionToolbar();
+          toolbarController.reset();
         },
       };
     },
diff --git a/blocks/canvas/editor-utils/toolbar-controller.js b/blocks/canvas/editor-utils/toolbar-controller.js
new file mode 100644
index 000000000..24a70f527
--- /dev/null
+++ b/blocks/canvas/editor-utils/toolbar-controller.js
@@ -0,0 +1,195 @@
+/**
+ * Single owner of the selection-toolbar's visibility across the canvas doc editor
+ * and the WYSIWYG iframe. See docs/canvas-toolbar-architecture.md.
+ *
+ * Nothing outside this module shows, hides, or positions the toolbar. Callers emit
+ * intent (activate / deactivate / selection / editor-mode) and this module derives
+ * visibility once per animation frame from an explicit "active surface" — never
+ * from `view.hasFocus()`, which lies while the user edits in the iframe.
+ */
+
+let toolbarEl;
+let toolbarLoading;
+let pointerdownInstalled = false;
+let windowBlurInstalled = false;
+
+const state = {
+  activeSurface: null, // 'doc' | 'wysiwyg' | null
+  docView: null, // the single ProseMirror view — always the command target
+  iframeEl: null, // for outside-click hit-testing
+  showable: false, // current selection is one the toolbar serves
+  editorMode: 'layout', // 'layout' | 'content' | 'split'
+};
+
+function ensureToolbar() {
+  if (toolbarEl) return toolbarEl;
+  toolbarEl = document.createElement('ew-selection-toolbar');
+  document.body.append(toolbarEl);
+  // The element definition loads lazily; re-render once it upgrades so a render
+  // scheduled before the module resolved takes effect.
+  toolbarLoading ??= import('../ew-selection-toolbar/ew-selection-toolbar.js')
+    // eslint-disable-next-line no-use-before-define -- mutually recursive with render
+    .then(() => scheduleRender());
+  return toolbarEl;
+}
+
+function editorModeAllows(surface) {
+  if (surface === 'doc') return state.editorMode === 'content' || state.editorMode === 'split';
+  if (surface === 'wysiwyg') return state.editorMode === 'layout' || state.editorMode === 'split';
+  return false;
+}
+
+/** The one visibility predicate. Interaction state is pulled from the element so
+ * a dialog / picker / menu is the single source of truth for "is interacting". */
+function shouldShow(tb) {
+  if (tb.linkDialogOpen || tb.altDialogOpen || tb.isInteracting) return false;
+  return state.activeSurface !== null
+    && state.showable
+    && editorModeAllows(state.activeSurface);
+}
+
+let renderQueued = false;
+function render() {
+  const tb = ensureToolbar();
+  // Element not upgraded yet; ensureToolbar re-renders when its module resolves.
+  if (typeof tb.show !== 'function') return;
+  // Only assign a known view; never clobber with null (teardown just hides, and a
+  // fresh view arrives via setDocView on the next load).
+  if (state.docView) tb.view = state.docView;
+  if (shouldShow(tb)) {
+    tb.show();
+  } else if (!tb.linkDialogOpen && !tb.altDialogOpen && !tb.isInteracting) {
+    tb.hide();
+  }
+}
+
+function scheduleRender() {
+  if (renderQueued) return;
+  renderQueued = true;
+  requestAnimationFrame(() => {
+    renderQueued = false;
+    render();
+  });
+}
+
+/** Pierce shadow roots to find the truly focused element. `document.activeElement`
+ * stops at a shadow host, so a focused iframe nested in a shadow root reports the
+ * host, not the iframe. */
+function deepActiveElement() {
+  let el = document.activeElement;
+  while (el?.shadowRoot?.activeElement) el = el.shadowRoot.activeElement;
+  return el;
+}
+
+/** Detect focus entering the wysiwyg iframe. The iframe element's own focus event
+ * is unreliable for cross-origin frames, and da-nx sends no message when a click
+ * doesn't change the block selection (e.g. clicking where the caret already sits).
+ * When focus moves into an iframe the parent window blurs and the (deep) active
+ * element becomes that iframe — a robust, message-independent signal. */
+function installIframeFocusDetection() {
+  if (windowBlurInstalled) return;
+  windowBlurInstalled = true;
+  window.addEventListener('blur', () => {
+    setTimeout(() => {
+      if (state.iframeEl && deepActiveElement() === state.iframeEl) {
+        // Entering an editable pane; assume showable so the toolbar appears even
+        // when no positional message follows. A later node-select (e.g. a table)
+        // refines it.
+        state.activeSurface = 'wysiwyg';
+        state.showable = true;
+        scheduleRender();
+      }
+    }, 0);
+  });
+}
+
+function installOutsidePointerdown() {
+  if (pointerdownInstalled) return;
+  pointerdownInstalled = true;
+  document.addEventListener('pointerdown', (e) => {
+    if (state.activeSurface === null) return;
+    const path = e.composedPath();
+    if (toolbarEl && path.includes(toolbarEl)) return;
+    if (state.docView?.dom && path.includes(state.docView.dom)) return;
+    if (state.iframeEl && path.includes(state.iframeEl)) return;
+    // A real pointerdown in the parent document outside every editing surface —
+    // the user is leaving. (Clicks inside the cross-origin iframe never reach here,
+    // and are handled by the iframe's own blur.)
+    state.activeSurface = null;
+    scheduleRender();
+  });
+}
+
+export const toolbarController = {
+  ensureToolbar,
+
+  /** Register the doc editor's view (the command target). */
+  setDocView(view) {
+    state.docView = view ?? null;
+    installOutsidePointerdown();
+    scheduleRender();
+  },
+
+  setIframe(iframeEl) {
+    state.iframeEl = iframeEl ?? null;
+    if (iframeEl) installIframeFocusDetection();
+  },
+
+  setEditorMode(mode) {
+    if (state.editorMode === mode) return;
+    state.editorMode = mode;
+    scheduleRender();
+  },
+
+  /** The user is now editing in `surface` (driven by real focus / positional intent). */
+  activate(surface, { iframeEl } = {}) {
+    if (surface !== 'doc' && surface !== 'wysiwyg') return;
+    if (iframeEl !== undefined) state.iframeEl = iframeEl;
+    state.activeSurface = surface;
+    installOutsidePointerdown();
+    scheduleRender();
+  },
+
+  /** Ownership-guarded: only the surface that currently owns the toolbar may
+   * deactivate it, so a late blur from one editor can't wipe the other. */
+  deactivate(surface) {
+    if (surface && state.activeSurface !== surface) return;
+    state.activeSurface = null;
+    scheduleRender();
+  },
+
+  /** Doc selection changed. Never claims the surface — a background/collab/mirror
+   * dispatch must not show the toolbar on a doc the user isn't editing. */
+  setDocSelection({ showable }) {
+    if (state.activeSurface === 'wysiwyg') return;
+    state.showable = showable;
+    scheduleRender();
+  },
+
+  /** A positional message from the iframe: the user is editing there. */
+  setWysiwygSelection({ showable }) {
+    state.activeSurface = 'wysiwyg';
+    state.showable = showable;
+    installOutsidePointerdown();
+    scheduleRender();
+  },
+
+  /** Re-query the toolbar's command/visibility state (e.g. after a command runs
+   * or a dialog/picker closes) without changing surface. */
+  refresh() {
+    scheduleRender();
+  },
+
+  /** After a toolbar command / dialog close — return focus to the active surface. */
+  restoreFocus() {
+    if (state.activeSurface === 'doc') state.docView?.focus();
+    // wysiwyg: focus never left the iframe (toolbar suppresses it via mousedown).
+  },
+
+  reset() {
+    state.activeSurface = null;
+    state.showable = false;
+    state.docView = null;
+    scheduleRender();
+  },
+};
diff --git a/blocks/canvas/ew-editor-doc/ew-editor-doc.js b/blocks/canvas/ew-editor-doc/ew-editor-doc.js
index 7eed6e97f..c9ed69d19 100644
--- a/blocks/canvas/ew-editor-doc/ew-editor-doc.js
+++ b/blocks/canvas/ew-editor-doc/ew-editor-doc.js
@@ -25,7 +25,8 @@ import { createTrackingPlugin } from '../editor-utils/prose-diff.js';
 import { resolveEditorDocSession } from './utils/load-editor-doc.js';
 import { afterNextPaint, ensureProseMountedInShadow } from './utils/shadow-mount.js';
 import { teardownEditorDocResources } from './utils/teardown.js';
-import { hideSelectionToolbar, setSelectionToolbarCtx } from '../editor-utils/selection-toolbar.js';
+import { setSelectionToolbarCtx } from '../editor-utils/selection-toolbar.js';
+import { toolbarController } from '../editor-utils/toolbar-controller.js';
 import { createExtensionsBridgePlugin } from '../editor-utils/extensions-bridge.js';
 import { MESSAGE_TYPES } from '../utils/quick-edit-messages.js';
 
@@ -47,6 +48,7 @@ export class EwEditorDoc extends LitElement {
       this.quickEditPort = undefined;
       this._teardown();
       setSelectionToolbarCtx();
+      toolbarController.reset();
       this._error = undefined;
       this._lastDocBlockIndex = undefined;
       this._lastDocSelKey = undefined;
@@ -178,6 +180,28 @@ export class EwEditorDoc extends LitElement {
     wireQuickEditControllerPort(this._controllerCtx);
   }
 
+  _wireProseFocus(view, proseEl) {
+    this._unwireProseFocus?.();
+    const onFocusIn = () => toolbarController.activate('doc');
+    const onFocusOut = () => {
+      // Defer so focus can settle. If it landed on the toolbar (button/dialog),
+      // stay active; otherwise the user left the doc surface.
+      setTimeout(() => {
+        const tb = toolbarController.ensureToolbar();
+        const active = document.activeElement;
+        if (active && (active === tb || tb.contains(active))) return;
+        toolbarController.deactivate('doc');
+      }, 0);
+    };
+    proseEl.addEventListener('focusin', onFocusIn);
+    proseEl.addEventListener('focusout', onFocusOut);
+    this._unwireProseFocus = () => {
+      proseEl.removeEventListener('focusin', onFocusIn);
+      proseEl.removeEventListener('focusout', onFocusOut);
+      this._unwireProseFocus = undefined;
+    };
+  }
+
   _setupAwareness(wsProvider) {
     if (this._awarenessOff) {
       this._awarenessOff();
@@ -198,6 +222,7 @@ export class EwEditorDoc extends LitElement {
 
   _teardown() {
     this._stopObservingUndoManager();
+    this._unwireProseFocus?.();
     const { wsProvider, view, proseEl } = this._proseContext ?? {};
     teardownEditorDocResources({
       clearPortHandler: () => this._clearControllerPort(),
@@ -263,6 +288,8 @@ export class EwEditorDoc extends LitElement {
 
       this._proseContext = { proseEl, wsProvider, view, ydoc, undoManager };
       setSelectionToolbarCtx({ org: this.ctx?.org, site: this.ctx?.repo, sourceUrl });
+      toolbarController.setDocView(view);
+      this._wireProseFocus(view, proseEl);
       this._setupAwareness(wsProvider);
       this._observeUndoManager(undoManager);
       this._emitHtmlChange();
@@ -283,7 +310,6 @@ export class EwEditorDoc extends LitElement {
     this._onCanvasEditorActive = (e) => {
       const view = e.detail?.view;
       this.hidden = view === 'layout';
-      hideSelectionToolbar();
     };
     this.parentElement?.addEventListener('nx-canvas-editor-active', this._onCanvasEditorActive);
     this._onWysiwygPortReady = (e) => {
@@ -315,6 +341,7 @@ export class EwEditorDoc extends LitElement {
     this._unsubscribeSelect?.();
     this._teardown();
     setSelectionToolbarCtx();
+    toolbarController.reset();
     super.disconnectedCallback();
   }
 
diff --git a/blocks/canvas/ew-editor-wysiwyg/ew-editor-wysiwyg.js b/blocks/canvas/ew-editor-wysiwyg/ew-editor-wysiwyg.js
index 8a7b2964f..4d28253d7 100644
--- a/blocks/canvas/ew-editor-wysiwyg/ew-editor-wysiwyg.js
+++ b/blocks/canvas/ew-editor-wysiwyg/ew-editor-wysiwyg.js
@@ -2,7 +2,7 @@ import { LitElement, html } from 'da-lit';
 import { getNx } from '../../../scripts/utils.js';
 import { getPreviewOrigin, fetchWysiwygCookie, fetchWysiwygBranch } from '../editor-utils/editor-utils.js';
 import { initIms as loadIms } from '../../shared/utils.js';
-import { hideSelectionToolbar } from '../editor-utils/selection-toolbar.js';
+import { toolbarController } from '../editor-utils/toolbar-controller.js';
 import { MESSAGE_TYPES } from '../utils/quick-edit-messages.js';
 
 const { loadStyle } = await import(`${getNx()}/utils/utils.js`);
@@ -100,7 +100,6 @@ export class EwEditorWysiwyg extends LitElement {
     const view = this._canvasActiveView ?? 'layout';
     const showWysiwyg = view === 'layout' || view === 'split';
     this.hidden = !showWysiwyg;
-    hideSelectionToolbar();
   }
 
   _resetCookieStateForCtxChange() {
@@ -189,6 +188,7 @@ export class EwEditorWysiwyg extends LitElement {
     const { org, repo, path } = this.ctx ?? {};
     if (!iframe?.contentWindow || !org || !repo || !path) return;
 
+    toolbarController.setIframe(iframe);
     this.removeAttribute(WYSIWYG_PORT_READY_ATTR);
     this._clearQuickEditRetry();
     this._syncCanvasVisibility();
@@ -205,8 +205,20 @@ export class EwEditorWysiwyg extends LitElement {
     this._scheduleQuickEditInitRetries(send);
   }
 
+  _onIframeFocus() {
+    const iframe = this.shadowRoot?.querySelector('iframe');
+    toolbarController.activate('wysiwyg', { iframeEl: iframe });
+  }
+
   _onIframeBlur() {
-    hideSelectionToolbar();
+    // Defer so focus can settle. If it landed on the toolbar (button/dialog), keep
+    // the wysiwyg surface active; otherwise the user has left the pane.
+    setTimeout(() => {
+      const tb = toolbarController.ensureToolbar();
+      const active = document.activeElement;
+      if (active && (active === tb || tb.contains(active))) return;
+      toolbarController.deactivate('wysiwyg');
+    }, 0);
   }
 
   render() {
@@ -228,6 +240,7 @@ export class EwEditorWysiwyg extends LitElement {
           allow="local-network-access"
           class="ew-editor-wysiwyg-iframe"
           @load=${this._onIframeLoad}
+          @focus=${this._onIframeFocus}
           @blur=${this._onIframeBlur}
         ></iframe>
       `;
diff --git a/blocks/canvas/ew-editor-wysiwyg/utils/handlers.js b/blocks/canvas/ew-editor-wysiwyg/utils/handlers.js
index da180e688..bc6187c67 100644
--- a/blocks/canvas/ew-editor-wysiwyg/utils/handlers.js
+++ b/blocks/canvas/ew-editor-wysiwyg/utils/handlers.js
@@ -1,10 +1,10 @@
 import { TextSelection, NodeSelection, yUndo, yRedo } from 'da-y-wrapper';
 import {
-  getSelectionToolbar,
   NX_QUICK_EDIT_IFRAME_SELECTION_META,
   NX_QUICK_EDIT_CLEAR_IFRAME_SELECTION_ORIGIN_META,
 } from '../../editor-utils/selection-toolbar.js';
-import { editorSelectChange } from '../../editor-utils/editor-utils.js';
+import { editorSelectChange, dispatchWithFakeFocus } from '../../editor-utils/editor-utils.js';
+import { toolbarController } from '../../editor-utils/toolbar-controller.js';
 import { getActiveBlockIndex } from '../../editor-utils/blocks.js';
 
 export function handleCursorMove({ cursorOffset, textCursorOffset }, ctx) {
@@ -12,10 +12,10 @@ export function handleCursorMove({ cursorOffset, textCursorOffset }, ctx) {
   if (!view || !wsProvider) return;
 
   if (cursorOffset == null || textCursorOffset == null) {
-    delete view.hasFocus;
+    // Per-block blur from the iframe — its documented purpose is clearing the
+    // remote cursor, NOT hiding the toolbar. The user is still in the pane while
+    // the iframe holds focus; toolbar deactivation comes from the iframe's blur.
     wsProvider.awareness.setLocalStateField('cursor', null);
-    const tb = getSelectionToolbar();
-    if (!tb.isInteracting && !tb.linkDialogOpen) tb.hide?.();
     return;
   }
 
@@ -29,8 +29,6 @@ export function handleCursorMove({ cursorOffset, textCursorOffset }, ctx) {
       return;
     }
 
-    view.hasFocus = () => true;
-
     const { tr } = state;
     tr.setSelection(TextSelection.create(state.doc, position));
 
@@ -58,13 +56,9 @@ export function handleCursorMove({ cursorOffset, textCursorOffset }, ctx) {
     }
 
     ctx.suppressRerender = true;
-    view.dispatch(tr.scrollIntoView());
+    dispatchWithFakeFocus(view, tr.scrollIntoView());
     ctx.suppressRerender = false;
-    const tb = getSelectionToolbar();
-    if (!tb.linkDialogOpen && !tb.isInteracting) {
-      tb.view = view;
-      tb.show();
-    }
+    toolbarController.setWysiwygSelection({ showable: true });
     const blockIndex = getActiveBlockIndex(view);
     if (blockIndex !== ctx.lastBlockIndex) {
       ctx.lastBlockIndex = blockIndex;
@@ -80,19 +74,11 @@ export function handleUndoRedo(data, ctx) {
   const { action } = data;
   const view = ctx?.view;
   if (!view) return;
-  // hasFocus may be overridden to () => true by the cursor-move hack; temporarily
-  // restore the prototype so ProseMirror skips _isDomSelectionInView during the
-  // undo dispatch (the editor may be in a hidden or unfocused state).
-  const hadHasFocus = Object.hasOwn(view, 'hasFocus');
-  delete view.hasFocus;
-
   if (action === 'undo') {
     yUndo(view.state);
   } else if (action === 'redo') {
     yRedo(view.state);
   }
-
-  if (hadHasFocus) view.hasFocus = () => true;
 }
 
 export function handleNewVersion() {
@@ -114,10 +100,9 @@ export function handleStoredMarks({ marks }, ctx) {
     const { tr } = state;
     tr.setStoredMarks(parsedMarks);
     ctx.suppressRerender = true;
-    view.dispatch(tr);
+    dispatchWithFakeFocus(view, tr);
     ctx.suppressRerender = false;
-    const tb = getSelectionToolbar();
-    if (tb.open && !tb.isInteracting) tb.requestUpdate();
+    toolbarController.refresh();
   } catch (e) {
     // eslint-disable-next-line no-console
     console.error('[quick-edit-controller] handleStoredMarks failed', e?.message);
@@ -135,7 +120,7 @@ export function handleSelectionChange({ anchor, head }, ctx, { fromQuickEditIfra
     tr.setSelection(TextSelection.create(state.doc, a, h));
     if (fromQuickEditIframe) tr.setMeta(NX_QUICK_EDIT_IFRAME_SELECTION_META, true);
     ctx.suppressRerender = true;
-    view.dispatch(tr);
+    dispatchWithFakeFocus(view, tr);
     ctx.suppressRerender = false;
     return true;
   } catch (e) {
@@ -145,34 +130,29 @@ export function handleSelectionChange({ anchor, head }, ctx, { fromQuickEditIfra
   }
 }
 
-function showToolbarInIFrame(ctx) {
-  const { view } = ctx;
-  const tb = getSelectionToolbar();
-  tb.view = view;
-  tb.show();
-}
-
 /** PostMessage `selection-change` from wysiwyg iframe: sync PM selection and toolbar. */
 export function handleIframeSelectionChange(data, ctx) {
   const { anchor, head } = data;
+  const { view } = ctx;
   if (anchor === head) {
-    const tb = getSelectionToolbar();
-    if (tb.isInteracting) return;
-    const { view } = ctx;
+    // Collapsed to a caret: clear the iframe-origin flag so subsequent doc
+    // transactions are read normally. Still a caret in the iframe, so the toolbar
+    // stays active/showable.
     if (view) {
       const tr = view.state.tr
         .setMeta(NX_QUICK_EDIT_CLEAR_IFRAME_SELECTION_ORIGIN_META, true)
         .setMeta('addToHistory', false);
       ctx.suppressRerender = true;
-      view.dispatch(tr);
+      dispatchWithFakeFocus(view, tr);
       ctx.suppressRerender = false;
     }
+    toolbarController.setWysiwygSelection({ showable: true });
     return;
   }
 
   if (!handleSelectionChange(data, ctx, { fromQuickEditIframe: true })) return;
 
-  showToolbarInIFrame(ctx);
+  toolbarController.setWysiwygSelection({ showable: true });
 }
 
 function srcFileName(src) {
@@ -234,7 +214,7 @@ export function handleNodeSelect({ node }, ctx) {
         .setSelection(TextSelection.near(state.doc.resolve(state.selection.from), 1))
         .setMeta('addToHistory', false);
       ctx.suppressRerender = true;
-      view.dispatch(tr);
+      dispatchWithFakeFocus(view, tr);
       ctx.suppressRerender = false;
       return;
     }
@@ -245,8 +225,10 @@ export function handleNodeSelect({ node }, ctx) {
       .scrollIntoView()
       .setMeta('addToHistory', false);
     ctx.suppressRerender = true;
-    view.dispatch(tr);
+    dispatchWithFakeFocus(view, tr);
     ctx.suppressRerender = false;
+    // Tables have their own UI; the toolbar hides for them. Images keep it.
+    toolbarController.setWysiwygSelection({ showable: node.anchorType !== 'table' });
   } catch (e) {
     // eslint-disable-next-line no-console
     console.error('[quick-edit-controller] handleNodeSelect failed', e?.message);
diff --git a/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.js b/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.js
index 7cc14f7f1..2e051dbee 100644
--- a/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.js
+++ b/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.js
@@ -6,6 +6,7 @@ import {
   getLinkInfoInSelection,
   applyLink,
 } from '../editor-utils/command-helpers.js';
+import { toolbarController } from '../editor-utils/toolbar-controller.js';
 
 const { loadStyle } = await import(`${getNx()}/utils/utils.js`);
 
@@ -54,20 +55,6 @@ class EwSelectionToolbar extends LitElement {
   connectedCallback() {
     super.connectedCallback();
     this.shadowRoot.adoptedStyleSheets = [styles];
-    this._onOutsidePointerDown = (e) => {
-      if (!this.open) return;
-      const path = e.composedPath();
-      if (path.includes(this)) return;
-      const editorDom = this.view?.dom;
-      if (editorDom && path.includes(editorDom)) return;
-      this.hide();
-    };
-    document.addEventListener('pointerdown', this._onOutsidePointerDown);
-  }
-
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    document.removeEventListener('pointerdown', this._onOutsidePointerDown);
   }
 
   get _picker() { return this.shadowRoot?.querySelector('nx-picker'); }
@@ -124,7 +111,8 @@ class EwSelectionToolbar extends LitElement {
     if (cmd) {
       cmd.apply(this.view);
       this.requestUpdate();
-      this.view.focus();
+      toolbarController.restoreFocus();
+      toolbarController.refresh();
     }
   }
 
@@ -162,7 +150,10 @@ class EwSelectionToolbar extends LitElement {
     if (!id) return;
     COMMAND_BY_ID.get(id)?.apply(this.view);
     this.requestUpdate();
-    if (!this._linkDialogOpen && !this._altDialogOpen) this.view.focus();
+    if (!this._linkDialogOpen && !this._altDialogOpen) {
+      toolbarController.restoreFocus();
+      toolbarController.refresh();
+    }
   }
 
   /* ---- Link dialog ---- */
@@ -185,14 +176,16 @@ class EwSelectionToolbar extends LitElement {
 
   _closeLinkDialog() {
     this._linkDialogOpen = false;
-    this.view?.focus();
+    toolbarController.restoreFocus();
+    toolbarController.refresh();
   }
 
   _onLinkDialogSubmit(e) {
     const { href, text } = e.detail;
     this._closeLinkDialog();
     applyLink(this.view, { href, text });
-    this.view.focus();
+    toolbarController.restoreFocus();
+    toolbarController.refresh();
   }
 
   get linkDialogOpen() { return this._linkDialogOpen ?? false; }
@@ -208,7 +201,8 @@ class EwSelectionToolbar extends LitElement {
 
   _closeAltDialog() {
     this._altDialogOpen = false;
-    this.view?.focus();
+    toolbarController.restoreFocus();
+    toolbarController.refresh();
   }
 
   _onAltDialogSubmit(e) {
@@ -217,7 +211,8 @@ class EwSelectionToolbar extends LitElement {
     const { pos } = this.view.state.selection.$anchor;
     this._closeAltDialog();
     this.view.dispatch(this.view.state.tr.setNodeAttribute(pos, 'alt', alt));
-    this.view.focus();
+    toolbarController.restoreFocus();
+    toolbarController.refresh();
   }
 
   get altDialogOpen() { return this._altDialogOpen ?? false; }
diff --git a/docs/canvas-toolbar-architecture.md b/docs/canvas-toolbar-architecture.md
new file mode 100644
index 000000000..725888702
--- /dev/null
+++ b/docs/canvas-toolbar-architecture.md
@@ -0,0 +1,277 @@
+# Canvas selection-toolbar architecture
+
+Status: design (pre-implementation)
+Scope: the shared selection toolbar across the canvas doc editor and the WYSIWYG
+iframe, in all three view modes (`layout`, `content`, `split`).
+
+This document is the **authority contract** for a redesign. It exists because the
+current implementation, and a prior refactor attempt (PR #1018, closed), both
+suffer from the toolbar intermittently failing to appear — most visibly on the
+WYSIWYG (layout) side of split view. The contract below is grounded in three
+investigation spikes whose findings are summarised at the end.
+
+---
+
+## 1. Background: what exists today
+
+- There is **one** ProseMirror view — the doc editor's (`ew-editor-doc`). It is
+  always the command target. The WYSIWYG pane is a cross-origin iframe (the da-nx
+  "quick-edit" preview) running its own editors that mirror state to the doc view
+  over a `MessageChannel`. Keeping the doc view as the single command target is
+  correct and is **retained** by this design.
+- The toolbar is a single global `<ew-selection-toolbar>` (`position: fixed`)
+  appended to `document.body`.
+- Toolbar visibility is currently written from ~6 places by **two competing
+  drivers**:
+  - the ProseMirror plugin in `editor-utils/selection-toolbar.js`, which gates on
+    `view.hasFocus()`; and
+  - the iframe message handlers in `ew-editor-wysiwyg/utils/handlers.js`, which
+    fake `view.hasFocus = () => true` and call `show()/hide()` directly.
+
+The core defect: visibility is derived from `view.hasFocus()` **while that same
+value is being faked**. The two ideas are mutually contradictory, so every fix
+on top of the current model spawns a new race.
+
+---
+
+## 2. Root causes (evidence-ranked)
+
+1. **Null `cursor-move` misused as "hide toolbar" (dominant).** da-nx sends a
+   `cursor-move` with no offsets as a **per-block blur** signal (v1 debounced
+   150ms; v2 immediate). Its documented meaning is *"clear the remote cursor"*
+   (`nx/utils/message-types.js`). da-live's `handleCursorMove` overloaded it to
+   also hide the toolbar. Because it is per-block, ordinary actions inside the
+   iframe (clicking between blocks, clicking a non-editable region, a block
+   re-rendering after an edit) fire it even though focus never left the iframe —
+   hiding the toolbar until the next real cursor move.
+2. **No coalescing.** A single range drag emits ~30 `selection-change` messages,
+   each triggering 1–2 visibility recomputes.
+3. **The `view.hasFocus()` lie leaks into visibility.** The fake focus is required
+   for collaboration (see §6) but must not participate in the toolbar decision.
+   In PR #1018 it still did — a mirror dispatch that ran the visibility plugin
+   under faked focus could claim the wrong active surface.
+4. **`document.activeElement` heuristics across the iframe boundary** are
+   timing- and browser-dependent (used by #1018's deferred blur handlers).
+
+Non-issue: a suspected "caret `selection-change` before `cursor-move`" ordering
+race on first click **did not reproduce** in the current da-nx build.
+
+---
+
+## 3. Key insight that drives the design
+
+**"Active surface = WYSIWYG" ⟺ focus is inside the iframe.** While the user clicks
+between blocks *inside* the iframe, focus stays in the frame — only da-nx's
+internal per-block editors change focus, which the parent never sees. The null
+`cursor-move` (a per-block blur) does **not** mean focus left the frame, which is
+exactly why it must not drive visibility.
+
+**How to detect it (corrected after testing).** The obvious signal — a `focus`/
+`blur` event on the `<iframe>` element — turned out to be unreliable: in practice
+those events did not fire at all for the cross-origin preview frame. The robust,
+message-independent signal is instead:
+
+- **`window` blur + deep active element.** When focus moves into an iframe the
+  parent window fires `blur` and the (shadow-piercing) active element becomes that
+  iframe. On `window` blur, if `deepActiveElement() === wysiwygIframe`, activate
+  the WYSIWYG surface. This fires even when da-nx sends no message — e.g. clicking
+  at the very end of a line, where the block's selection doesn't change, so no
+  `cursor-move` is emitted.
+- Positional `cursor-move` / `selection-change` remain a secondary activation
+  signal (they also carry the selection), but must not be the *only* one.
+- Deactivation comes from: doc `focusin` (switching to the doc surface), or a
+  pointerdown in the parent outside every surface. It must **not** depend on an
+  iframe blur event or the null `cursor-move`.
+
+---
+
+## 4. Target model: one owner
+
+Introduce a single module-level `ToolbarController`. It is the **only** code that
+shows/hides/positions the toolbar or sets its command target. Everything else
+emits typed events into it. It reduces events into state, derives visibility once
+per frame, and imperatively syncs the element.
+
+```
+events ──▶ reduce() ──▶ state ──▶ derive() ──▶ render() (coalesced 1×/frame)
+```
+
+### 4.1 State shape
+
+```
+{
+  activeSurface: 'doc' | 'wysiwyg' | null,
+  docView:       EditorView | null,         // command target
+  iframeEl:      HTMLIFrameElement | null,   // for outside-click hit-testing
+  showable:      boolean,                    // current selection is toolbar-supported
+  modal:         boolean,                    // a dialog / picker / menu is open
+  editorMode:    'layout' | 'content' | 'split',
+}
+```
+
+`showable` is `false` for selections the toolbar does not serve (e.g. a `table`
+node selection); `true` for text, caret, image, and ranges.
+
+### 4.2 The single visibility predicate
+
+```
+visible =
+     activeSurface !== null
+  && !modal
+  && showable
+  && editorModeAllows(activeSurface)
+
+editorModeAllows('doc')     = editorMode ∈ { content, split }
+editorModeAllows('wysiwyg') = editorMode ∈ { layout, split }
+```
+
+**`view.hasFocus()` appears nowhere in this predicate.** That is the property that
+distinguishes this design from every prior version.
+
+### 4.3 Event inventory (one emit-site each)
+
+| Event | Sole emitter | Effect |
+|---|---|---|
+| `activate('doc')` | `focusin` on doc PM dom | `activeSurface = 'doc'` |
+| `deactivate('doc')` | `focusout` on doc PM dom (focus not in toolbar) | if `activeSurface==='doc'` → `null` |
+| `setDocSelection({ showable })` | doc PM plugin `update` (skips iframe-origin txns) | update `showable`; **does not** change `activeSurface` |
+| `activate('wysiwyg')` | iframe element `focus` | `activeSurface = 'wysiwyg'` |
+| `deactivate('wysiwyg')` | iframe element `blur` (focus not in toolbar) | if `activeSurface==='wysiwyg'` → `null` |
+| `setWysiwygSelection({ showable })` | iframe `cursor-move` (positional), `selection-change`, `node-select` | update `showable` |
+| `setEditorMode(mode)` | header view-toggle handler (`canvas.js`) | update `editorMode` |
+| `setModal(bool)` | toolbar element (dialog/picker/menu open/close) | update `modal` |
+| `reset()` | ctx change / teardown | clear all, hide |
+
+Deliberately **not** an event: the null `cursor-move`. It performs an awareness
+clear only (`awareness.setLocalStateField('cursor', null)`) and never touches the
+controller.
+
+### 4.4 Authority / ordering rule
+
+Activation follows the browser focus model, which places focus in exactly one
+surface at a time. The only race is deactivation ordering, resolved by two rules
+already validated conceptually:
+
+1. **Ownership-guarded deactivation:** `deactivate(surface)` is a no-op unless
+   `activeSurface === surface`. So a late doc `focusout` cannot wipe an already
+   active WYSIWYG, regardless of whether iframe `focus` or doc `focusout` fires
+   first.
+2. **Deferred deactivation with a toolbar check:** run the deactivate on the next
+   task; if focus has landed on the toolbar (button/dialog), skip it. The toolbar
+   suppresses focus loss via `mousedown` `preventDefault`, so this is a safety net.
+
+Because activation is bound to real focus events (not to PM transactions), a
+background/collab/mirror dispatch can never claim a surface.
+
+### 4.5 Coalescing
+
+Every event marks state dirty and schedules one `render()` per frame
+(microtask or rAF). `render()` computes `derive()` from the current snapshot and
+applies show/hide + anchor exactly once. This collapses the ~30-message drag
+burst and any activate/deactivate churn within a frame, eliminating flicker.
+
+---
+
+## 5. Component responsibilities after the change
+
+- **`ToolbarController` (new, `editor-utils/`):** owns state, exposes the §4.3
+  intake methods, does coalesced render, drives the element. Replaces the
+  show/hide orchestration currently spread across files.
+- **`<ew-selection-toolbar>`:** presentation + command dispatch only. Commands
+  apply to `controller.docView`. Emits `setModal(true/false)` around its dialogs,
+  pickers, and menus. No focus logic, no surface logic, no outside-click logic of
+  its own beyond forwarding.
+- **PM plugin (`selection-toolbar.js`):** shrinks to emitting `setDocSelection`
+  (skipping iframe-origin transactions). Drops the `hasFocus` gate and the
+  `document.querySelector('ew-canvas-header')` read.
+- **`ew-editor-doc`:** wires `focusin`/`focusout` on the prose dom →
+  `activate('doc')` / deferred `deactivate('doc')`; calls `reset()` on ctx change.
+- **`ew-editor-wysiwyg`:** wires the iframe element's `focus`/`blur` →
+  `activate('wysiwyg')` / deferred `deactivate('wysiwyg')`.
+- **`handlers.js`:** positional `cursor-move` / `selection-change` / `node-select`
+  → `setWysiwygSelection`. Null `cursor-move` → awareness clear only. Keeps a
+  **scoped** `dispatchWithFakeFocus` around the mirror dispatches (see §6).
+- **`canvas.js`:** `setEditorMode(view)` on the header view toggle.
+
+---
+
+## 6. The focus lie is retained — but quarantined
+
+Collaboration depends on it. y-prosemirror's cursor plugin
+(`updateCursorInfo`, `plugins/cursor-plugin.js`) broadcasts *this* user's cursor
+to awareness **only when `view.hasFocus()` is true**, and clears it otherwise.
+da-live has no alternative outbound path (its `updateCursors`/`SET_CURSORS` is the
+*inbound* direction — rendering remote users' cursors into the iframe). While the
+user edits in the WYSIWYG pane, the doc view genuinely lacks DOM focus, so without
+the fake, collaborators would lose sight of this user's cursor.
+
+Resolution:
+
+- **Keep** a scoped helper that fakes focus only for the duration of a mirror
+  `view.dispatch(tr)` and restores it in a `finally` (as PR #1018's
+  `dispatchWithFakeFocus` did). This preserves outbound awareness.
+- **Guarantee** the visibility layer never reads `view.hasFocus()` (§4.2). Once
+  that holds, the scoped lie is harmless: it feeds the y-cursor plugin (intended)
+  and cannot influence the toolbar. Untangling these two consumers of the same
+  value is the crux of the fix.
+
+---
+
+## 7. Optional da-nx enhancement (not a blocker)
+
+A clean protocol would have da-nx emit an explicit, debounced pane-level
+`editable-focus: true | false` message, distinct from the awareness `cursor-move`.
+da-live could then drop even the iframe-element focus/blur inference. This design
+does **not** require it — the iframe-focus signal (§3) is sufficient to ship. File
+as a follow-up with the da-nx owner.
+
+---
+
+## 8. Migration path (incremental, each step shippable)
+
+1. Add `ToolbarController` and route existing `show()/hide()` calls through it as
+   passthrough (no behaviour change).
+2. Add `activeSurface` + the §4.2 predicate; move `editorMode` off the header DOM
+   query into `setEditorMode`.
+3. Flip the PM plugin and `handlers.js` to emit events; **stop hiding on null
+   `cursor-move`**; confine the focus lie to the scoped dispatch helper.
+4. Move activation to real focus events (doc prose focus/out, iframe focus/blur);
+   remove the `activeElement`-based outside logic.
+5. Add coalesced render.
+6. (Optional) surface-anchored toolbar positioning; da-nx `editable-focus`.
+
+---
+
+## 9. Verification (manual)
+
+Drive the real app in **split view**:
+
+- Click into the WYSIWYG pane as the first interaction → toolbar appears and
+  stays.
+- Click a non-editable region inside the preview → toolbar stays (no null-cursor
+  drop-out).
+- Select a range and drag → toolbar stays; no flicker.
+- Click a toolbar button → command applies, toolbar stays, focus returns to the
+  active surface.
+- Switch view modes → toolbar recomputes from the current selection rather than
+  hiding until the next selection change.
+- Second collaborator session → this user's cursor remains visible to them while
+  editing in the WYSIWYG pane (confirms the scoped focus lie still works).
+
+---
+
+## Appendix: spike findings
+
+- **Spike #1 (live logging, split view).** On first click into WYSIWYG,
+  `cursor-move` fires first and alone — no caret-`selection-change` race. Toolbar
+  drop-outs correlate exactly with null `cursor-move` fired while the iframe still
+  held focus. A single drag produced ~30 `selection-change` messages.
+  `view.hasFocus()` read `true` on nearly every plugin update (the lie).
+- **Spike #2 (da-nx source).** WYSIWYG is per-block micro-editors keyed by
+  `data-prose-index`. Null `cursor-move` is a per-block blur (v1 150ms debounce,
+  v2 immediate) whose documented purpose is clearing the remote cursor. No
+  explicit focus/blur message is sent to the parent.
+- **Spike #3 (y-prosemirror source).** `updateCursorInfo` gates the outbound
+  cursor broadcast on `view.hasFocus()`; da-live has no alternative path
+  (`extractCursors` reads remote `.ProseMirror-yjs-cursor` decorations — inbound
+  only). The lie is load-bearing for collaboration but cleanly scopable.

From 457196f345d19245e2bab0669858fe481fd7430e Mon Sep 17 00:00:00 2001
From: Hannes Hertach <hhertach@adobe.com>
Date: Fri, 24 Jul 2026 11:09:47 +0200
Subject: [PATCH 2/6] fix(ew): keep collab cursor broadcasting while editing in
 WYSIWYG pane
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

y-prosemirror's cursor plugin broadcasts this user's caret to collaborators
only while the doc view "has focus", and clears it on the next update once
focus is lost. Its updateCursorInfo is the plugin's view.update callback, so it
runs after every transaction. A focus lie scoped to a single mirror dispatch
therefore only survived one tick: the next unrelated update (a remote edit, the
iframe streaming into Yjs, or the redraw our own setLocalStateField triggers)
ran with the real hasFocus() === false and wiped the just-broadcast cursor. The
caret flashed to peers and vanished.

Gate the lie on the active surface instead: while activeSurface === 'wysiwyg'
the doc view reports focus, so the cursor keeps broadcasting for the whole time
the iframe owns editing (layout and split). When the user leaves, the real
check returns and the cursor is correctly cleared.

The lie makes selectionToDOM treat the doc view as owning the selection, but
that only writes a DOM selection range (no focus move). The one thing that would
steal focus is view.focus(), so neuter it while the iframe is active — no caller
(drop handler, command, restoreFocus) can pull focus off the iframe and revive
the toolbar-visibility bugs. dispatchWithFakeFocus is retained as a complement
for the instant before the surface flips.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 blocks/canvas/editor-utils/editor-utils.js    | 14 ++---
 .../canvas/editor-utils/toolbar-controller.js | 27 ++++++++++
 docs/canvas-toolbar-architecture.md           | 52 ++++++++++++++-----
 3 files changed, 74 insertions(+), 19 deletions(-)

diff --git a/blocks/canvas/editor-utils/editor-utils.js b/blocks/canvas/editor-utils/editor-utils.js
index 117282608..2c8dfc03d 100644
--- a/blocks/canvas/editor-utils/editor-utils.js
+++ b/blocks/canvas/editor-utils/editor-utils.js
@@ -8,12 +8,14 @@ import { MESSAGE_TYPES } from '../utils/quick-edit-messages.js';
 const { DA_CONTENT } = await import(`${getNx()}/utils/utils.js`);
 
 /**
- * Dispatch a mirror transaction while temporarily making `view.hasFocus()` return
- * true, then restore it. y-prosemirror's cursor plugin broadcasts this user's
- * cursor to collaborators only while the view "has focus"; in WYSIWYG mode the
- * iframe owns DOM focus, so without this the local cursor would be cleared on
- * every mirrored edit. Scoped to the dispatch so nothing else ever reads the lie —
- * toolbar visibility is derived from the active surface, not from focus.
+ * Dispatch a mirror transaction while forcing `view.hasFocus()` true for the
+ * duration, then restore it. y-prosemirror's cursor plugin broadcasts this user's
+ * cursor to collaborators only while the view "has focus". The toolbar controller
+ * already keeps `hasFocus` true whenever the wysiwyg surface is active, but a
+ * mirrored edit can land in the instant before the surface flips (the message is
+ * applied, then the surface is claimed) — this guarantees the very edit that moves
+ * the caret also broadcasts it. Toolbar visibility never reads focus; it derives
+ * from the active surface.
  */
 export function dispatchWithFakeFocus(view, tr) {
   const hadOwn = Object.hasOwn(view, 'hasFocus');
diff --git a/blocks/canvas/editor-utils/toolbar-controller.js b/blocks/canvas/editor-utils/toolbar-controller.js
index 24a70f527..857717759 100644
--- a/blocks/canvas/editor-utils/toolbar-controller.js
+++ b/blocks/canvas/editor-utils/toolbar-controller.js
@@ -103,6 +103,32 @@ function installIframeFocusDetection() {
   });
 }
 
+/**
+ * While the wysiwyg iframe owns editing, keep the doc view broadcasting this
+ * user's cursor to collaborators without ever letting real focus land on it.
+ *
+ * y-prosemirror's cursor plugin broadcasts the local cursor only while the view
+ * "has focus", and clears it on the next update once focus is lost — so a caret
+ * mirrored from the iframe would flash to peers and vanish. We lie about focus so
+ * the plugin keeps broadcasting; but `hasFocus` lying alone would let ProseMirror's
+ * `selectionToDOM` treat the doc editor as focused. That only writes a DOM
+ * selection range (harmless — it doesn't move focus), so the one thing left to
+ * guard is `view.focus()`, which really would steal focus from the iframe and
+ * bring back the toolbar-visibility bugs. Neuter it while wysiwyg is active.
+ */
+const focusGuardedViews = new WeakSet();
+function installSurfaceFocusGuards(view) {
+  if (focusGuardedViews.has(view)) return;
+  focusGuardedViews.add(view);
+  const realHasFocus = view.hasFocus.bind(view);
+  view.hasFocus = () => state.activeSurface === 'wysiwyg' || realHasFocus();
+  const realFocus = view.focus.bind(view);
+  view.focus = () => {
+    if (state.activeSurface === 'wysiwyg') return;
+    realFocus();
+  };
+}
+
 function installOutsidePointerdown() {
   if (pointerdownInstalled) return;
   pointerdownInstalled = true;
@@ -126,6 +152,7 @@ export const toolbarController = {
   /** Register the doc editor's view (the command target). */
   setDocView(view) {
     state.docView = view ?? null;
+    if (view) installSurfaceFocusGuards(view);
     installOutsidePointerdown();
     scheduleRender();
   },
diff --git a/docs/canvas-toolbar-architecture.md b/docs/canvas-toolbar-architecture.md
index 725888702..2782189af 100644
--- a/docs/canvas-toolbar-architecture.md
+++ b/docs/canvas-toolbar-architecture.md
@@ -176,7 +176,8 @@ burst and any activate/deactivate churn within a frame, eliminating flicker.
 
 - **`ToolbarController` (new, `editor-utils/`):** owns state, exposes the §4.3
   intake methods, does coalesced render, drives the element. Replaces the
-  show/hide orchestration currently spread across files.
+  show/hide orchestration currently spread across files. On `setDocView` it also
+  installs the surface-gated focus guards (§6) on the doc view.
 - **`<ew-selection-toolbar>`:** presentation + command dispatch only. Commands
   apply to `controller.docView`. Emits `setModal(true/false)` around its dialogs,
   pickers, and menus. No focus logic, no surface logic, no outside-click logic of
@@ -205,15 +206,38 @@ da-live has no alternative outbound path (its `updateCursors`/`SET_CURSORS` is t
 user edits in the WYSIWYG pane, the doc view genuinely lacks DOM focus, so without
 the fake, collaborators would lose sight of this user's cursor.
 
-Resolution:
-
-- **Keep** a scoped helper that fakes focus only for the duration of a mirror
-  `view.dispatch(tr)` and restores it in a `finally` (as PR #1018's
-  `dispatchWithFakeFocus` did). This preserves outbound awareness.
-- **Guarantee** the visibility layer never reads `view.hasFocus()` (§4.2). Once
-  that holds, the scoped lie is harmless: it feeds the y-cursor plugin (intended)
-  and cannot influence the toolbar. Untangling these two consumers of the same
-  value is the crux of the fix.
+A **scoped** lie (fake focus only for the duration of one mirror
+`view.dispatch(tr)`) is **not sufficient**, and this was found in testing.
+`updateCursorInfo` is the plugin's `view.update` callback — it runs after *every*
+transaction. The scoped dispatch broadcasts the cursor, but the next unrelated
+update (a remote peer's edit, the iframe streaming changes into Yjs, or the redraw
+transaction our own `setLocalStateField` triggers via awareness `'change'`) runs
+`updateCursorInfo` with the real `hasFocus() === false` and hits its *else* branch,
+which **clears** the just-broadcast cursor. Net effect: the cursor flashes to peers
+for one tick and vanishes.
+
+Resolution — a lie **gated on the active surface**, plus a focus guard:
+
+- **`installSurfaceFocusGuards(view)`** (in `toolbar-controller.js`, wired from
+  `setDocView`) overrides `view.hasFocus` to return `true` whenever
+  `state.activeSurface === 'wysiwyg'`, else the real check. This holds the lie for
+  the *whole* duration the iframe owns editing (layout **and** split), so no later
+  update can clear the cursor. When the user leaves, the surface goes to `null`,
+  the real check returns, and `updateCursorInfo` correctly clears the cursor.
+- **Focus must never actually move to the doc editor.** The `hasFocus` lie makes
+  ProseMirror's `selectionToDOM` treat the doc view as owning the selection — but
+  that only writes a DOM selection *range* (`domSel.collapse/extend`), which does
+  **not** move focus. The one thing that would is `view.focus()` (→ `this.dom.focus()`,
+  `prosemirror-view` index.js:5521). So the same guard neuters `view.focus()` while
+  `activeSurface === 'wysiwyg'`, so no caller (drop handler, command, `restoreFocus`)
+  can steal focus from the iframe and resurrect the toolbar bugs.
+- **`dispatchWithFakeFocus`** is retained as a complement, not the primary mechanism:
+  a mirrored edit can arrive in the instant before the surface flips to `'wysiwyg'`
+  (the message is applied, *then* the surface is claimed), so it forces the lie for
+  that one dispatch to guarantee the edit that moves the caret also broadcasts it.
+- **The visibility layer never reads `view.hasFocus()`** (§4.2). That is what makes
+  the lie safe: it feeds the y-cursor plugin (intended) and cannot influence the
+  toolbar.
 
 ---
 
@@ -234,7 +258,8 @@ as a follow-up with the da-nx owner.
 2. Add `activeSurface` + the §4.2 predicate; move `editorMode` off the header DOM
    query into `setEditorMode`.
 3. Flip the PM plugin and `handlers.js` to emit events; **stop hiding on null
-   `cursor-move`**; confine the focus lie to the scoped dispatch helper.
+   `cursor-move`**; gate the focus lie on the active surface and neuter
+   `view.focus()` while the iframe owns editing (§6).
 4. Move activation to real focus events (doc prose focus/out, iframe focus/blur);
    remove the `activeElement`-based outside logic.
 5. Add coalesced render.
@@ -255,8 +280,9 @@ Drive the real app in **split view**:
   active surface.
 - Switch view modes → toolbar recomputes from the current selection rather than
   hiding until the next selection change.
-- Second collaborator session → this user's cursor remains visible to them while
-  editing in the WYSIWYG pane (confirms the scoped focus lie still works).
+- Second collaborator session → this user's cursor remains visible to them
+  **continuously** (not just a one-tick flash) while editing in the WYSIWYG pane,
+  in both layout and split (confirms the surface-gated focus lie, §6).
 
 ---
 

From bdad6cb14af33b03d565c9f8e87e32953d7481d5 Mon Sep 17 00:00:00 2001
From: Hannes Hertach <hhertach@adobe.com>
Date: Fri, 24 Jul 2026 12:09:01 +0200
Subject: [PATCH 3/6] feat(ew): give the WYSIWYG surface a reduced
 selection-toolbar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The WYSIWYG iframe owns block-level structure, so the shared selection toolbar
now renders a surface-appropriate button set. The controller pushes the active
surface onto the element, and the element gates its sections:

- doc surface: full toolbar (block-type picker, marks, structure, tables, links,
  images incl. add-image)
- wysiwyg surface: inline marks, link controls, and image alt-text editing only
  — the block-type picker, list/structure, table controls, and the add-image
  action are dropped (block insertion and block structure belong to the iframe)

In split view the button set follows the pane you're editing. Ports the
per-surface intent from the earlier PR #1018 into the current architecture.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../canvas/editor-utils/toolbar-controller.js |  3 +++
 .../ew-selection-toolbar.js                   | 26 ++++++++++++++-----
 .../ew-selection-toolbar.test.js              | 24 +++++++++++++++++
 3 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/blocks/canvas/editor-utils/toolbar-controller.js b/blocks/canvas/editor-utils/toolbar-controller.js
index 857717759..b86a9e913 100644
--- a/blocks/canvas/editor-utils/toolbar-controller.js
+++ b/blocks/canvas/editor-utils/toolbar-controller.js
@@ -56,6 +56,9 @@ function render() {
   // Only assign a known view; never clobber with null (teardown just hides, and a
   // fresh view arrives via setDocView on the next load).
   if (state.docView) tb.view = state.docView;
+  // The element renders a surface-appropriate button set: the wysiwyg iframe owns
+  // block-level structure, so it gets inline/link/image controls only.
+  tb.activeSurface = state.activeSurface;
   if (shouldShow(tb)) {
     tb.show();
   } else if (!tb.linkDialogOpen && !tb.altDialogOpen && !tb.isInteracting) {
diff --git a/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.js b/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.js
index 2e051dbee..03b35eaf5 100644
--- a/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.js
+++ b/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.js
@@ -41,6 +41,7 @@ function blockTypeLabelForRaw(raw) {
 class EwSelectionToolbar extends LitElement {
   static properties = {
     view: { attribute: false },
+    activeSurface: { attribute: false },
     org: { type: String },
     site: { type: String },
     sourceUrl: { type: String },
@@ -337,16 +338,27 @@ class EwSelectionToolbar extends LitElement {
     const renderButtons = (items) => items.map((i) => this._renderToolbarButton(i));
     const renderImageItems = (items) => items.map((i) => this._renderImageItem(i));
 
+    const inWysiwyg = this.activeSurface === 'wysiwyg';
+    // The iframe owns block insertion, so "add image" is doc-only; editing a
+    // selected image's alt text stays available in wysiwyg.
+    const imageItems = inWysiwyg
+      ? IMAGE_ITEMS.filter((i) => i.id !== 'image-add')
+      : IMAGE_ITEMS;
+
+    // `wysiwyg` marks sections offered while editing in the WYSIWYG iframe. The
+    // iframe owns block-level structure (block type, lists, tables), so those are
+    // doc-only; inline marks, links, and image controls remain in both surfaces.
     const sections = [
-      { items: PICKER_DEFS, render: () => this._renderBlockTypePicker() },
-      { items: MARK_ITEMS, render: () => renderButtons(MARK_ITEMS) },
-      { items: STRUCTURE_ITEMS, render: () => renderButtons(STRUCTURE_ITEMS) },
-      { items: TABLE_ITEMS, render: () => renderButtons(TABLE_ITEMS) },
-      { items: LINK_ITEMS, render: () => renderButtons(LINK_ITEMS) },
-      { items: IMAGE_ITEMS, render: () => renderImageItems(IMAGE_ITEMS) },
+      { items: PICKER_DEFS, wysiwyg: false, render: () => this._renderBlockTypePicker() },
+      { items: MARK_ITEMS, wysiwyg: true, render: () => renderButtons(MARK_ITEMS) },
+      { items: STRUCTURE_ITEMS, wysiwyg: false, render: () => renderButtons(STRUCTURE_ITEMS) },
+      { items: TABLE_ITEMS, wysiwyg: false, render: () => renderButtons(TABLE_ITEMS) },
+      { items: LINK_ITEMS, wysiwyg: true, render: () => renderButtons(LINK_ITEMS) },
+      { items: imageItems, wysiwyg: true, render: () => renderImageItems(imageItems) },
     ];
 
-    const visible = sections.filter(({ items }) => this._hasVisibleCommands(items));
+    const allowed = inWysiwyg ? sections.filter((s) => s.wysiwyg) : sections;
+    const visible = allowed.filter(({ items }) => this._hasVisibleCommands(items));
     return visible.flatMap(({ render }, i) => {
       const part = render();
       return i === 0 ? [part] : [html`<span class="toolbar-sep" aria-hidden="true"></span>`, part];
diff --git a/test/unit/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.test.js b/test/unit/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.test.js
index 028300006..35be5cf9e 100644
--- a/test/unit/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.test.js
+++ b/test/unit/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.test.js
@@ -107,4 +107,28 @@ describe('ew-selection-toolbar buttons', () => {
     expect(imgNode.attrs.alt).to.equal('New alt');
     expect(toolbar.altDialogOpen).to.be.false;
   });
+
+  it('shows block-level controls in the doc surface', async () => {
+    setText('hello');
+    selectText(1, 6);
+    toolbar.activeSurface = 'doc';
+    await toolbar.updateComplete;
+
+    expect(toolbar.shadowRoot.querySelector('.toolbar-block-type'), 'block-type picker').to.exist;
+    expect(toolbar.shadowRoot.querySelector('button[data-id="bullet-list"]'), 'bullet-list').to.exist;
+    expect(toolbar.shadowRoot.querySelector('button[data-id="strong"]'), 'strong').to.exist;
+    expect(toolbar.shadowRoot.querySelector('button[data-id="image-add"]'), 'add image').to.exist;
+  });
+
+  it('drops block-level controls but keeps inline marks in the wysiwyg surface', async () => {
+    setText('hello');
+    selectText(1, 6);
+    toolbar.activeSurface = 'wysiwyg';
+    await toolbar.updateComplete;
+
+    expect(toolbar.shadowRoot.querySelector('.toolbar-block-type'), 'block-type picker').to.not.exist;
+    expect(toolbar.shadowRoot.querySelector('button[data-id="bullet-list"]'), 'bullet-list').to.not.exist;
+    expect(toolbar.shadowRoot.querySelector('button[data-id="image-add"]'), 'add image').to.not.exist;
+    expect(toolbar.shadowRoot.querySelector('button[data-id="strong"]'), 'strong').to.exist;
+  });
 });

From f648e7ba503561bed04b5c4175313433b75e352b Mon Sep 17 00:00:00 2001
From: Hannes Hertach <hhertach@adobe.com>
Date: Fri, 24 Jul 2026 12:09:12 +0200
Subject: [PATCH 4/6] fix(ew): reset stored marks when the cursor moves in
 WYSIWYG mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

handleCursorMove preserved state.storedMarks whenever the new position had no
adjacent marks, so moving the caret off bold text left bold queued on unmarked
text. That preservation was only meant to survive the same-position cursor-move
the iframe re-reports right after a toolbar toggle — not a real move.

Track the last cursor offset and branch on it: a genuine move resets stored
marks to what's at the new location (nothing on unmarked text), while a
same-position re-report keeps a toolbar-toggled mark until the user types or
actually moves. Also forget the position on iframe blur so re-entry counts as a
move.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../ew-editor-wysiwyg/utils/handlers.js       | 28 +++++++----
 .../ew-editor-wysiwyg/node-select.test.js     | 50 ++++++++++++++++++-
 2 files changed, 67 insertions(+), 11 deletions(-)

diff --git a/blocks/canvas/ew-editor-wysiwyg/utils/handlers.js b/blocks/canvas/ew-editor-wysiwyg/utils/handlers.js
index bc6187c67..28b9c2627 100644
--- a/blocks/canvas/ew-editor-wysiwyg/utils/handlers.js
+++ b/blocks/canvas/ew-editor-wysiwyg/utils/handlers.js
@@ -16,6 +16,9 @@ export function handleCursorMove({ cursorOffset, textCursorOffset }, ctx) {
     // remote cursor, NOT hiding the toolbar. The user is still in the pane while
     // the iframe holds focus; toolbar deactivation comes from the iframe's blur.
     wsProvider.awareness.setLocalStateField('cursor', null);
+    // Forget the last position so re-entering (even at the same offset) counts as
+    // a move and resets stored marks rather than preserving a stale queued mark.
+    ctx.lastCursorPos = null;
     return;
   }
 
@@ -32,28 +35,33 @@ export function handleCursorMove({ cursorOffset, textCursorOffset }, ctx) {
     const { tr } = state;
     tr.setSelection(TextSelection.create(state.doc, position));
 
-    // Sync stored marks so the toolbar reflects the marks active at the cursor.
-    // Two problems this solves:
-    // 1. ProseMirror clears storedMarks whenever selection.anchor changes, which
-    //    happens on every cursor-move — that wipes toolbar-toggled marks before the
-    //    first keystroke arrives.
-    // 2. marksAcross() returns Mark.none when the cursor is at the end of a mark
-    //    run (nothing to the right), so the toolbar shows the mark as inactive even
-    //    though the text is marked.  nodeBefore/nodeAfter covers both sides.
+    // Sync stored marks to the cursor's location. marksAcross() returns Mark.none
+    // when the cursor sits at the end of a mark run (nothing to the right), so the
+    // toolbar would show the mark inactive even though the text is marked;
+    // inspecting nodeBefore/nodeAfter covers both sides.
     const $pos = state.doc.resolve(position);
     const marksBefore = $pos.nodeBefore?.marks;
     const marksAfter = $pos.nodeAfter?.marks;
     const marksAtCursor = (marksBefore?.length ? marksBefore : null)
       ?? (marksAfter?.length ? marksAfter : null);
 
+    // A real cursor move always resets stored marks to what's at the new location
+    // (which is nothing when the text there is unmarked). A toolbar-toggled mark is
+    // only queued for the next keystroke — it must survive the *same-position*
+    // cursor-move the iframe re-reports after the toggle, but not an actual move.
+    const cursorMoved = position !== ctx.lastCursorPos;
     if (marksAtCursor) {
       // Cursor is adjacent to marked text — use those marks (handles Cmd+B case).
       tr.setStoredMarks(marksAtCursor);
+    } else if (cursorMoved) {
+      // Moved onto unmarked text — clear so nothing lingers from the old position.
+      tr.setStoredMarks(null);
     } else if (state.storedMarks?.length) {
-      // No marked text at this position, but user explicitly toggled a mark via
-      // the toolbar — preserve it so it survives cursor-move events before typing.
+      // Same position after a toolbar toggle — keep the queued mark until the user
+      // types or actually moves the cursor.
       tr.setStoredMarks(state.storedMarks);
     }
+    ctx.lastCursorPos = position;
 
     ctx.suppressRerender = true;
     dispatchWithFakeFocus(view, tr.scrollIntoView());
diff --git a/test/unit/blocks/canvas/ew-editor-wysiwyg/node-select.test.js b/test/unit/blocks/canvas/ew-editor-wysiwyg/node-select.test.js
index 429f85f2a..74b787a84 100644
--- a/test/unit/blocks/canvas/ew-editor-wysiwyg/node-select.test.js
+++ b/test/unit/blocks/canvas/ew-editor-wysiwyg/node-select.test.js
@@ -5,7 +5,7 @@ import { setNx } from '../../../../../scripts/utils.js';
 setNx('/test/fixtures/nx', { hostname: 'example.com' });
 
 const { createTestEditor, destroyEditor } = await import('../../edit/prose/test-helpers.js');
-const { handleNodeSelect, resolveNodeSelectPos } = await import('../../../../../blocks/canvas/ew-editor-wysiwyg/utils/handlers.js');
+const { handleNodeSelect, resolveNodeSelectPos, handleCursorMove } = await import('../../../../../blocks/canvas/ew-editor-wysiwyg/utils/handlers.js');
 
 function insertTable(editor) {
   const { state } = editor.view;
@@ -124,3 +124,51 @@ describe('resolveNodeSelectPos', () => {
     expect(resolveNodeSelectPos({ anchorType: 'image', proseIndex: 99999, src: '/nope.png' }, doc)).to.equal(null);
   });
 });
+
+describe('handleCursorMove stored marks', () => {
+  let editor;
+  const wsProvider = { awareness: { setLocalStateField() {} } };
+  beforeEach(async () => { editor = await createTestEditor(); });
+  afterEach(() => destroyEditor(editor));
+
+  function setBoldThenPlain() {
+    const { state } = editor.view;
+    const { schema } = state;
+    const strong = schema.marks.strong.create();
+    const para = schema.nodes.paragraph.create(null, [
+      schema.text('bold', [strong]),
+      schema.text('plain'),
+    ]);
+    editor.view.dispatch(state.tr.replaceWith(0, state.doc.content.size, para));
+  }
+
+  const hasStrong = () => editor.view.state.storedMarks?.some((m) => m.type.name === 'strong');
+  const storedEmpty = () => {
+    const s = editor.view.state.storedMarks;
+    return s == null || s.length === 0;
+  };
+
+  it('resets stored marks when the cursor moves from marked to unmarked text', () => {
+    setBoldThenPlain();
+    const ctx = { view: editor.view, wsProvider };
+    const move = (p) => handleCursorMove({ cursorOffset: p, textCursorOffset: 0 }, ctx);
+
+    move(3); // inside the bold run
+    expect(hasStrong()).to.equal(true);
+    move(8); // into the plain run — bold must not linger
+    expect(storedEmpty()).to.equal(true);
+  });
+
+  it('keeps a toolbar-toggled mark while the cursor stays put', () => {
+    setBoldThenPlain();
+    const ctx = { view: editor.view, wsProvider };
+    const move = (p) => handleCursorMove({ cursorOffset: p, textCursorOffset: 0 }, ctx);
+
+    move(8); // plain text: stored marks reset to none
+    // Queue bold as if toggled in the toolbar (no cursor move).
+    const { schema } = editor.view.state;
+    editor.view.dispatch(editor.view.state.tr.setStoredMarks([schema.marks.strong.create()]));
+    move(8); // same-position re-report from the iframe must not drop it
+    expect(hasStrong()).to.equal(true);
+  });
+});

From 950260ae884d31913391d9770e983fe29e7b22a9 Mon Sep 17 00:00:00 2001
From: Hannes Hertach <hhertach@adobe.com>
Date: Fri, 24 Jul 2026 12:20:56 +0200
Subject: [PATCH 5/6] refactor(ew): drop redundant getSelectionToolbar wrapper

getSelectionToolbar() was a one-line pass-through to
toolbarController.ensureToolbar(); production code already calls the controller
directly. Remove it and point the remaining test at ensureToolbar().

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 blocks/canvas/editor-utils/selection-toolbar.js               | 4 ----
 .../canvas/ew-selection-toolbar/ew-selection-toolbar.test.js  | 4 ++--
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/blocks/canvas/editor-utils/selection-toolbar.js b/blocks/canvas/editor-utils/selection-toolbar.js
index 2c725f136..91aa6889d 100644
--- a/blocks/canvas/editor-utils/selection-toolbar.js
+++ b/blocks/canvas/editor-utils/selection-toolbar.js
@@ -16,10 +16,6 @@ export function getSelectionOriginFromIframe(state) {
   return selectionToolbarOriginKey.getState(state)?.fromIframe ?? false;
 }
 
-export function getSelectionToolbar() {
-  return toolbarController.ensureToolbar();
-}
-
 export function setSelectionToolbarCtx({ org = null, site = null, sourceUrl = null } = {}) {
   const tb = toolbarController.ensureToolbar();
   tb.org = org;
diff --git a/test/unit/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.test.js b/test/unit/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.test.js
index 35be5cf9e..724193427 100644
--- a/test/unit/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.test.js
+++ b/test/unit/blocks/canvas/ew-selection-toolbar/ew-selection-toolbar.test.js
@@ -2,7 +2,7 @@ import { expect } from '@esm-bundle/chai';
 import { TextSelection, NodeSelection } from 'da-y-wrapper';
 import { setNx } from '../../../../../scripts/utils.js';
 import { createTestEditor, destroyEditor } from '../../edit/prose/test-helpers.js';
-import { getSelectionToolbar } from '../../../../../blocks/canvas/editor-utils/selection-toolbar.js';
+import { toolbarController } from '../../../../../blocks/canvas/editor-utils/toolbar-controller.js';
 
 setNx('/test/fixtures/nx', { hostname: 'example.com' });
 
@@ -16,7 +16,7 @@ describe('ew-selection-toolbar buttons', () => {
 
   beforeEach(async () => {
     editor = await createTestEditor();
-    toolbar = getSelectionToolbar();
+    toolbar = toolbarController.ensureToolbar();
     toolbar.view = editor.view;
   });
 

From 4cadee1cc7c07d09464dff332dbfda34128f8f5f Mon Sep 17 00:00:00 2001
From: Hannes Hertach <hhertach@adobe.com>
Date: Fri, 28 Aug 2026 11:55:02 +0200
Subject: [PATCH 6/6] fix: use canvas bus in canvas entry

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 blocks/canvas/canvas.js | 42 ++++++++++++++++-------------------------
 1 file changed, 16 insertions(+), 26 deletions(-)

diff --git a/blocks/canvas/canvas.js b/blocks/canvas/canvas.js
index 6b939f606..b19c827ac 100644
--- a/blocks/canvas/canvas.js
+++ b/blocks/canvas/canvas.js
@@ -1,5 +1,4 @@
 import { getNx } from '../../scripts/utils.js';
-import { editorSelectChange } from './editor-utils/editor-utils.js';
 import {
   normalizeCanvasEditorView,
   readInitialCanvasEditorView,
@@ -20,6 +19,7 @@ import { resolveEditorDocSession } from './ew-editor-doc/utils/load-editor-doc.j
 import { sourceUrlFromEditorCtx } from './ew-editor-doc/utils/ctx.js';
 import { SEL_BLOCK, SEL_ITEM, SEL_TEXT } from './ew-editor-doc/utils/selection.js';
 import { getChatPanelContent } from '../shared/chat-panel.js';
+import { canvasBus } from './utils/canvas-bus.js';
 
 const { loadStyle, hashChange } = await import(`${getNx()}/utils/utils.js`);
 const { CHAT_EVENT } = await import(`${getNx()}/blocks/chat/constants.js`);
@@ -38,25 +38,16 @@ function buildCanvasDocPath(state) {
   return `${org}/${site}/${path}`;
 }
 
-function notifyCanvasEditorActive(mountRoot, view) {
+function notifyCanvasEditorActive(view) {
   const v = normalizeCanvasEditorView(view);
   toolbarController.setEditorMode(v);
-  mountRoot.dispatchEvent(new CustomEvent('nx-canvas-editor-active', {
-    bubbles: false,
-    detail: { view: v },
-  }));
+  canvasBus.editorViewState.emit({ view: v });
 }
 
 function canvasEditorMountRoot(block) {
   return block.querySelector('.default-content') || block;
 }
 
-function canvasHeaderApplyTarget(block) {
-  return block.querySelector('.nx-canvas-editor-mount')
-    || block.querySelector('.default-content')
-    || block;
-}
-
 function removeCanvasEditors(mountRoot) {
   removeSplitGutter(mountRoot);
   mountRoot.querySelector('ew-editor-doc')?.remove();
@@ -133,7 +124,7 @@ async function syncCanvasEditorsToHash({ mountRoot, header, state }) {
   docEl.ctx = ctx;
   ensureNxEditorWysiwyg(mountRoot).ctx = ctx;
   finalizeSplitEditorMountOrder(mountRoot);
-  notifyCanvasEditorActive(mountRoot, header.editorView);
+  notifyCanvasEditorActive(header.editorView);
   syncEditorSplitLayout({ mountRoot, view: header.editorView });
 }
 
@@ -165,17 +156,16 @@ function hashState() {
 async function installCanvasHeader(block, { org, site }) {
   const header = document.createElement('ew-canvas-header');
   header.editorView = await readInitialCanvasEditorView({ org, site });
-  header.addEventListener('nx-canvas-editor-view', (e) => {
-    const view = normalizeCanvasEditorView(e.detail?.view);
+  canvasBus.editorViewRequest.subscribe(({ view: rawView }) => {
+    const view = normalizeCanvasEditorView(rawView);
     persistCanvasEditorView(view);
-    const applyTarget = canvasHeaderApplyTarget(block);
-    notifyCanvasEditorActive(applyTarget, view);
+    notifyCanvasEditorActive(view);
     syncEditorSplitLayout({ mountRoot: canvasEditorMountRoot(block), view });
   });
-  header.addEventListener('nx-canvas-undo', () => {
+  canvasBus.undoRequest.subscribe(() => {
     canvasEditorMountRoot(block).querySelector('ew-editor-doc')?.undo();
   });
-  header.addEventListener('nx-canvas-redo', () => {
+  canvasBus.redoRequest.subscribe(() => {
     canvasEditorMountRoot(block).querySelector('ew-editor-doc')?.redo();
   });
   block.before(header);
@@ -197,7 +187,7 @@ const SHORTCUTS = [
     code: 'KeyS',
     mod: true,
     altKey: true,
-    action: openNewVersionRow,
+    channel: canvasBus.newVersionRequest,
   },
 ];
 document.addEventListener('keydown', (e) => {
@@ -211,10 +201,10 @@ document.addEventListener('keydown', (e) => {
   ));
   if (!match) return;
   e.preventDefault();
-  match.action();
+  match.channel.emit();
 });
 
-document.addEventListener('nx-canvas-new-version', openNewVersionRow);
+canvasBus.newVersionRequest.subscribe(openNewVersionRow);
 
 export default async function decorate(block) {
   const { org, site } = hashState();
@@ -258,9 +248,9 @@ export default async function decorate(block) {
   syncEditorSplitLayout({ mountRoot, view: header.editorView });
   installEditorSplitDrag(mountRoot);
 
-  mountRoot.addEventListener('nx-editor-undo-state', (e) => {
-    header.undoAvailable = e.detail?.canUndo ?? false;
-    header.redoAvailable = e.detail?.canRedo ?? false;
+  canvasBus.undoState.subscribe((detail) => {
+    header.undoAvailable = detail?.canUndo ?? false;
+    header.redoAvailable = detail?.canRedo ?? false;
   });
 
   hashChange.subscribe((state) => {
@@ -283,7 +273,7 @@ export default async function decorate(block) {
   const CANVAS_CHAT_KEY = 'canvas-selection';
   const SELECTION_LABEL = 'Selection';
   let hasContext = false;
-  editorSelectChange.subscribe(({
+  canvasBus.editorSelectState.subscribe(({
     blockIndex, blockName, proseIndex, innerText, source,
     selectionType, selectedHTML, selFrom, selTo,
   }) => {