From 4926df932498ffd87878fc46a685803ec385573e Mon Sep 17 00:00:00 2001
From: Jer Miller <jeremie.miller@gmail.com>
Date: Sun, 26 Jul 2026 17:33:25 -0600
Subject: [PATCH] fix(convey): isolate active workspace dialogs from shell
 chrome

Dissolve the .workspace view-transition stacking context only while a managed dialog is open, and raise the active dialog above shell chrome with a new --z-active-dialog token.

The modal layer inerts background branches with an ancestor-chain sibling walk and restores prior inert state exactly when the dialog closes or is removed.

The managed set is body-wide [role="dialog"][aria-modal="true"] minus the shell-owned #talentViewModal and .report-error-modal dialogs, because Speakers mounts its backdrop directly to document.body.
---
 solstone/convey/static/app.css        |  15 +
 solstone/convey/static/modal_layer.js | 333 ++++++++++++
 solstone/convey/static/shell.html     |   1 +
 tests/js/modal_layer_harness.js       | 738 ++++++++++++++++++++++++++
 tests/test_convey_modal_layer_js.py   |  43 ++
 tests/test_convey_shell_chrome.py     |  34 ++
 tests/test_convey_spa_shell.py        |   1 +
 7 files changed, 1165 insertions(+)
 create mode 100644 solstone/convey/static/modal_layer.js
 create mode 100644 tests/js/modal_layer_harness.js
 create mode 100644 tests/test_convey_modal_layer_js.py

