visualdynamics.gui.report_editor

report_editor

The report editor: the exported page as the preview, the acts on the bar.

The page shown is the very HTML the export writes — a browser view of exactly what the reader will get, figures drawn by the same JavaScript their browser will run — and it does two things the export's page does not: it frames the selected block, and it says which block was clicked. Everything else lives in Qt (Brandon, 2026-09-08: "the toolbar should be the same as the task bar at the top of the report screen how we have for every other GUI object"): a bar of acts above the page — Insert, Reference, Move Up, Move Down, Delete, Export — and a settings pane beside it carrying what the selected block has to say: a figure block's sources and caption, a text block's Markdown in a Qt editor, the report's title and marking when nothing is selected. Every act is one operation on the Report model, journaled by the window, followed by a re-render of the page; the exported file never carries any chrome.

Classes:

Name	Description
ReportEditor	Owns the web view, the bar and the pane; mutates the report the

Classes

ReportEditor

ReportEditor(parent: QWidget | None = None)

Bases: QWidget

Owns the web view, the bar and the pane; mutates the report the operations describe.

Methods:

Name	Description
insert	Insert a block of kind after the selected block, or at the
insert_reference	{{figure:caption}} or {{table:caption}} at the text
flush_text	Land the text editor's Markdown on the block now — what the
stand_down	Leave the page with nothing for the view's destructor to wait on.

Source code in src/visualdynamics/gui/report_editor.py

def __init__(self, parent: QWidget | None = None) -> None:
    super().__init__(parent)
    self.report: Any = None
    #: callables the window sets, so the editor reads the project
    #: as it stands rather than a copy taken when it opened
    self.objects: Callable[[], dict[str, Any]] | None = None
    self.object_groups: Callable[[], list[Any]] | None = None
    self.unit_system: Any = None
    #: the block the bar and the pane act on, or None for the report
    self.selected: int | None = None
    #: (label, caption) for every numbered figure and table, from
    #: the last render — the Reference menu's offer
    self._labels: list[tuple[str, str]] = []
    layout = QVBoxLayout(self)
    layout.setContentsMargins(0, 0, 0, 0)
    layout.setSpacing(0)
    self.toolbar: QToolBar = self._build_toolbar()
    layout.addWidget(self.toolbar)
    self.split: QSplitter = QSplitter(Qt.Orientation.Horizontal)
    self.view: QWebEngineView = QWebEngineView()
    #: the page, made here and owned here rather than by the view:
    #: a view deletes a page it made itself in the same call that
    #: detaches it (`QWebEngineViewPrivate::bindPageAndView`), so
    #: its live web contents were always torn down with the widget
    #: they drew into still standing — the hang `stand_down` exists
    #: for. A page the view does not own is only detached by
    #: `setPage(None)`, and its teardown can be sequenced.
    self.page: QWebEnginePage = QWebEnginePage(self)
    self.view.setPage(self.page)
    #: the loadFinished slot of the navigation in flight, if any
    self._restore = None
    #: the one timer that scrolls a freshly loaded page back to
    #: where it was — held, so standing down can stop it: a bare
    #: single-shot could still fire its script into a page in the
    #: middle of being discarded (the gate's stall, 2026-09-19)
    self._scroll_timer: QTimer = QTimer(self.view)
    self._scroll_timer.setSingleShot(True)
    self._scroll_timer.setInterval(50)
    self._scroll_timer.timeout.connect(self._scroll_back)
    self._scroll_to: int = 0
    self.split.addWidget(self.view)
    self.pane: QScrollArea = QScrollArea()
    self.pane.setWidgetResizable(True)
    self.pane.setMinimumWidth(240)
    self.split.addWidget(self.pane)
    self.split.setStretchFactor(0, 3)
    self.split.setStretchFactor(1, 1)
    self.split.setSizes([900, 300])
    layout.addWidget(self.split, 1)
    self.bridge: _Bridge = _Bridge(self)
    self.bridge.operated.connect(self._operate)
    self.channel: QWebChannel = QWebChannel(self)
    self.channel.registerObject('bridge', self.bridge)
    self.page.setWebChannel(self.channel)
    self._scroll = 0
    self._page_path = None
    self._channel_js = None
    #: the project changed while this page was not on screen; the
    #: window rebuilds before showing it again rather than paying
    #: 254 ms per change for a document nobody is looking at
    self.stale: bool = False
    #: what stopped the last build, or None: a page that could not
    #: be built says so instead of staying white
    self.failure: str | None = None
    # the pane's widgets, rebuilt when the selection changes; None
    # while the selection has no such field
    self.text_editor: QPlainTextEdit | None = None
    self.caption_edit: QLineEdit | None = None
    self.title_edit: QLineEdit | None = None
    self.marking_edit: QLineEdit | None = None
    self.color_box: QComboBox | None = None
    self.field_boxes: dict[str, QComboBox] = {}
    self._loading_pane = False
    self._text_timer: QTimer = QTimer(self)
    self._text_timer.setSingleShot(True)
    self._text_timer.setInterval(TEXT_DEBOUNCE_MS)
    self._text_timer.timeout.connect(self.flush_text)
    self._show_selection()

