ms-components 0.3.3__tar.gz → 0.3.5__tar.gz

{ms_components-0.3.3/src/ms_components.egg-info → ms_components-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ms_components
-Version: 0.3.3
+Version: 0.3.5
 Summary: PySide6 UI components for MolSuite: smart table, project browser, job monitor, PyMOL dock, steppers.
 Author: Mario S. Valdés-Tresanco, Mario E. Valdés-Tresanco
 License-Expression: MIT

{ms_components-0.3.3 → ms_components-0.3.5}/docs/index.md

@@ -21,7 +21,7 @@ pip install ms_components
 | `ms_components.ms_table` | Declarative, paginated table over SQLModel |
 | `ms_components.ms_monitor` | Job monitor for an `ms_flow` workspace: cancel, resume, move |
 | `ms_components.ms_executors` | Hosts and executors: Settings pages and the panel that starts them |
-| `ms_components.ms_projects` | Project browser and project menu |
+| [`ms_components.ms_projects`](project_form_events.md) | Project browser, project menu, and form lifecycle events |
 | `ms_components.ms_settings` | Typed editor for application settings |
 | `ms_components.ms_pymol` | PyMOL dock and control bar |
 | `ms_components.ms_stepper` | Step-by-step wizard widget |

{ms_components-0.3.3 → ms_components-0.3.5}/docs/ms_tutorial.md

@@ -90,6 +90,14 @@ window.tutorials.start(overview)
   without resetting application data. Multiple queued copies of an old event do
   not complete a later step, even if both steps use the same signal.
 
+For asynchronous operations that may finish while the user has gone Back, supply
+`TutorialEvent(signal, accept=..., is_complete=lambda: cached_result_is_ready)`.
+The controller checks `is_complete` when entering an unfinished step and advances
+if it returns true. The application records successful completion before emitting
+its signal; the callback reads that state, without blocking or querying a database.
+`accept` validates incoming signal arguments; `is_complete` independently checks
+the operation and result that the step requires.
+
 `TutorialEvent.signal` also accepts a zero-argument resolver for signals belonging
 to dialogs or controls that are recreated. It is resolved when entering the step.
 
@@ -118,6 +126,18 @@ the application automatically. Hidden targets temporarily hide the overlay; an
 initial hidden target without an existing overlay fails with a diagnostic. Missing
 or deleted targets and callback failures stop the tour and emit `failed`.
 
+Call the public `controller.refresh()` after an application UI change when the
+spotlight should update immediately. Normal tracking continues automatically.
+Accepting a host `QDialog` preserves the tutorial so its target can move back to
+the parent window; closing or rejecting the host still cancels the tutorial.
+
+`TutorialController(dim_background=False)` preserves the application's background
+colors and draws only the target outline. Input gating remains the same.
+`instruction_provider=lambda step: current_instruction` supplies dynamic plain-text
+instructions. They are measured again only when their text changes, without
+resetting the reader's scroll position on every tracking tick. These options do not
+depend on any application or project package.
+
 Lifecycle signals:
 
 | Signal | Arguments |

ms_components-0.3.5/docs/project_form_events.md

@@ -0,0 +1,17 @@
+# Project form events
+
+`ProjectsMenuWidget` and `ProjectBrowserPanel` emit
+`project_form_opened(ProjectFormDialog)` before entering a create/edit form's modal
+loop. The form's `mode` is `"create"` or `"edit"`. Hosts can bind controls and
+observe the normal `accepted`, `rejected`, and `finished` Qt signals without
+searching the browser's widget tree or replacing its actions.
+
+`ProjectFormDialog` is exported from `ms_components.ms_projects`. Its public
+controls include `name_input`, `path_input`, `path_row`, `browse_button`, and
+`save_button`. `name_committed(str)` emits the trimmed name when editing finishes.
+`path_selected(str)` emits only when Browse confirms a folder, including selecting
+the current folder again. Cancelling the chooser emits no selection event.
+
+`project_created(project_id)` means that project creation succeeded. It remains
+separate from opening the form or accepting its fields, which may still be followed
+by a backend error. None of these APIs depend on `ms_tutorial` or a host application.

ms_components-0.3.5/src/ms_components/ms_projects/__init__.py

@@ -0,0 +1,4 @@
+from .browser import ProjectBrowserPanel, ProjectBrowserWindow, ProjectFormDialog
+from .widget import ProjectsMenuWidget
+
+__all__ = ["ProjectBrowserPanel", "ProjectBrowserWindow", "ProjectFormDialog", "ProjectsMenuWidget"]

{ms_components-0.3.3 → ms_components-0.3.5}/src/ms_components/ms_projects/browser.py

@@ -988,6 +988,9 @@ class StatsDialog(QDialog):
 
 
 class ProjectFormDialog(QDialog):
+    name_committed = Signal(str)
+    path_selected = Signal(str)
+
     def __init__(self, *, apps: list, mode: str,
                  initial_data: dict | None = None,
                  allow_app_selection: bool = True, parent=None):
@@ -1005,6 +1008,7 @@ class ProjectFormDialog(QDialog):
         layout = QVBoxLayout(self)
         form = QFormLayout()
         self.name_input        = QLineEdit(self.initial_data.get("name", ""))
+        self.name_input.editingFinished.connect(lambda: self.name_committed.emit(self.name_input.text().strip()))
         self.path_input        = QLineEdit(str(self.initial_data.get("path", "")))
         self.path_input.setReadOnly(True)
         self.description_input = QTextEdit(self.initial_data.get("description", ""))
@@ -1022,11 +1026,11 @@ class ProjectFormDialog(QDialog):
             idx = self.app_combo.findData(cid)
             if idx >= 0: self.app_combo.setCurrentIndex(idx)
         self.app_combo.setEnabled(self.allow_app_selection and not is_edit)
-        path_row = QWidget()
+        path_row = self.path_row = QWidget()
         pl = QHBoxLayout(path_row)
         pl.setContentsMargins(0,0,0,0)
         pl.addWidget(self.path_input)
-        browse_btn = QPushButton("Browse...")
+        browse_btn = self.browse_button = QPushButton("Browse...")
         browse_btn.clicked.connect(self._on_browse)
         browse_btn.setEnabled(not is_edit)
         pl.addWidget(browse_btn)
@@ -1037,6 +1041,7 @@ class ProjectFormDialog(QDialog):
         form.addRow("Description:", self.description_input)
         layout.addLayout(form)
         btns = QDialogButtonBox(QDialogButtonBox.Save | QDialogButtonBox.Cancel)
+        self.save_button = btns.button(QDialogButtonBox.Save)
         btns.accepted.connect(self.accept)
         btns.rejected.connect(self.reject)
         layout.addWidget(btns)
@@ -1045,7 +1050,9 @@ class ProjectFormDialog(QDialog):
         folder = QFileDialog.getExistingDirectory(
             self, "Select folder",
             self.path_input.text().strip() or str(Path.home()))
-        if folder: self.path_input.setText(folder)
+        if folder:
+            self.path_input.setText(folder)
+            self.path_selected.emit(folder)
 
     def accept(self):
         if not self.name_input.text().strip():
@@ -1091,6 +1098,7 @@ class StatTile(QFrame):
 class ProjectBrowserPanel(QWidget):
     project_requested = Signal(str)
     project_created   = Signal(str)
+    project_form_opened = Signal(object)
     projects_changed  = Signal()
 
     def __init__(self, *, app_id: str | None = None, header_title: str,
@@ -1288,6 +1296,7 @@ class ProjectBrowserPanel(QWidget):
                           "description": raw.description, "tags": raw.tags,
                           "app_id": raw.app_id},
             allow_app_selection=self._dialog_allows_app_selection(), parent=self)