diff --git a/solstone/convey/static/app.css b/solstone/convey/static/app.css
index ee80e724d..f3f6479b2 100644
--- a/solstone/convey/static/app.css
+++ b/solstone/convey/static/app.css
@@ -97,6 +97,11 @@ html {
   --z-modals: 200;        /* Modal overlays */
   --z-notifications: 300; /* Notifications, status pane, error log */
   --z-tags: 400;          /* Corner tags - topmost layer */
+  /*
+   * Above .skip-link (9999) and presentation-mode body::after (9998);
+   * inert cannot disable that click-to-exit pseudo-element.
+   */
+  --z-active-dialog: 10000;
 }
 
 body {
@@ -113,6 +118,16 @@ body {
   margin-left: var(--menu-bar-width-minimal);
 }
 
+body.has-managed-dialog .workspace {
+  view-transition-name: none;
+}
+
+[data-convey-active-dialog],
+[data-convey-active-dialog-host] {
+  /* App workspace <style> blocks load after app.css at equal specificity. */
+  z-index: var(--z-active-dialog) !important;
+}
+
 body.menu-full .workspace {
   margin-left: var(--menu-bar-width-full);
 }
diff --git a/solstone/convey/static/modal_layer.js b/solstone/convey/static/modal_layer.js
new file mode 100644
index 000000000..a65153a9f
--- /dev/null
+++ b/solstone/convey/static/modal_layer.js
@@ -0,0 +1,333 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 sol pbc
+
+(function (global) {
+  const MANAGED_DIALOG_SELECTOR = '[role="dialog"][aria-modal="true"]';
+  // Assignment §8 items 1-2: shell-owned dialogs stay outside this app workspace layer.
+  const UNMANAGED_DIALOG_SELECTOR = '#talentViewModal, .report-error-modal';
+  const BODY_ACTIVE_CLASS = 'has-managed-dialog';
+  const ACTIVE_DIALOG_ATTR = 'data-convey-active-dialog';
+  const ACTIVE_HOST_ATTR = 'data-convey-active-dialog-host';
+  const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'area[href]',
+    'button',
+    'input',
+    'select',
+    'textarea',
+    'summary',
+    'iframe',
+    'object',
+    'embed',
+    '[contenteditable="true"]',
+    '[contenteditable=""]',
+    '[tabindex]',
+  ].join(',');
+
+  let initialized = false;
+  let observer = null;
+  let reconcileQueued = false;
+  let activeDialog = null;
+  let activeHost = null;
+  let lastOutsideFocus = null;
+  let lastTabWasBackward = false;
+  const inertRecords = new Map();
+
+  function bodyElement() {
+    if (!document.body) {
+      throw new Error('managed modal layer requires document.body');
+    }
+    return document.body;
+  }
+
+  function elementChildren(element) {
+    return Array.from(element.children || []);
+  }
+
+  function hasHiddenAttribute(element) {
+    return Boolean(
+      element.hidden
+      || (typeof element.hasAttribute === 'function' && element.hasAttribute('hidden'))
+    );
+  }
+
+  function isInDocumentBody(element) {
+    for (let node = element; node; node = node.parentElement) {
+      if (node === document.body) return true;
+    }
+    return false;
+  }
+
+  function isRenderedOpen(element) {
+    for (let node = element; node; node = node.parentElement) {
+      if (hasHiddenAttribute(node)) return false;
+      if (node.style && node.style.display === 'none') return false;
+      if (global.getComputedStyle(node).display === 'none') return false;
+      if (node === document.body) return true;
+    }
+    return false;
+  }
+
+  function isManagedDialog(element) {
+    return Boolean(
+      element
+      && typeof element.matches === 'function'
+      && element.matches(MANAGED_DIALOG_SELECTOR)
+      && !element.matches(UNMANAGED_DIALOG_SELECTOR)
+    );
+  }
+
+  function managedDialogs() {
+    return Array.from(bodyElement().querySelectorAll(MANAGED_DIALOG_SELECTOR))
+      .filter((dialog) => !dialog.matches(UNMANAGED_DIALOG_SELECTOR));
+  }
+
+  function findActiveDialog() {
+    let visibleDialog = null;
+    managedDialogs().forEach((dialog) => {
+      if (isRenderedOpen(dialog)) {
+        // If multiple managed dialogs are visible, the last in document order is active.
+        visibleDialog = dialog;
+      }
+    });
+    return visibleDialog;
+  }
+
+  function findActiveHost(dialog) {
+    if (global.getComputedStyle(dialog).position !== 'static') {
+      return null;
+    }
+    // Speakers is static inside a positioned backdrop; positioned dialogs need no host.
+    for (let node = dialog.parentElement; node && node !== document.body; node = node.parentElement) {
+      if (global.getComputedStyle(node).position !== 'static') {
+        return node;
+      }
+    }
+    return null;
+  }
+
+  function clearMarkers() {
+    if (activeDialog) {
+      activeDialog.removeAttribute(ACTIVE_DIALOG_ATTR);
+    }
+    if (activeHost) {
+      activeHost.removeAttribute(ACTIVE_HOST_ATTR);
+    }
+    activeDialog = null;
+    activeHost = null;
+  }
+
+  function applyMarkers(dialog) {
+    if (activeDialog !== dialog) {
+      clearMarkers();
+    } else if (activeHost) {
+      activeHost.removeAttribute(ACTIVE_HOST_ATTR);
+      activeHost = null;
+    }
+
+    activeDialog = dialog;
+    activeHost = findActiveHost(dialog);
+    activeDialog.setAttribute(ACTIVE_DIALOG_ATTR, '');
+    if (activeHost) {
+      activeHost.setAttribute(ACTIVE_HOST_ATTR, '');
+    }
+  }
+
+  function isElementInert(element) {
+    return Boolean(
+      element.inert
+      || (typeof element.hasAttribute === 'function' && element.hasAttribute('inert'))
+    );
+  }
+
+  function rememberAndInert(element) {
+    if (!inertRecords.has(element)) {
+      inertRecords.set(element, { wasInert: isElementInert(element) });
+    }
+    element.inert = true;
+    element.setAttribute('inert', '');
+  }
+
+  function restoreInert(element, record) {
+    if (record.wasInert) {
+      element.inert = true;
+      element.setAttribute('inert', '');
+      return;
+    }
+    element.inert = false;
+    element.removeAttribute('inert');
+  }
+
+  function collectInertSiblings(dialog) {
+    const siblings = new Set();
+    let branch = dialog;
+    for (let parent = dialog.parentElement; parent; parent = parent.parentElement) {
+      elementChildren(parent).forEach((child) => {
+        if (child !== branch) {
+          siblings.add(child);
+        }
+      });
+      if (parent === document.body) {
+        return siblings;
+      }
+      branch = parent;
+    }
+    return siblings;
+  }
+
+  function applyInert(dialog) {
+    const desired = dialog ? collectInertSiblings(dialog) : new Set();
+
+    inertRecords.forEach((record, element) => {
+      if (!element.isConnected || !desired.has(element)) {
+        if (element.isConnected) {
+          restoreInert(element, record);
+        }
+        inertRecords.delete(element);
+      }
+    });
+
+    desired.forEach((element) => {
+      rememberAndInert(element);
+    });
+  }
+
+  function isInsideManagedDialog(element) {
+    for (let node = element; node && node !== document.body; node = node.parentElement) {
+      if (isManagedDialog(node)) return true;
+    }
+    return false;
+  }
+
+  function hasInertAncestor(element) {
+    for (let node = element; node && node !== document.body; node = node.parentElement) {
+      if (isElementInert(node)) return true;
+    }
+    return false;
+  }
+
+  function isDisabled(element) {
+    return Boolean(element.disabled || element.getAttribute('aria-disabled') === 'true');
+  }
+
+  function hasNegativeTabIndex(element) {
+    const value = element.getAttribute('tabindex');
+    return value !== null && Number(value) < 0;
+  }
+
+  function isFocusableCandidate(element) {
+    return Boolean(
+      typeof element.focus === 'function'
+      && !isDisabled(element)
+      && !hasNegativeTabIndex(element)
+      && !hasInertAncestor(element)
+      && isRenderedOpen(element)
+    );
+  }
+
+  function focusableCandidates(dialog) {
+    return Array.from(dialog.querySelectorAll(FOCUSABLE_SELECTOR))
+      .filter(isFocusableCandidate);
+  }
+
+  function focusDialog(dialog, reverse) {
+    const candidates = focusableCandidates(dialog);
+    const target = reverse ? candidates[candidates.length - 1] : candidates[0];
+    if (target) {
+      target.focus();
+      return;
+    }
+    if (typeof dialog.focus === 'function') {
+      dialog.focus();
+    }
+  }
+
+  function restoreOpener() {
+    const opener = lastOutsideFocus;
+    if (
+      opener
+      && opener.isConnected
+      && typeof opener.focus === 'function'
+      && !isDisabled(opener)
+      && !hasInertAncestor(opener)
+      && isRenderedOpen(opener)
+    ) {
+      opener.focus();
+    }
+  }
+
+  function reconcile() {
+    const previousDialog = activeDialog;
+    const dialog = findActiveDialog();
+
+    if (!dialog) {
+      bodyElement().classList.remove(BODY_ACTIVE_CLASS);
+      clearMarkers();
+      applyInert(null);
+      if (previousDialog) {
+        restoreOpener();
+      }
+      return;
+    }
+
+    bodyElement().classList.add(BODY_ACTIVE_CLASS);
+    applyMarkers(dialog);
+    applyInert(dialog);
+
+    if (previousDialog !== dialog) {
+      const focused = document.activeElement;
+      if (!focused || !dialog.contains(focused)) {
+        focusDialog(dialog, false);
+      }
+    }
+  }
+
+  function scheduleReconcile() {
+    if (reconcileQueued) return;
+    reconcileQueued = true;
+    global.requestAnimationFrame(() => {
+      reconcileQueued = false;
+      reconcile();
+    });
+  }
+
+  function handleFocusIn(event) {
+    const target = event.target;
+    if (!target || !isInDocumentBody(target)) return;
+
+    if (!activeDialog && !isInsideManagedDialog(target)) {
+      lastOutsideFocus = target;
+      return;
+    }
+
+    if (activeDialog && !activeDialog.contains(target)) {
+      focusDialog(activeDialog, lastTabWasBackward);
+    }
+  }
+
+  function handleKeyDown(event) {
+    if (event.key === 'Tab') {
+      lastTabWasBackward = Boolean(event.shiftKey);
+    }
+  }
+
+  function init() {
+    if (initialized) return;
+    initialized = true;
+
+    observer = new MutationObserver(scheduleReconcile);
+    observer.observe(bodyElement(), {
+      attributes: true,
+      attributeFilter: ['hidden', 'style', 'class', 'aria-modal', 'role'],
+      childList: true,
+      subtree: true,
+    });
+    document.addEventListener('focusin', handleFocusIn, true);
+    document.addEventListener('keydown', handleKeyDown, true);
+    document.addEventListener('workspace:mounted', reconcile);
+    reconcile();
+  }
+
+  global.ConveyModalLayer = { init, reconcile };
+  global.whenShellReady(init);
+})(window);
diff --git a/solstone/convey/static/shell.html b/solstone/convey/static/shell.html
index ed0e725ee..5fb21421a 100644
--- a/solstone/convey/static/shell.html
+++ b/solstone/convey/static/shell.html
@@ -46,6 +46,7 @@
   <script src="/static/day-grid.js" defer></script>
   <script src="/static/drawer.js" defer></script>
   <script src="/static/gate-drawer.js" defer></script>