Methods:

insert

insert(kind: str) -> None

Insert a block of kind after the selected block, or at the end, and select it.

Source code in src/visualdynamics/gui/report_editor.py

def insert(self, kind: str) -> None:
    """Insert a block of `kind` after the selected block, or at the
    end, and select it."""
    if self.report is None:
        return
    at = (self.selected + 1 if self.selected is not None
          else self.report.num_blocks)
    self._operate({'op': 'insert', 'at': at, 'kind': kind})

insert_reference

insert_reference(kind: str, caption: str) -> None

{{figure:caption}} or {{table:caption}} at the text editor's cursor — the token the model stores, renumbered by the same code that numbers the page.

Source code in src/visualdynamics/gui/report_editor.py

def insert_reference(self, kind: str, caption: str) -> None:
    """`{{figure:caption}}` or `{{table:caption}}` at the text
    editor's cursor — the token the model stores, renumbered by
    the same code that numbers the page."""
    if self.text_editor is None:
        return
    self.text_editor.textCursor().insertText(f'{{{{{kind}:{caption}}}}}')
    self.text_editor.setFocus()

flush_text

flush_text() -> None

Land the text editor's Markdown on the block now — what the debounce does after typing rests, and what a test calls.

Source code in src/visualdynamics/gui/report_editor.py

def flush_text(self) -> None:
    """Land the text editor's Markdown on the block now — what the
    debounce does after typing rests, and what a test calls."""
    self._text_timer.stop()
    if (self.text_editor is None or self.report is None
            or self.selected is None
            or not 0 <= self.selected < self.report.num_blocks):
        return
    text = self.text_editor.toPlainText()
    if text == self.report.blocks[self.selected].get('text', ''):
        return
    self._operate({'op': 'field', 'at': self.selected, 'field': 'text',
                   'value': text})

stand_down

stand_down() -> None

Leave the page with nothing for the view's destructor to wait on.

A QWebEngineView destroyed while its page is live blocked the whole process: Chromium's teardown waits on the render process in a synchronous mach_msg call that never returned. That was the gate's "stall at 98 %" — sampled on 2026-09-18 with a worker's main thread parked inside QtWebEngineCore, and then named exactly by a faulthandler dump: the window fixture delivering the deferred delete to a window whose report page had just finished loading. Stopping a navigation in flight (the first cut of this) was not enough; a loaded, rendering page hangs the destructor just the same.

The cure is Qt's own: a hidden page can be discarded — its render process shut down gracefully, the page unloaded — and a discarded page is destroyed in a millisecond (measured: the destructor went from a hang to 0.001 s). So the view is hidden, the page discarded, and the events that carry the change are pumped before the caller goes on to destroy anything. The scroll-restoring slot of a navigation in flight is dropped too, since it would fire into the discarded page.