+        self.project_form_opened.emit(dlg)
         if dlg.exec() != QDialog.Accepted:
             return
         data = dlg.get_data()
@@ -1355,6 +1364,7 @@ class ProjectBrowserPanel(QWidget):
             initial_data={"path": str(Path.home()/"molsuite_projects"),
                           "app_id": self._active_tool_app_id or apps[0].app_id},
             allow_app_selection=self._dialog_allows_app_selection(), parent=self)
+        self.project_form_opened.emit(dlg)
         if dlg.exec() != QDialog.Accepted:
             return
         fd = dlg.get_data()

{ms_components-0.3.3 → ms_components-0.3.5}/src/ms_components/ms_projects/widget.py

@@ -38,6 +38,7 @@ def _project_color(index: int) -> str:
 class ProjectsMenuWidget(QFrame):
     project_requested = Signal(str)
     project_created = Signal(str)
+    project_form_opened = Signal(object)
     # The host app's open project was confirmed for deletion: the host closes it, then deletes it.
     active_project_delete_requested = Signal(str)
 
@@ -173,6 +174,7 @@ class ProjectsMenuWidget(QFrame):
             allow_app_selection=self.allow_app_selection,
             parent=self,
         )
+        self.project_form_opened.emit(dialog)
         if dialog.exec() != ProjectFormDialog.Accepted:
             return
         data = dialog.get_data()
@@ -224,6 +226,7 @@ class ProjectsMenuWidget(QFrame):
             allow_app_selection=False,
             parent=self,
         )
+        self.project_form_opened.emit(dialog)
         if dialog.exec() != ProjectFormDialog.Accepted:
             return
         data = dialog.get_data()

{ms_components-0.3.3 → ms_components-0.3.5}/src/ms_components/ms_pymol/__init__.py

@@ -1,5 +1,6 @@
 from .widget import (
     COMPARISON_COLORS,
+    associate_scene_objects,
     PymolControlBar,
     PymolDockWidget,
     PymolPresetSpec,
@@ -8,6 +9,7 @@ from .widget import (
 
 __all__ = [
     "COMPARISON_COLORS",
+    "associate_scene_objects",
     "PymolControlBar",
     "PymolDockWidget",
     "PymolPresetSpec",

ms_components-0.3.5/src/ms_components/ms_pymol/icons/hydrogens-polar.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="2" y="2" width="20" height="20" rx="5"/>
+  <path d="M7 7v10M13 7v10M7 12h6"/>
+  <path d="M16 12V7h1.5a1.5 1.5 0 0 1 0 3H16" stroke-width="1.2"/>
+</svg>

ms_components-0.3.5/src/ms_components/ms_pymol/icons/hydrogens.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="2" y="2" width="20" height="20" rx="5"/>
+  <path d="M8 7v10M16 7v10M8 12h8"/>
+</svg>

{ms_components-0.3.3 → ms_components-0.3.5}/src/ms_components/ms_pymol/widget.py

@@ -39,6 +39,8 @@ from . import plugins as _pymol_plugins  # noqa: F401
 
 
 class _PymolGLWidget(PyMOLGLWidget):
+    before_render = Signal()
+
     def __init__(self, parent):
         super().__init__(parent)
         self._opengl_error: str | None = None
@@ -69,6 +71,7 @@ class _PymolGLWidget(PyMOLGLWidget):
 
     def paintGL(self):
         if self._opengl_error is None:
+            self.before_render.emit()
             super().paintGL()
 
     def resizeGL(self, width, height):
@@ -123,6 +126,7 @@ class PymolPresetSpec:
     callback: Callable[[Any, PymolSceneContext], None]
     contexts: frozenset[str] = field(default_factory=frozenset)
     tooltip: str = ""
+    per_grid_slot: bool = False
 
     def supports(self, context_kind: str) -> bool:
         return not self.contexts or str(context_kind) in self.contexts
@@ -138,6 +142,14 @@ def _builtin_preset(method_name: str):
     return apply
 
 
+def associate_scene_objects(cmd, objects, *, reference: str) -> None:
+    """Keep generated interactions/geometry in their structure's comparison panel."""
+    slot = cmd.get_setting_int("grid_slot", reference)
+    for obj in objects:
+        if cmd.get_type(obj) != "object:group":
+            cmd.set("grid_slot", slot, obj)
+
+
 class PymolControlBar(QFrame):
     """Compact, reusable controls for an embedded PyMOL scene."""
 
@@ -150,7 +162,9 @@ class PymolControlBar(QFrame):
         self._cmd = cmd
         self._context = PymolSceneContext()
         self._grid_label_objects: set[str] = set()
+        self._preset_objects: set[str] = set()
         self._comparison_layout = "grid"
+        self._hydrogen_mode = "none"
         self._presets: dict[str, PymolPresetSpec] = {}
         self.setObjectName("PymolControlBar")
 
@@ -246,6 +260,14 @@ class PymolControlBar(QFrame):
             menu=hide_menu,
         )
 
+        self.hydrogens_action = self._add_toolbar_action(
+            "Hydrogens", "hydrogens.svg",
+            "Hydrogens: hidden. Click to show all H in this PyMOL session.",
+            self.toggle_hydrogens,
+            checkable=True,
+        )
+        self.hydrogens_action.setData("none")
+
         self.preset_menu = QMenu("Presets", bar)
         self.preset_action = self._add_toolbar_action(
             "Presets", "presets.svg",
@@ -264,6 +286,7 @@ class PymolControlBar(QFrame):
         self._sync_selection_mode()
         self.refresh_context_label()
         self._refresh_preset_menu()
+        self.apply_hydrogen_visibility()
         self._configure_overflow_button()
         if self._cmd is None:
             self.setEnabled(False)
@@ -443,6 +466,7 @@ class PymolControlBar(QFrame):
         self.comparison_menu.menuAction().setVisible(normalized.is_comparison)
         if was_comparison or normalized.is_comparison:
             self._run_command("Grid labels", self._sync_grid_labels)
+        self.apply_hydrogen_visibility()
         self.refresh_context_label()
         self._refresh_preset_menu()
 
@@ -473,7 +497,7 @@ class PymolControlBar(QFrame):
             self._cmd.set("grid_mode", int(self._comparison_layout == "grid"))
             slot_names: dict[int, list[str]] = {}
             for obj in self._cmd.get_object_list(self._context.target):
-                if obj in self._grid_label_objects:
+                if obj in self._grid_label_objects or obj in self._preset_objects:
                     continue
                 slot = self._cmd.get_setting_int("grid_slot", obj)
                 if slot > 0:
@@ -555,6 +579,10 @@ class PymolControlBar(QFrame):
                 self._cmd.color(color, f"({temporary}) and elem C")
                 self._cmd.delete(name)
                 self._cmd.set_name(temporary, name)
+                for obj in self._preset_objects & set(self._cmd.get_names("objects")):
+                    if self._cmd.get_setting_int("grid_slot", obj) == slot:
+                        self._cmd.delete(obj)
+                        self._preset_objects.discard(obj)
                 self._context = replace(
                     self._context, grid_labels={**self._context.grid_labels, slot: label},
                 )
@@ -623,6 +651,7 @@ class PymolControlBar(QFrame):
         def apply() -> None:
             self._cmd.hide("everything", target)
             self._cmd.show(normalized, target)
+            self.apply_hydrogen_visibility()
 
         self._run_command(f"Display {normalized}", apply)
 
@@ -636,6 +665,41 @@ class PymolControlBar(QFrame):
             lambda: self._cmd.hide(normalized, self.active_target()),
         )
 
+    def toggle_hydrogens(self) -> None:
+        previous = self._hydrogen_mode
+        modes = ("none", "all", "polar")
+        self._hydrogen_mode = modes[(modes.index(previous) + 1) % len(modes)]
+        if not self.apply_hydrogen_visibility():
+            self._hydrogen_mode = previous
+        mode = self._hydrogen_mode
+        icon = "hydrogens-polar.svg" if mode == "polar" else "hydrogens.svg"
+        self._toolbar_action_icons[self.hydrogens_action] = icon
+        self.hydrogens_action.setIcon(self._toolbar_icon(icon))
+        self.hydrogens_action.setChecked(mode != "none")
+        self.hydrogens_action.setData(mode)
+        state, next_state = {
+            "none": ("hidden", "show all H"),
+            "all": ("all H", "show only polar H"),
+            "polar": ("polar H only (bonded to N, O or S)", "hide all H"),
+        }[mode]
+        self.hydrogens_action.setToolTip(
+            f"Hydrogens: {state}. Click to {next_state} in this PyMOL session."
+        )
+
+    def apply_hydrogen_visibility(self) -> bool:
+        # Enforce the session policy before drawing, including externally loaded objects.
+        polar = "hydro and neighbor (elem N+O+S)"
+        shown = {"none": "", "all": "hydro", "polar": polar}[self._hydrogen_mode]
+        hidden = {"none": "hydro", "all": "", "polar": f"hydro and not ({polar})"}[self._hydrogen_mode]
+
+        def apply() -> None:
+            if hidden and self._cmd.count_atoms(f"({hidden}) and visible"):
+                self._cmd.hide("everything", hidden)
+            if shown and self._cmd.count_atoms(f"({shown}) and not rep sticks"):
+                self._cmd.show("sticks", shown)
+
+        return self._run_command("Hydrogens", apply)
+
     def clear_selection(self) -> None:
         if self._run_command("Clear selection", self._cmd.deselect):
             self.refresh_context_label()
@@ -695,7 +759,38 @@ class PymolControlBar(QFrame):
             )
 
         def apply() -> None:
-            spec.callback(self._cmd, self._context)
+            existing = set(self._cmd.get_names("objects"))
+            for obj in self._preset_objects & existing:
+                self._cmd.delete(obj)
+            self._preset_objects.clear()
+            if self._context.is_comparison and spec.per_grid_slot:
+                slots: dict[int, list[str]] = {}
+                source = " or ".join(f"({s})" for s in self._context.selections.values() if s) or self._context.target
+                for obj in self._cmd.get_object_list(source):
+                    if obj not in self._grid_label_objects:
+                        slot = self._cmd.get_setting_int("grid_slot", obj)
+                        if slot > 0:
+                            slots.setdefault(slot, []).append(obj)
+                if not slots:
+                    spec.callback(self._cmd, self._context)
+                for slot, objects in sorted(slots.items()):
+                    target = " or ".join(objects)
+                    context = replace(
+                        self._context, target=target,
+                        selections={role: f"({selection}) and ({target})"
+                                    for role, selection in self._context.selections.items()},
+                    )
+                    before = set(self._cmd.get_names("objects"))
+                    spec.callback(self._cmd, context)
+                    for obj in set(self._cmd.get_names("objects")) - before:
+                        # PyMOL reuses names such as polar_contacts on its next preset call.
+                        name = self._cmd.get_unused_name(f"{obj}_slot{slot}")
+                        self._cmd.set_name(obj, name)
+                        self._preset_objects.add(name)
+                        associate_scene_objects(self._cmd, [name], reference=objects[0])
+            else:
+                spec.callback(self._cmd, self._context)
+            self.apply_hydrogen_visibility()
             if self._context.is_comparison:
                 self._sync_grid_labels()
 
@@ -714,6 +809,7 @@ class PymolControlBar(QFrame):
                 key=key,
                 label=label,
                 callback=_builtin_preset(method),
+                per_grid_slot=True,
             )
 
     def _sync_selection_mode(self) -> None:
@@ -781,6 +877,7 @@ class PymolDockWidget(MSDockWidget):
             self.cmd.set("internal_gui", False)
 
         self.control_bar = PymolControlBar(self.cmd, self)
+        self.pymol_widget.before_render.connect(self.control_bar.apply_hydrogen_visibility)
         self.toolbar = self.control_bar
         self.pymol_widget.installEventFilter(self)
 
@@ -899,6 +996,7 @@ class PymolDockWidget(MSDockWidget):
 
 __all__ = [
     "COMPARISON_COLORS",
+    "associate_scene_objects",
     "PymolControlBar",
     "PymolDockWidget",
     "PymolPresetSpec",

{ms_components-0.3.3 → ms_components-0.3.5}/src/ms_components/ms_table/__init__.py

@@ -40,9 +40,11 @@ from .table_config import (
     DEFAULT_PAGE_SIZES,
 )
 from .table_model import SmartTableModel
+from .table_interaction import TableInteraction
 
 __all__ = [
     "SmartTableView",
+    "TableInteraction",
     "SessionProvider",
     "TableConfig",
     "ToolbarAction",

{ms_components-0.3.3 → ms_components-0.3.5}/src/ms_components/ms_table/query_builder.py

@@ -24,6 +24,10 @@ from .table_config import (
 )
 
 
+# Past this many rows a DuckDB seek numbers the rows instead of an ORDER BY + OFFSET.
+DUCKDB_RANK_FROM = 100_000
+
+
 class QueryBuilder:
     """Builds and runs paginated queries from a TableConfig.
 
@@ -147,7 +151,8 @@ class QueryBuilder:
             return []
         stmt = self._build_base_statement().with_only_columns(pk)
         with self._db.get_session() as session:
-            return [int(value) for value in session.exec(stmt).all() if value is not None]
+            # scalars(): with expr columns the base select has several entities and exec() yields Rows.
+            return [int(value) for value in session.scalars(stmt).all() if value is not None]
 
     def count(self) -> int:
         """Row total under the current filters/search, without fetching any row.
@@ -205,19 +210,51 @@ class QueryBuilder:
         has_more = len(raw) > self._page_size
         return [self._row_to_dict(row) for row in raw[:self._page_size]], has_more
 
-    def fetch_window_at(self, page_index: int) -> tuple[list[dict], bool]:
+    def fetch_window_at(self, page_index: int, anchor: tuple[Any, Any] | None = None,
+                        anchor_page: int = 0) -> tuple[list[dict], bool]:
         """Direct load for a scrollbar jump to a page that has not been walked yet.
 
-        The normal path is still keyset via :meth:`fetch_window_after`. OFFSET only
-        shows up when the user drags the scrollbar to a position with no known
-        cursor.
+        `anchor` is the keyset cursor that starts `anchor_page` (None = the top). The
+        walk from it to the target reads only (sort value, pk) - never whole rows -
+        and then the page itself is a keyset seek, so jumping to the end of a 4M-row
+        table no longer materializes 4M rows.
         """
-        offset = max(0, int(page_index)) * self._page_size
-        stmt = self._build_base_statement().offset(offset).limit(self._page_size + 1)
+        offset = max(0, int(page_index) - int(anchor_page)) * self._page_size
+        if self._get_pk_attr() is None:  # no keyset possible: plain OFFSET
+            stmt = self._build_base_statement().offset(int(page_index) * self._page_size)
+            with self._db.get_session() as session:
+                raw = session.exec(stmt.limit(self._page_size + 1)).all()
+            return [self._row_to_dict(row) for row in raw[:self._page_size]], len(raw) > self._page_size
+        cursor = self._seek(anchor, offset) if offset else anchor
+        if offset and cursor is None:
+            return [], False  # past the end (rows vanished under the scrollbar)
+        return self.fetch_window_after(cursor)
+
+    def _seek(self, anchor: tuple[Any, Any] | None, offset: int) -> tuple[Any, Any] | None:
+        """Cursor of the `offset`-th row after `anchor`, reading only the key columns."""
+        pk = self._get_pk_attr()
+        attr = self._resolve_attr(self._sorts[0].field) if self._sorts else None
+        keys = [attr.label("_seek_sort") if attr is not None else None, pk.label("_seek_pk")]
+        stmt = self._build_base_statement()
+        clause = self._keyset_clause(anchor)
+        if clause is not None:
+            stmt = stmt.where(clause)
         with self._db.get_session() as session:
-            raw = session.exec(stmt).all()
-        has_more = len(raw) > self._page_size
-        return [self._row_to_dict(row) for row in raw[:self._page_size]], has_more
+            if offset > DUCKDB_RANK_FROM and session.get_bind().dialect.name == "duckdb":
+                # DuckDB turns ORDER BY + OFFSET into a top-N heap the size of the offset
+                # (2.3 s at 3.85M rows); numbering the rows sorts once (0.2-0.7 s), which
+                # loses to the heap on short walks. SQLite: OFFSET 0.3 s, row_number() 2 s.
+                rank = func.row_number().over(order_by=self._order_clauses()).label("_seek_rank")
+                inner = stmt.with_only_columns(*[k for k in keys if k is not None], rank) \
+                    .order_by(None).subquery()
+                row = session.execute(select(*[c for c in inner.c if c.name != "_seek_rank"])
+                                   .where(inner.c._seek_rank == offset)).first()
+            else:
+                row = session.execute(stmt.with_only_columns(*[k for k in keys if k is not None])
+                                   .offset(offset - 1).limit(1)).first()
+        if row is None:
+            return None
+        return (row[0], row[1]) if attr is not None else (None, row[0])
 
     def _keyset_clause(self, cursor: tuple[Any, Any] | None):
         if cursor is None:
@@ -240,20 +277,19 @@ class QueryBuilder:
             return or_(attr.is_not(None), rest_of_nulls) if not sort.descending else rest_of_nulls
         if sort.descending:
             return or_(attr < sort_value, and_(attr == sort_value, pk > pk_value), attr.is_(None))
-        return or_(attr > sort_value, and_(attr == sort_value, pk > pk_value))
+        # The redundant `attr >= value` is what lets SQLite seek the index when the values
+        # are bound parameters (without it: a SCAN, 0.2 s per page at 3.85M rows) and
+        # DuckDB prune row groups by zone map.
+        # ponytail: descending keeps its `IS NULL` arm and so its scan; same fix needs the
+        # null tail fetched as a second query.
+        return and_(attr >= sort_value, or_(attr > sort_value, and_(attr == sort_value, pk > pk_value)))
 
     def fetch(self) -> tuple[list[dict], int]:
         """Run the query and return (rows_as_dicts, total_count)."""
-        stmt      = self._build_base_statement()
-        count_stmt = self._build_count_statement()
         with self._db.get_session() as session:
-            total: int = session.exec(count_stmt).one()  # type: ignore[arg-type]
-
-            offset = (self._page - 1) * self._page_size
-            stmt   = stmt.offset(offset).limit(self._page_size)
+            total: int = session.exec(self._build_count_statement()).one()  # type: ignore[arg-type]
 
-            raw_rows = session.exec(stmt).all()
-            rows     = [self._row_to_dict(r) for r in raw_rows]
+        rows, _has_more = self.fetch_window_at(self._page - 1)
         return rows, total
 
     # ──────────────────────────────────────────
@@ -302,24 +338,20 @@ class QueryBuilder:
         if search_clause is not None:
             stmt = stmt.where(search_clause)
 
-        # ORDER BY
-        if self._sorts:
-            for sort in self._sorts:
-                attr = self._resolve_attr(sort.field)
-                if attr is not None:
-                    stmt = stmt.order_by(attr.desc() if sort.descending else attr.asc())
-            # PK tie-break: without it two rows with the same score have undefined
-            # order and the keyset cursor skips or repeats rows across pages.
-            pk = self._get_pk_attr()
-            if pk is not None:
-                stmt = stmt.order_by(pk)
-        else:
-            # Default order: primary key of the main table
-            pk = self._get_pk_attr()
-            if pk is not None:
-                stmt = stmt.order_by(pk)
+        return stmt.order_by(*self._order_clauses())
 
-        return stmt
+    def _order_clauses(self) -> list:
+        clauses = []
+        for sort in self._sorts:
+            attr = self._resolve_attr(sort.field)
+            if attr is not None:
+                clauses.append(attr.desc() if sort.descending else attr.asc())
+        # PK tie-break (and default order): without it two rows with the same score have
+        # undefined order and the keyset cursor skips or repeats rows across pages.
+        pk = self._get_pk_attr()
+        if pk is not None:
+            clauses.append(pk)
+        return clauses
 
     def _build_count_statement(self):
         model = self._config.model_class