+  <script src="/static/modal_layer.js" defer></script>
   <script src="/static/shell_boot.js" defer></script>
 </head>
 <body>
diff --git a/tests/js/modal_layer_harness.js b/tests/js/modal_layer_harness.js
new file mode 100644
index 000000000..341d55f44
--- /dev/null
+++ b/tests/js/modal_layer_harness.js
@@ -0,0 +1,738 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 sol pbc
+
+const assert = require('assert');
+const fs = require('fs');
+const vm = require('vm');
+
+const modalLayerPath = process.argv[2];
+const caseName = process.argv[3];
+
+class FakeClassList {
+  constructor(element) {
+    this.element = element;
+    this.values = new Set();
+  }
+
+  add(...names) {
+    let changed = false;
+    names.forEach((name) => {
+      if (name && !this.values.has(String(name))) {
+        this.values.add(String(name));
+        changed = true;
+      }
+    });
+    if (changed) this.element._syncClassAttribute();
+  }
+
+  remove(...names) {
+    let changed = false;
+    names.forEach((name) => {
+      if (this.values.delete(String(name))) {
+        changed = true;
+      }
+    });
+    if (changed) this.element._syncClassAttribute();
+  }
+
+  contains(name) {
+    return this.values.has(String(name));
+  }
+
+  toggle(name, force) {
+    if (force === true) {
+      this.add(name);
+      return true;
+    }
+    if (force === false) {
+      this.remove(name);
+      return false;
+    }
+    if (this.contains(name)) {
+      this.remove(name);
+      return false;
+    }
+    this.add(name);
+    return true;
+  }
+
+  setFromString(value) {
+    this.values = new Set(String(value || '').split(/\s+/).filter(Boolean));
+  }
+
+  toString() {
+    return Array.from(this.values).join(' ');
+  }
+}
+
+class FakeElement {
+  constructor(document, tagName = 'div') {
+    this.ownerDocument = document;
+    this.nodeType = 1;
+    this.tagName = String(tagName).toUpperCase();
+    this.attributes = {};
+    this.children = [];
+    this.parentElement = null;
+    this.style = {};
+    this.hidden = false;
+    this.inert = false;
+    this.disabled = false;
+    this.listeners = {};
+    this.classList = new FakeClassList(this);
+  }
+
+  get id() {
+    return this.attributes.id || '';
+  }
+
+  set id(value) {
+    this.setAttribute('id', value);
+  }
+
+  get className() {
+    return this.classList.toString();
+  }
+
+  set className(value) {
+    this.classList.setFromString(value);
+    this._syncClassAttribute();
+  }
+
+  get isConnected() {
+    for (let node = this; node; node = node.parentElement) {
+      if (node === this.ownerDocument.body) return true;
+    }
+    return false;
+  }
+
+  _syncClassAttribute() {
+    const value = this.classList.toString();
+    if (value) {
+      this.attributes.class = value;
+    } else {
+      delete this.attributes.class;
+    }
+    this.ownerDocument._notifyMutation('class');
+  }
+
+  appendChild(child) {
+    if (child.parentElement) {
+      child.parentElement.removeChild(child);
+    }
+    this.children.push(child);
+    child.parentElement = this;
+    this.ownerDocument._notifyMutation();
+    return child;
+  }
+
+  removeChild(child) {
+    const index = this.children.indexOf(child);
+    assert(index !== -1, 'child is not attached to parent');
+    this.children.splice(index, 1);
+    child.parentElement = null;
+    this.ownerDocument._notifyMutation();
+    return child;
+  }
+
+  setAttribute(name, value) {
+    const attr = String(name);
+    this.attributes[attr] = String(value);
+    if (attr === 'hidden') this.hidden = true;
+    if (attr === 'inert') this.inert = true;
+    if (attr === 'class') this.classList.setFromString(value);
+    this.ownerDocument._notifyMutation(attr);
+  }
+
+  removeAttribute(name) {
+    const attr = String(name);
+    delete this.attributes[attr];
+    if (attr === 'hidden') this.hidden = false;
+    if (attr === 'inert') this.inert = false;
+    if (attr === 'class') this.classList.setFromString('');
+    this.ownerDocument._notifyMutation(attr);
+  }
+
+  hasAttribute(name) {
+    return Object.prototype.hasOwnProperty.call(this.attributes, String(name));
+  }
+
+  getAttribute(name) {
+    const attr = String(name);
+    return this.hasAttribute(attr) ? this.attributes[attr] : null;
+  }
+
+  addEventListener(type, listener) {
+    if (!this.listeners[type]) this.listeners[type] = [];
+    this.listeners[type].push(listener);
+  }
+
+  dispatchEvent(event) {
+    const listeners = this.listeners[event.type] || [];
+    listeners.forEach((listener) => listener(event));
+  }
+
+  contains(target) {
+    for (let node = target; node; node = node.parentElement) {
+      if (node === this) return true;
+    }
+    return false;
+  }
+
+  focus() {
+    if (this.ownerDocument.activeElement === this) return;
+    this.ownerDocument.activeElement = this;
+    this.ownerDocument.dispatchEvent({ type: 'focusin', target: this });
+  }
+
+  matches(selector) {
+    return selector.split(',').some((part) => this._matchesSingle(part.trim()));
+  }
+
+  _matchesSingle(selector) {
+    if (!selector) return false;
+    if (selector === '[role="dialog"][aria-modal="true"]') {
+      return this.getAttribute('role') === 'dialog'
+        && this.getAttribute('aria-modal') === 'true';
+    }
+    if (selector === '.report-error-modal') {
+      return this.classList.contains('report-error-modal');
+    }
+    if (selector.startsWith('#')) {
+      return this.id === selector.slice(1);
+    }
+    if (selector.startsWith('.')) {
+      return this.classList.contains(selector.slice(1));
+    }
+    if (selector === '[tabindex]') {
+      return this.hasAttribute('tabindex');
+    }
+    if (selector === '[contenteditable="true"]') {
+      return this.getAttribute('contenteditable') === 'true';
+    }
+    if (selector === '[contenteditable=""]') {
+      return this.getAttribute('contenteditable') === '';
+    }
+    if (selector === 'a[href]' || selector === 'area[href]') {
+      return this.tagName.toLowerCase() === selector.slice(0, selector.indexOf('['))
+        && this.hasAttribute('href');
+    }
+    return this.tagName.toLowerCase() === selector;
+  }
+
+  querySelectorAll(selector) {
+    const results = [];
+    const visit = (node) => {
+      node.children.forEach((child) => {
+        if (child.matches(selector)) {
+          results.push(child);
+        }
+        visit(child);
+      });
+    };
+    visit(this);
+    return results;
+  }
+}
+
+class FakeDocument {
+  constructor() {
+    this.listeners = {};
+    this.readyState = 'complete';
+    this.activeElement = null;
+    this.observers = [];
+    this.body = new FakeElement(this, 'body');
+  }
+
+  createElement(tagName) {
+    return new FakeElement(this, tagName);
+  }
+
+  addEventListener(type, listener) {
+    if (!this.listeners[type]) this.listeners[type] = [];
+    this.listeners[type].push(listener);
+  }
+
+  dispatchEvent(event) {
+    const listeners = this.listeners[event.type] || [];
+    listeners.forEach((listener) => listener(event));
+  }
+
+  listenerCount(type) {
+    return (this.listeners[type] || []).length;
+  }
+
+  _notifyMutation(attributeName = null) {
+    this.observers.forEach((observer) => {
+      const filter = observer.options.attributeFilter || null;
+      if (attributeName && filter && !filter.includes(attributeName)) return;
+      observer.callback();
+    });
+  }
+}
+
+class FakeMutationObserver {
+  constructor(callback) {
+    this.callback = callback;
+  }
+
+  observe(target, options) {
+    target.ownerDocument.observers.push({ callback: this.callback, target, options });
+  }
+}
+
+function makeContext() {
+  const document = new FakeDocument();
+  const frames = [];
+  const context = {
+    console,
+    document,
+    MutationObserver: FakeMutationObserver,
+    requestAnimationFrame(callback) {
+      frames.push(callback);
+      return frames.length;
+    },
+    getComputedStyle(element) {
+      return {
+        display: computedDisplay(element),
+        position: computedPosition(element),
+      };
+    },
+  };
+  context.window = context;
+  context.globalThis = context;
+  context.whenShellReady = (callback) => callback({});
+  context.flushFrames = function flushFrames() {
+    while (frames.length) {
+      const frame = frames.shift();
+      frame();
+    }
+  };
+  vm.createContext(context);
+  vm.runInContext(fs.readFileSync(modalLayerPath, 'utf8'), context, {
+    filename: modalLayerPath,
+  });
+  return context;
+}
+
+function computedDisplay(element) {
+  if (element.style.display) return element.style.display;
+  if (element.classList.contains('modal-backdrop')) {
+    return element.classList.contains('show') ? 'flex' : 'none';
+  }
+  if (element.classList.contains('color-modal')) return 'none';
+  if (element.classList.contains('modal')) return 'none';
+  if (element.id === 'trDeleteSegmentModal') return 'none';
+  return 'block';
+}
+
+function computedPosition(element) {
+  if (element.classList.contains('position-relative')) {
+    return 'relative';
+  }
+  if (
+    element.classList.contains('link-modal')
+    || element.classList.contains('modal')
+    || element.classList.contains('modal-backdrop')
+    || element.classList.contains('color-modal')
+    || element.classList.contains('tr-screenshot-modal')
+    || element.classList.contains('fixed-dialog')
+    || element.classList.contains('spk-who-backdrop')
+    || element.id === 'trDeleteSegmentModal'
+  ) {
+    return 'fixed';
+  }
+  return 'static';
+}
+
+function el(document, tagName, attrs = {}) {
+  const element = document.createElement(tagName);
+  Object.entries(attrs).forEach(([name, value]) => {
+    if (name === 'class') {
+      element.className = value;
+    } else if (name === 'hidden') {
+      if (value) element.setAttribute('hidden', '');
+    } else if (name === 'disabled') {
+      element.disabled = Boolean(value);
+    } else if (name === 'styleDisplay') {
+      element.style.display = value;
+    } else {
+      element.setAttribute(name, value);
+    }
+  });
+  return element;
+}
+
+function dialog(document, attrs = {}) {
+  return el(document, 'div', {
+    role: 'dialog',
+    'aria-modal': 'true',
+    ...attrs,
+  });
+}
+
+function shell(document) {
+  const skip = el(document, 'a', { id: 'skip-link', href: '#main-content' });
+  const menu = el(document, 'nav', { id: 'menu-bar' });
+  const facet = el(document, 'nav', { id: 'facet-bar' });
+  const notifications = el(document, 'div', { id: 'notification-center' });
+  const talent = dialog(document, { id: 'talentViewModal', hidden: true });
+  const workspace = el(document, 'main', { id: 'main-content', class: 'workspace' });
+  const report = dialog(document, { class: 'modal report-error-modal', styleDisplay: 'block' });
+  document.body.appendChild(skip);
+  document.body.appendChild(menu);
+  document.body.appendChild(facet);
+  document.body.appendChild(notifications);
+  document.body.appendChild(talent);
+  document.body.appendChild(workspace);
+  document.body.appendChild(report);
+  return { skip, menu, facet, notifications, talent, workspace, report };
+}
+
+function makeWorkspaceShape(context, kind) {
+  const document = context.document;
+  const base = shell(document);
+  const root = el(document, 'section', { id: `${kind}-root` });
+  const panel = el(document, 'section', { id: `${kind}-panel` });
+  const backgroundButton = el(document, 'button', { id: `${kind}-background` });
+  panel.appendChild(backgroundButton);
+  root.appendChild(panel);
+  base.workspace.appendChild(root);
+
+  if (kind === 'network-pair' || kind === 'network-unpair') {
+    const modal = dialog(document, {
+      id: kind === 'network-pair' ? 'link-pair-modal' : 'link-unpair-modal',
+      class: 'link-modal',
+      hidden: true,
+    });
+    modal.appendChild(el(document, 'div', { class: 'link-modal-box' }));
+    panel.appendChild(modal);
+    return {
+      ...base,
+      dialog: modal,
+      expectedMarker: modal,
+      open() { modal.removeAttribute('hidden'); },
+      close() { modal.setAttribute('hidden', ''); },
+    };
+  }
+
+  if (kind === 'import') {
+    const modal = dialog(document, { id: 'detectModal', class: 'modal' });
+    panel.appendChild(modal);
+    return {
+      ...base,
+      dialog: modal,
+      expectedMarker: modal,
+      open() { modal.style.display = 'block'; document._notifyMutation('style'); },
+      close() { modal.style.display = 'none'; document._notifyMutation('style'); },
+    };
+  }
+
+  if (kind === 'observer') {
+    const modal = dialog(document, { id: 'keyModal', class: 'modal' });
+    panel.appendChild(modal);
+    return {
+      ...base,
+      dialog: modal,
+      expectedMarker: modal,
+      open() { modal.style.display = 'block'; document._notifyMutation('style'); },
+      close() { modal.style.display = 'none'; document._notifyMutation('style'); },
+    };
+  }
+
+  if (kind === 'transcripts-delete') {
+    const modal = dialog(document, {
+      id: 'trDeleteSegmentModal',
+      class: 'modal',
+      styleDisplay: 'none',
+    });
+    panel.appendChild(modal);
+    return {
+      ...base,
+      dialog: modal,
+      expectedMarker: modal,
+      open() { modal.style.display = 'flex'; document._notifyMutation('style'); },
+      close() { modal.style.display = 'none'; document._notifyMutation('style'); },
+    };
+  }
+
+  if (kind === 'transcripts-screenshot') {
+    const modal = dialog(document, {
+      id: 'trImageModal',
+      class: 'tr-screenshot-modal',
+    });
+    modal.style.display = 'none';
+    document.body.appendChild(modal);
+    return {
+      ...base,
+      dialog: modal,
+      expectedMarker: modal,
+      open() { modal.style.display = 'flex'; document._notifyMutation('style'); },
+      close() { modal.style.display = 'none'; document._notifyMutation('style'); },
+    };
+  }
+
+  if (kind === 'sol') {
+    const modal = dialog(document, { id: 'preview-modal', class: 'modal-backdrop' });
+    panel.appendChild(modal);
+    return {
+      ...base,
+      dialog: modal,
+      expectedMarker: modal,
+      open() { modal.classList.add('show'); },
+      close() { modal.classList.remove('show'); },
+    };
+  }
+
+  if (kind.startsWith('settings-')) {
+    const modal = dialog(document, { id: kind, class: 'color-modal' });
+    panel.appendChild(modal);
+    return {
+      ...base,
+      dialog: modal,
+      expectedMarker: modal,
+      open() { modal.style.display = kind.endsWith('cleanup') ? 'flex' : 'block'; document._notifyMutation('style'); },
+      close() { modal.style.display = 'none'; document._notifyMutation('style'); },
+    };
+  }
+
+  if (kind === 'speakers') {
+    const backdrop = el(document, 'div', { class: 'spk-who-backdrop', hidden: true });
+    const modal = dialog(document, { class: 'spk-who-dialog' });
+    backdrop.appendChild(modal);
+    document.body.appendChild(backdrop);
+    return {
+      ...base,
+      backdrop,
+      dialog: modal,
+      expectedMarker: modal,
+      expectedHost: backdrop,
+      open() { backdrop.removeAttribute('hidden'); },
+      close() { backdrop.setAttribute('hidden', ''); },
+    };
+  }
+
+  throw new Error(`unknown shape: ${kind}`);
+}
+
+function assertInactive(context, shape) {
+  context.flushFrames();
+  assert(!context.document.body.classList.contains('has-managed-dialog'));
+  assert(!shape.dialog.hasAttribute('data-convey-active-dialog'));
+  if (shape.expectedHost) {
+    assert(!shape.expectedHost.hasAttribute('data-convey-active-dialog-host'));
+  }
+}
+
+function assertActive(context, shape) {
+  context.flushFrames();
+  assert(context.document.body.classList.contains('has-managed-dialog'));
+  assert(shape.expectedMarker.hasAttribute('data-convey-active-dialog'));
+  if (shape.expectedHost) {
+    assert(shape.expectedHost.hasAttribute('data-convey-active-dialog-host'));
+  }
+}
+
+function testVisibilityShapes() {
+  [
+    'network-pair',
+    'network-unpair',
+    'import',
+    'observer',
+    'transcripts-delete',
+    'transcripts-screenshot',
+    'sol',
+    'settings-custom',
+    'settings-icon',
+    'settings-color',
+    'settings-cleanup',
+    'settings-cleanupLogs',
+    'speakers',
+  ].forEach((kind) => {
+    const context = makeContext();
+    const shape = makeWorkspaceShape(context, kind);
+    context.ConveyModalLayer.reconcile();
+    assertInactive(context, shape);
+    shape.open();
+    assertActive(context, shape);
+    shape.close();
+    assertInactive(context, shape);
+  });
+}
+
+function testActivationDeactivation() {
+  const context = makeContext();
+  const shape = makeWorkspaceShape(context, 'network-pair');
+  shape.open();
+  assertActive(context, shape);
+  shape.close();
+  assertInactive(context, shape);
+}
+
+function testInertRestoration() {
+  const context = makeContext();
+  const shape = makeWorkspaceShape(context, 'network-pair');
+  const preInert = shape.menu;
+  preInert.setAttribute('inert', '');
+  const sibling = el(context.document, 'button', { id: 'dialog-sibling' });
+  shape.dialog.parentElement.appendChild(sibling);
+
+  shape.open();
+  assertActive(context, shape);
+  assert(shape.skip.inert);
+  assert(shape.facet.inert);
+  assert(preInert.inert);
+  assert(sibling.inert);
+  assert(!shape.workspace.inert);
+  assert(!shape.dialog.inert);
+
+  shape.close();
+  assertInactive(context, shape);
+  assert(!shape.skip.inert);
+  assert(!shape.facet.inert);
+  assert(preInert.inert);
+  assert(preInert.hasAttribute('inert'));
+  assert(!sibling.inert);
+  assert(!sibling.hasAttribute('inert'));
+}
+
+function testInitialFocusSkipsInvalidCandidates() {
+  const context = makeContext();
+  const shape = makeWorkspaceShape(context, 'network-pair');
+  const hidden = el(context.document, 'button', { hidden: true });
+  const inert = el(context.document, 'button');
+  inert.setAttribute('inert', '');
+  const disabled = el(context.document, 'button', { disabled: true });
+  const nonRendered = el(context.document, 'button', { styleDisplay: 'none' });
+  const target = el(context.document, 'button', { id: 'first-valid' });
+  shape.dialog.appendChild(hidden);
+  shape.dialog.appendChild(inert);
+  shape.dialog.appendChild(disabled);
+  shape.dialog.appendChild(nonRendered);
+  shape.dialog.appendChild(target);
+  shape.skip.focus();
+
+  shape.open();
+  assertActive(context, shape);
+  assert.strictEqual(context.document.activeElement, target);
+}
+
+function testForwardAndReverseWrap() {
+  const context = makeContext();
+  const shape = makeWorkspaceShape(context, 'network-pair');
+  const first = el(context.document, 'button', { id: 'first' });
+  const last = el(context.document, 'button', { id: 'last' });
+  shape.dialog.appendChild(first);
+  shape.dialog.appendChild(last);
+  shape.open();
+  assertActive(context, shape);
+
+  shape.skip.focus();
+  assert.strictEqual(context.document.activeElement, first);
+
+  context.document.dispatchEvent({ type: 'keydown', key: 'Tab', shiftKey: true });
+  shape.facet.focus();
+  assert.strictEqual(context.document.activeElement, last);
+}
+
+function testOutsideFocusRedirects() {
+  const context = makeContext();
+  const shape = makeWorkspaceShape(context, 'network-pair');
+  const first = el(context.document, 'button', { id: 'inside' });
+  shape.dialog.appendChild(first);
+  shape.open();
+  assertActive(context, shape);
+
+  shape.notifications.focus();
+  assert.strictEqual(context.document.activeElement, first);
+}
+
+function testOpenerRestoresAfterSynchronousAppFocus() {
+  const context = makeContext();
+  const shape = makeWorkspaceShape(context, 'network-pair');
+  const inside = el(context.document, 'button', { id: 'inside' });
+  shape.dialog.appendChild(inside);
+  shape.skip.focus();
+
+  shape.open();
+  inside.focus();
+  context.flushFrames();
+  assert.strictEqual(context.document.activeElement, inside);
+
+  shape.close();
+  context.flushFrames();
+  assert.strictEqual(context.document.activeElement, shape.skip);
+}
+
+function testRepeatedWorkspaceMountedIsIdempotent() {
+  const context = makeContext();
+  shell(context.document);
+  context.ConveyModalLayer.init();
+  context.ConveyModalLayer.init();
+  context.document.dispatchEvent({ type: 'workspace:mounted', target: context.document });
+  context.document.dispatchEvent({ type: 'workspace:mounted', target: context.document });
+
+  assert.strictEqual(context.document.observers.length, 1);
+  assert.strictEqual(context.document.listenerCount('workspace:mounted'), 1);
+  assert.strictEqual(context.document.listenerCount('focusin'), 1);
+  assert.strictEqual(context.document.listenerCount('keydown'), 1);
+}
+
+function testWorkspaceRemovalRestoresState() {
+  const context = makeContext();
+  const shape = makeWorkspaceShape(context, 'network-pair');
+  shape.open();
+  assertActive(context, shape);
+  assert(shape.skip.inert);
+  assert(shape.dialog.hasAttribute('data-convey-active-dialog'));
+
+  context.document.body.removeChild(shape.workspace);
+  context.flushFrames();
+
+  assert(!context.document.body.classList.contains('has-managed-dialog'));
+  assert(!shape.skip.inert);
+  assert(!shape.skip.hasAttribute('inert'));
+  assert(!shape.dialog.hasAttribute('data-convey-active-dialog'));
+}
+
+function testPositionedDialogDoesNotMarkPositionedAncestor() {
+  const context = makeContext();
+  const base = shell(context.document);
+  const positionedAncestor = el(context.document, 'section', {
+    id: 'positioned-ancestor',
+    class: 'position-relative',
+  });
+  const modal = dialog(context.document, {
+    id: 'fixed-dialog',
+    class: 'fixed-dialog',
+  });
+  modal.appendChild(el(context.document, 'button', { id: 'inside-fixed-dialog' }));
+  positionedAncestor.appendChild(modal);
+  base.workspace.appendChild(positionedAncestor);
+
+  context.ConveyModalLayer.reconcile();
+
+  assert(context.document.body.classList.contains('has-managed-dialog'));
+  assert(modal.hasAttribute('data-convey-active-dialog'));
+  assert(!positionedAncestor.hasAttribute('data-convey-active-dialog-host'));
+}
+
+const cases = {
+  visibility_shapes: testVisibilityShapes,
+  activation_deactivation: testActivationDeactivation,
+  inert_restoration: testInertRestoration,
+  initial_focus_skips_invalid: testInitialFocusSkipsInvalidCandidates,
+  forward_reverse_wrap: testForwardAndReverseWrap,
+  outside_focus_redirect: testOutsideFocusRedirects,
+  opener_restoration_after_sync_focus: testOpenerRestoresAfterSynchronousAppFocus,
+  repeated_workspace_mounted_idempotent: testRepeatedWorkspaceMountedIsIdempotent,
+  workspace_removal_restores_state: testWorkspaceRemovalRestoresState,
+  positioned_dialog_does_not_mark_positioned_ancestor:
+    testPositionedDialogDoesNotMarkPositionedAncestor,
+};
+
+if (!cases[caseName]) {
+  throw new Error(`unknown modal layer harness case: ${caseName}`);
+}
+
+cases[caseName]();
+console.log(JSON.stringify({ ok: true, case: caseName }));
diff --git a/tests/test_convey_modal_layer_js.py b/tests/test_convey_modal_layer_js.py
new file mode 100644
index 000000000..d4a511023
--- /dev/null
+++ b/tests/test_convey_modal_layer_js.py
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2026 sol pbc
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+MODAL_LAYER_JS = REPO_ROOT / "solstone" / "convey" / "static" / "modal_layer.js"
+HARNESS_JS = REPO_ROOT / "tests" / "js" / "modal_layer_harness.js"
+
+
+@pytest.mark.parametrize(
+    "case_name",
+    [
+        "visibility_shapes",
+        "activation_deactivation",
+        "inert_restoration",
+        "initial_focus_skips_invalid",
+        "forward_reverse_wrap",
+        "outside_focus_redirect",
+        "opener_restoration_after_sync_focus",
+        "repeated_workspace_mounted_idempotent",
+        "workspace_removal_restores_state",
+        "positioned_dialog_does_not_mark_positioned_ancestor",
+    ],
+)
+def test_modal_layer_behavior(case_name: str) -> None:
+    node = shutil.which("node")
+    if node is None:
+        pytest.skip("node not available")
+
+    result = subprocess.run(
+        [node, str(HARNESS_JS), str(MODAL_LAYER_JS), case_name],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0, result.stderr
diff --git a/tests/test_convey_shell_chrome.py b/tests/test_convey_shell_chrome.py
index 393adf5a8..c05d4b41d 100644
--- a/tests/test_convey_shell_chrome.py
+++ b/tests/test_convey_shell_chrome.py
@@ -12,6 +12,9 @@ LIVE_MOBILE_MENU_MEDIA_ANCHOR = (
 MOBILE_BARE_FACET_AFTER_ANCHOR = "\n  .facet-bar::after {\n"
 MOBILE_MENU_FULL_FACET_AFTER_ANCHOR = "\n  body.menu-full .facet-bar::after {\n"
 SURFACE_STATE_DESC_ANCHOR = "\n.surface-state-desc {\n"
+ACTIVE_DIALOG_MARKER_SELECTOR = (
+    "[data-convey-active-dialog],\n[data-convey-active-dialog-host]"
+)
 
 
 def _class_specificity(selector: str) -> int:
@@ -81,6 +84,37 @@ def test_surface_state_heading_keeps_existing_gray():
     assert "color: #4b5563;" in rule
 
 
+def test_active_dialog_z_token_sits_above_shell_tags():
+    css = APP_CSS_PATH.read_text(encoding="utf-8")
+    _, root_rule = _rule_block(css, ":root")
+
+    assert "--z-tags: 400;" in root_rule
+    assert "--z-active-dialog: 10000;" in root_rule
+    assert ".skip-link (9999)" in root_rule
+    assert "presentation-mode body::after (9998)" in root_rule
+    assert "click-to-exit pseudo-element" in root_rule
+    assert root_rule.index("--z-tags: 400;") < root_rule.index(
+        "--z-active-dialog: 10000;"
+    )
+
+
+def test_workspace_view_transition_is_disabled_while_managed_dialog_is_open():
+    css = APP_CSS_PATH.read_text(encoding="utf-8")
+    _, workspace_rule = _rule_block(css, ".workspace")
+    _, active_rule = _rule_block(css, "body.has-managed-dialog .workspace")
+
+    assert "view-transition-name: workspace;" in workspace_rule
+    assert "view-transition-name: none;" in active_rule
+
+
+def test_active_dialog_marker_uses_active_dialog_z_token():
+    css = APP_CSS_PATH.read_text(encoding="utf-8")
+    _, marker_rule = _rule_block(css, ACTIVE_DIALOG_MARKER_SELECTOR)
+
+    assert "App workspace <style> blocks load after app.css" in marker_rule
+    assert "z-index: var(--z-active-dialog) !important;" in marker_rule
+
+
 def test_mobile_menu_full_facet_bar_separator_override_wins_by_source_order():
     css = APP_CSS_PATH.read_text(encoding="utf-8")
     desktop_selector = "body.menu-full .facet-bar::after"
diff --git a/tests/test_convey_spa_shell.py b/tests/test_convey_spa_shell.py
index af290626a..d2ad119f9 100644
--- a/tests/test_convey_spa_shell.py
+++ b/tests/test_convey_spa_shell.py
@@ -27,6 +27,7 @@ BOOT_PATH_FILES = [
     CONVEY_STATIC / "date_format.js",
     CONVEY_STATIC / "chat_chrome.js",
     CONVEY_STATIC / "status_pane.js",
+    CONVEY_STATIC / "modal_layer.js",
     CONVEY_STATIC / "presentation_mode.js",
     CONVEY_STATIC / "menu_state.js",
 ]
-- 
2.51.2