Then the discard itself hung (2026-09-28, a stack this time: setLifecycleState(Discarded) never returning from WebContentsAdapter::discard()). Qt's source says why it can: discard asks the render process to shut down and then destroys the live web contents synchronously, right there — the same teardown the destructor did — while the page is still bound to the widget it drew into, with that widget's compositor and surfaces alive to be waited on. The view's destructor never did better: it deletes an owned page in the very call that detaches it. So the page is detached from the view first, the events that carry the widget away are pumped, and only then is the page discarded, with nothing left to wait on but the renderer it is asking to leave. Which is a mechanism, not a witnessed cure — the hang wants a starved machine and never reproduced alone — so the log still records each step.

Source code in src/visualdynamics/gui/report_editor.py

def stand_down(self) -> None:
    """Leave the page with nothing for the view's destructor to wait on.

    A `QWebEngineView` destroyed while its page is live blocked the
    whole process: Chromium's teardown waits on the render process
    in a synchronous `mach_msg` call that never returned. That was
    the gate's "stall at 98 %" — sampled on 2026-09-18 with a
    worker's main thread parked inside QtWebEngineCore, and then
    named exactly by a faulthandler dump: the window fixture
    delivering the deferred delete to a window whose report page
    had *just finished* loading. Stopping a navigation in flight
    (the first cut of this) was not enough; a loaded, rendering
    page hangs the destructor just the same.

    The cure is Qt's own: a hidden page can be *discarded* — its
    render process shut down gracefully, the page unloaded — and
    a discarded page is destroyed in a millisecond (measured: the
    destructor went from a hang to 0.001 s). So the view is
    hidden, the page discarded, and the events that carry the
    change are pumped before the caller goes on to destroy
    anything. The scroll-restoring slot of a navigation in flight
    is dropped too, since it would fire into the discarded page.

    Then the discard itself hung (2026-09-28, a stack this time:
    `setLifecycleState(Discarded)` never returning from
    `WebContentsAdapter::discard()`). Qt's source says why it can:
    discard asks the render process to shut down and then destroys
    the live web contents synchronously, right there — the same
    teardown the destructor did — while the page is still bound
    to the widget it drew into, with that widget's compositor and
    surfaces alive to be waited on. The view's destructor never
    did better: it deletes an owned page in the very call that
    detaches it. So the page is detached from the view *first*,
    the events that carry the widget away are pumped, and only
    then is the page discarded, with nothing left to wait on but
    the renderer it is asking to leave. Which is a mechanism, not
    a witnessed cure — the hang wants a starved machine and never
    reproduced alone — so the log still records each step.
    """
    from PySide6.QtWidgets import QApplication

    page = self.page
    # the witness the stall's record asks for (PLAN.md "The 98 %
    # stall, named"): the page's state at the moment of the
    # discard, on the debug log — the faulthandler dump names the
    # line and not the page
    _log.debug('stand_down: loading=%s state=%s restore=%s scroll_timer=%s',
               page.isLoading(), page.lifecycleState(),
               self._restore is not None, self._scroll_timer.isActive())
    if self._restore is not None:
        with contextlib.suppress(RuntimeError, TypeError):
            self.view.loadFinished.disconnect(self._restore)
        self._restore = None
    self._scroll_timer.stop()
    self.view.stop()
    self.view.hide()
    # detached before discarded: the view forgets a page it does
    # not own without deleting it, and the widget the page drew
    # into goes away on the events pumped here
    self.view.setPage(None)
    for _ in range(20):
        QApplication.processEvents()
    _log.debug('stand_down: detached')
    with contextlib.suppress(RuntimeError):
        page.setLifecycleState(QWebEnginePage.LifecycleState.Discarded)
    _log.debug('stand_down: discarded, state=%s', page.lifecycleState())
    for _ in range(20):
        QApplication.processEvents()

Functions: