flea-qml 0.0.0-stage → 0.1.0

package/ui/KindStack.qml

@@ -0,0 +1,40 @@
+import QtQuick
+import "." as Flea
+
+// The marks a multi-selection stacks in the preview frame, one per kind, front-most first. The
+// canvas offsets its marks a quarter of the mark across and an eleventh of it down, so both steps
+// are measured against the mark this pane actually draws, HANDOFF rule 17's stateMarkSize.
+Item {
+    id: root
+
+    // Glyph names, front-most first, as ui/js/Facts.js multiMarks builds them.
+    property var marks: []
+
+    readonly property int stepX: Math.round(Theme.stateMarkSize / 4)
+    readonly property int stepY: Math.round(Theme.stateMarkSize / 11)
+    // Every mark behind the front one is a step fainter, which is the canvas's 1.0, 0.7 and 0.4.
+    readonly property real fade: 0.3
+    readonly property int steps: Math.max(0, root.marks.length - 1)
+
+    width: Theme.stateMarkSize + root.steps * root.stepX
+    height: Theme.stateMarkSize + root.steps * root.stepY
+
+    Repeater {
+        model: root.marks
+
+        delegate: Flea.Glyph {
+            required property string modelData
+            required property int index
+            // Model order paints back to front, so the front mark has to claim its own z.
+            z: root.marks.length - index
+            x: (root.steps - index) * root.stepX
+            y: index * root.stepY
+            maxSize: Theme.stateMarkSize
+            width: Theme.stateMarkSize
+            height: Theme.stateMarkSize
+            name: modelData
+            color: Theme.color.mutedFrame
+            opacity: 1 - index * root.fade
+        }
+    }
+}

package/ui/LangMark.qml

@@ -0,0 +1,51 @@
+import QtQuick
+import QtQuick.Shapes
+import "js/LangMarkPaths.js" as LangMarkPaths
+
+// A language logo on the file page: stroked page plus filled logo in the same ink.
+Item {
+    id: root
+
+    property string slug: ""
+    property color color: "transparent"
+    // Shared 24-unit grid with ui/js/Icons.js.
+    readonly property real grid: 24
+    // Caller ceiling; without one it draws nothing (fails loud).
+    property real maxSize
+    // "scale" would shadow Item.scale, as in ui/Glyph.qml.
+    readonly property real markSize: Math.min(root.maxSize, root.width, root.height)
+    readonly property real gridScale: root.markSize / root.grid
+    // Board's two-unit stroke on the shared grid.
+    property real strokeWidth: 2
+    // Caller caps; false is the Omarchy cut.
+    property bool roundCaps: false
+
+    // File page with the corner cut for the logo box (x 1..15, y 9..23).
+    readonly property string page: "M4 7V2h10l6 6v14H17 M14 2v6h6"
+
+    // Grid-sized Shape re-centered in the slot (Scale origin is 0,0).
+    Shape {
+        width: root.grid
+        height: root.grid
+        x: (root.width - root.markSize) / 2
+        y: (root.height - root.markSize) / 2
+        preferredRendererType: Shape.CurveRenderer
+        transform: Scale { xScale: root.gridScale; yScale: root.gridScale }
+
+        ShapePath {
+            strokeColor: root.color
+            fillColor: "transparent"
+            strokeWidth: root.strokeWidth
+            capStyle: root.roundCaps ? ShapePath.RoundCap : ShapePath.SquareCap
+            joinStyle: root.roundCaps ? ShapePath.RoundJoin : ShapePath.MiterJoin
+            PathSvg { path: root.page }
+        }
+
+        // Filled logo baked via translate(1 9) scale(14/24); see ui/js/LangMarkPaths.js.
+        ShapePath {
+            strokeColor: "transparent"
+            fillColor: root.color
+            PathSvg { path: LangMarkPaths.pathFor(root.slug) }
+        }
+    }
+}

package/ui/LangMarkLoader.qml

@@ -0,0 +1,26 @@
+pragma ComponentBehavior: Bound
+import QtQuick
+import qs.Commons
+
+// Only a row with a visible language logo builds it; the glyph supplies its geometry.
+Loader {
+    id: root
+
+    required property Item owner
+    required property Item glyph
+    active: !root.owner.thumbDrawn && root.owner.langSlug !== ""
+    visible: !root.owner.thumbDrawn && root.owner.langSlug !== ""
+    x: root.glyph.x
+    y: root.glyph.y
+    width: root.glyph.width
+    height: root.glyph.height
+    sourceComponent: LangMark {
+        anchors.fill: parent
+        maxSize: root.glyph.maxSize
+        slug: root.owner.langSlug
+        color: root.glyph.color
+        strokeWidth: root.glyph.strokeWidth
+        roundCaps: ViewState.hyprlandIcons && Style.cornerRadius > 0
+    }
+    onStatusChanged: if (status === Loader.Error) throw new Error("LangMark.qml did not load: Loader status " + status)
+}

package/ui/List.qml

@@ -0,0 +1,480 @@
+import QtQuick
+import "." as Flea
+import "js/ClipMarks.js" as ClipMarks
+import "js/DirSizes.js" as DirSizes
+import "js/ExtThumbs.js" as ExtThumbs
+import "js/Filter.js" as Filter
+import "js/Scroll.js" as Scroll
+import "js/ScrollOff.js" as ScrollOff
+import "js/Tap.js" as Tap
+import "js/Thumbs.js" as Thumbs
+
+// The listing's render, scroll and settle-triggered refetch, split out of Pane.qml; reaches Pane's state through the pane reference and the context menu through menu, both handed in at instantiation.
+ListView {
+    id: root
+
+    property var pane: null
+    readonly property bool fileDragActive: dragSession.Drag.active
+    property var menu: null
+
+    // Parked rows built ahead of the next landing; a row parks invisible and the landing shows it again.
+    readonly property Flea.PrebuildDriver prebuild: Flea.PrebuildDriver {
+        view: root
+        model: stable
+        pane: root.pane
+        limit: stable.warmRows
+        held: root.hiddenHeld
+        park: function (cell) { cell.live = false; cell.visible = false }
+        adopt: function (cell) { cell.live = true; cell.visible = true; cursorMark.place(cell) }
+    }
+
+    // Shared once, read plainly per row, so no delegate builds its own width or array.
+    property real rowWidth: Scroll.contentWidth(root.width, Theme.spacing.rowPaddingX)
+    // Dual mode hides mode and kind on top of the stored set; one array, never one per row.
+    property var rowHiddenCols: root.pane && root.pane.dualMode ? ["mode", "kind"].concat(ViewState.hiddenCols) : ViewState.hiddenCols
+    // Shared name budgets remove the per-row floor; Row keeps its local default for PickerList and drop targets.
+    readonly property bool listDual: root.pane && root.pane.dualMode ? true : false
+    readonly property real listMarkSlot: root.listDual ? Theme.markSize : Theme.iconSize
+    readonly property real listSizeWidth: root.listDual ? Theme.dualColumn.size : Theme.column.size
+    readonly property real listDateWidth: root.listDual ? Theme.dualColumn.date : Theme.column.date
+    // The same set Row.cols resolves, from the same width and hidden array, so the two cannot drift.
+    readonly property var listCols: root.pane && root.pane.recentMode.length > 0 ? Theme.columns(root.rowWidth, root.rowHiddenCols, root.listDateWidth, true, root.listDual) : root.listDual ? Theme.dualColumns(root.rowWidth, root.rowHiddenCols) : Theme.columns(root.rowWidth, root.rowHiddenCols, root.listDateWidth)
+    readonly property bool listModeShown: root.listCols ? !!root.listCols.mode : false
+    readonly property bool listSizeShown: root.listCols ? !!root.listCols.size : false
+    readonly property bool listDateShown: root.listCols ? !!root.listCols.date : false
+    readonly property bool listKindShown: root.listCols ? !!root.listCols.kind : false
+    // Matches Theme.clipMarkSize; the reserve keeps the glyph readable.
+    readonly property int listClipPx: Theme.clipMarkSize
+    // Exact drawn geometry: the row less padding, mark, gap, columns, gaps and name-to-mode gap, in pixels then floored.
+    readonly property real nameSlotPlainPx: Math.max(0, root.rowWidth - 2 * Theme.spacing.rowPaddingX - root.listMarkSlot - Theme.spacing.gap - (root.listModeShown ? Theme.column.mode : 0) - (root.listSizeShown ? root.listSizeWidth : 0) - (root.listDateShown ? root.listDateWidth : 0) - (root.listKindShown ? Theme.column.kind : 0) - (root.listKindShown ? Theme.spacing.gap : 0) - ((root.listDateShown && !root.listDual) ? Theme.spacing.gap : 0) - ((root.listSizeShown && !root.listDual) ? Theme.spacing.gap : 0) - (root.listModeShown ? Theme.spacing.gap : 0))
+    readonly property real nameSlotClipPx: Math.max(0, root.nameSlotPlainPx - Theme.spacing.gap - root.listClipPx)
+    readonly property int nameBudgetPlain: Theme.bodyAdvance > 0 && root.nameSlotPlainPx > 0 ? Math.floor(root.nameSlotPlainPx / Theme.bodyAdvance) : -1
+    readonly property int nameBudgetClip: Theme.bodyAdvance > 0 && root.nameSlotClipPx > 0 ? Math.floor(root.nameSlotClipPx / Theme.bodyAdvance) : -1
+    property bool clipEmpty: ClipMarks.isEmpty(root.pane ? root.pane.clipboard : null)
+    // The short-circuit below is the only release while empty, so a cut of a large directory frees its lookup here.
+    onClipEmptyChanged: { if (root.clipEmpty) ClipMarks.release() }
+
+    // Pane owns cursorIndex, thumbState and dirSizeState; List only computes what changed and hands it back.
+    // Both ends of cursorClamped are view positions, not listing rows: under a filter they differ.
+    signal cursorClamped(int first, int last)
+    signal thumbsApplied(var work)
+    signal dirSizesApplied(var ask)
+    signal dirSizesCancelled()
+
+    focus: true
+    keyNavigationEnabled: false
+    // Hidden holds no delegates; an edit the List held when it hid keeps its own per RenameField.qml.
+    model: Flea.StableModel { id: stable; view: root; total: (root.visible || root.renameHeld) ? root.pane.shownTotal : 0
+                              warm: root.visible && root.pane.searchMode.length > 0 && root.pane.swap.searchWarm === true; warmRows: Math.floor((root.height + root.cacheBuffer) / Theme.fileRowHeight) + 1 }
+    clip: true
+    cacheBuffer: Theme.fileRowHeight * pane.cacheRows
+    boundsBehavior: Flickable.StopAtBounds
+    highlightMoveDuration: 0
+    // Every property the delegate draws binds to index and cursor is refiled by listingIndex, so a row leaving the buffer is re-bound rather than rebuilt.
+    reuseItems: true
+    // The one row drawn as the cursor; a cursor move touches two delegates, not every live one.
+    Flea.CursorMark { id: cursorMark; row: root.pane.cursorIndex }
+
+    Flea.FastScrollHandler {
+        parent: root
+        flickable: root
+    }
+
+    readonly property alias scrollBar: verticalScroll
+    Flea.ViewportScrollBar {
+        id: verticalScroll
+        parent: root
+        anchors { top: parent.top; right: parent.right }
+        flickable: root
+    }
+
+    Flea.SelectionBand {
+        parent: root
+        pane: root.pane
+        flickable: root
+    }
+
+    Flea.FileDrag {
+        id: dragSession
+        pane: root.pane
+    }
+
+    delegate: Flea.Row {
+        id: cell
+        required property int index
+        // Parked while pooled: each listing read returns its own last value until onReused rebinds it before the next frame; a row holding the open editor stays live, since a prebuild create pools and reuses the shown rows and pooling would destroy the editor.
+        property bool live: true
+        ListView.onPooled: if (!cell.renaming) cell.live = false
+        ListView.onReused: {
+            // The driver's create can take a pooled row past the shown ones; it parks as a built one does.
+            if (cell.index >= root.count) { root.prebuild.parkCell(cell); return }
+            cell.live = true
+            root.prebuild.adoptCell(cell)
+        }
+        // Built ahead of a landing past the shown rows: parked invisible until the landing reuses it.
+        property bool prebuilt: false
+        Component.onDestruction: root.prebuild.gone(cell)
+        // index is where the row is drawn; listingIndex is the row the backend numbers, and under a
+        // filter the two are different. Everything that leaves this delegate takes the listing one.
+        readonly property int listingIndex: cell.live ? Filter.at(root.pane.shown, index) : -1
+        // Filed by listing row in the view's cursor mark, which sets cursor; see ui/CursorMark.qml.
+        property int markRow: -1
+        Component.onCompleted: if (!root.prebuild.built(cell)) cursorMark.place(cell)
+        onListingIndexChanged: cursorMark.place(cell)
+        // The scroll lane stays clear so rows never reflow under the bar.
+        width: root.rowWidth
+        paintWidth: root.width
+        row: cell.live ? root.pane.rowFor(listingIndex) : cell.row
+        paneFocused: root.pane.paneFocused
+        dualMode: root.pane.dualMode
+        hiddenCols: root.rowHiddenCols
+        // One Columns.set per List state, shared by every delegate; Row keeps its local default for PickerList and drop targets.
+        assignedCols: root.listCols
+        hovered: hover.hovered
+        thumb: cell.live ? root.thumbFor(listingIndex) : cell.thumb
+        selected: cell.live && root.pane.isSelected(listingIndex)
+        // Empty short-circuits before the library, so no row calls it while the clipboard is empty.
+        clipMark: !cell.live ? cell.clipMark : root.clipEmpty ? "" : ClipMarks.markForRow(root.pane, cell.row ? cell.row.n : "", root.pane.clipboard)
+        // Shared budgets: one floor per List state, not per row; drop rows keep local measured geometry in Row.
+        assignedNameBudget: cell.clipMark.length > 0 ? root.nameBudgetClip : root.nameBudgetPlain
+        // The highlight content builds with the filter strip, so no keystroke pays for it; mirrors the strip's own up rule.
+        markArmed: root.pane.filterTyping || root.pane.filterQuery.length > 0
+        // A search's location layout builds hidden after the strip's first frame, so no answer pays for it.
+        locateArmed: root.pane.searchMode.length > 0 && root.pane.swap.searchWarm === true
+        kindNames: cell.live ? root.pane.kindNames : cell.kindNames
+        dirSize: cell.live ? DirSizes.cellFor(root.pane.dirSizeState, listingIndex) : cell.dirSize
+        // A filter paints its run the same way a search does; filtering below is what keeps the
+        // ordinary columns, because these rows are still this directory's own and not walk results.
+        searchQuery: !cell.live ? cell.searchQuery : root.pane.searchMode.length > 0 ? root.pane.swap.answeredQuery : root.pane.filterQuery
+        filtering: cell.live ? root.pane.shown !== null : cell.filtering
+        // Sidebar040: Recent splits its path into Name and the fixed Location column.
+        recenting: cell.live ? root.pane.recentMode.length > 0 : cell.recenting
+        renaming: listingIndex >= 0 && listingIndex === root.pane.renamingIndex
+        renamePane: root.pane
+        // -1 is also what Filter.at answers for a stale delegate, so an idle list must never light one.
+        dropTarget: dragSession.dropIndex >= 0 && listingIndex === dragSession.dropIndex
+        dropCopying: dragSession.dragCopy
+        dropLinking: dragSession.dragLink
+
+        onRenameCommitted: function (newName) { root.pane.commitRename(newName) }
+        onRenameAbandoned: root.pane.renamingIndex = -1
+
+        HoverHandler {
+            id: hover
+            // Disabled while pooled, so a reused row starts unhovered as a new one does.
+            enabled: cell.live && root.pane.selectionBand === null
+        }
+
+        TapHandler {
+            id: tap
+            enabled: !cell.renaming
+            acceptedButtons: Qt.LeftButton | Qt.RightButton | Qt.MiddleButton
+            // A held press must still tap on release.
+            longPressThreshold: 0
+            // A press held past the interval must not fire while the button is
+            // still down on a row about to be dragged; the release still arms.
+            onPressedChanged: if (pressed) root.pane.pressSlowClick()
+            onTapped: function (eventPoint, button) {
+                if (button === Qt.MiddleButton)
+                    Tap.tappedTab(root.pane.rowFor(listingIndex), root.pane.path, root.pane)
+                else if (button === Qt.RightButton)
+                    Tap.tappedMenu(listingIndex, eventPoint, root.pane, root.menu)
+                else if (cell.onSizeCell(eventPoint.position)) {
+                    // A folder's ⚖️ Size cell measures that folder and does nothing else; a double click stays one ask.
+                    if (tap.tapCount === 1) root.pane.measureDirs([listingIndex])
+                } else {
+                    var wasSole = root.pane.slowClickWasSole(listingIndex)
+                    Tap.tapped(listingIndex, tap.tapCount, tap.point.modifiers, root.pane)
+                    Tap.slowTap(root.pane, tap.tapCount === 1 && Tap.onName(cell.nameItem(), cell, eventPoint.position, false),
+                                listingIndex, tap.point.modifiers, dragSession.Drag.active, wasSole)
+                }
+            }
+        }
+
+        Flea.RowDrag {
+            session: dragSession
+            listingIndex: cell.listingIndex
+            row: cell.row
+        }
+    }
+    // The listing keeps one row of bare ground at its end. SearchFilter rule 1 took the filter's
+    // sentence off this slot, and the ground under it is not the sentence: it is where a band starts
+    // and where the background menu is raised, and a listing whose last row sits flush on the bottom
+    // edge offers neither once it is scrolled to the end.
+    footer: Item {
+        width: root.rowWidth
+        height: Theme.chromeHeight
+    }
+
+    // Empty space under the last row belongs to the directory, not to a row, so it raises the
+    // background menu. Tap.onBackground says the point missed every delegate, which is what leaves a
+    // right click on a row to that row's own handler above.
+    TapHandler {
+        acceptedButtons: Qt.RightButton
+        onTapped: function (eventPoint) {
+            if (Tap.onBackground(root, eventPoint))
+                root.menu.openBackground(eventPoint.scenePosition)
+        }
+    }
+
+    onContentYChanged: {
+        // Hidden geometry and a restore in flight move no shared state.
+        if (!root.visible || root.hiddenHeld)
+            return
+        // The cursor follows the bounded view, silent while that view did not move.
+        var at = Scroll.bounded(root.contentY, root.originY, root.contentHeight, root.height)
+        // Qt shifts originY when expanded delegates collapse; row offsets start at that origin.
+        var first = Math.floor((at - root.originY) / Theme.fileRowHeight)
+        var last = Math.min(root.pane.shownTotal - 1, first + root.pane.visibleRows - 1)
+        if (root.pane.renamingIndex >= 0) {
+            var range = root.visibleRange()
+            first = range.first
+            last = range.last
+        }
+        if (last >= first && root.pane.selectionBand === null && at !== root._clampAt) {
+            root._clampAt = at
+            root.cursorClamped(first, last)
+        }
+        root.menu.close()
+        // A scroll never cancels a size the user asked for (src/dirsize.js).
+        coalesce.start()
+        settle.restart()
+    }
+
+    function visibleRange() {
+        var fallback = Thumbs.viewport(root.contentY - root.originY, Theme.fileRowHeight, root.pane.visibleRows, root.pane.shownTotal)
+        // The retained error caption expands one row; query actual delegates while it is present.
+        if (root.pane.renamingIndex >= 0) {
+            var first = root.indexAt(0, root.contentY)
+            var last = root.indexAt(0, root.contentY + root.height - 1)
+            first = first < 0 ? fallback.first : first
+            return {first: first, last: last < 0 ? Math.min(root.count - 1, first + root.pane.visibleRows) : last}
+        }
+        return fallback
+    }
+
+    // Returning parks the view on the shared cursor once the reset rows land.
+    property bool hiddenHeld: false
+    // True while the List's own edit is open, so a hide keeps it in any binding order; a rename in Grid or Columns leaves it false.
+    property bool renameHeld: false
+    // The bounded view last emitted; a bounce holds it, so the cursor stays put.
+    property var _clampAt
+    // Last parked contentY and loop turns spent; only a value stable across turns ends the hold.
+    property real restoreY: -1
+    property int restoreTicks: 0
+    onVisibleChanged: {
+        if (!root.visible) {
+            coalesce.stop()
+            settle.stop()
+            root.hiddenHeld = true
+            root.restoreY = -1
+            root.restoreTicks = 0
+            return
+        }
+        root.renameHeld = root.pane ? root.pane.renamingIndex >= 0 : false
+        if (root.hiddenHeld)
+            root.restoreCursorView()
+    }
+    onCountChanged: {
+        if (root.hiddenHeld && root.visible && root.count > 0)
+            root.restoreCursorView()
+        root.prebuild.landed()
+    }
+    onCurrentIndexChanged: root.prebuild.kick()
+    function restoreCursorView() {
+        // A queued turn arriving after the hold ended is stale.
+        if (!root.hiddenHeld || !root.visible)
+            return
+        if (!root.pane) {
+            root.hiddenHeld = false
+            return
+        }
+        // The model reset may still be landing; a later turn retries.
+        if (root.count === 0 && root.pane.shownTotal > 0) {
+            root.deferRestore()
+            return
+        }
+        // An empty listing and a filtered-away cursor have no view to park, so the hold ends here.
+        var view = Filter.viewOf(root.pane.shown, root.pane.cursorIndex)
+        if (root.count === 0 || view < 0) {
+            root.hiddenHeld = false
+            return
+        }
+        root.forceLayout()
+        root.positionViewAtIndex(view, ListView.Contain)
+        // Only a value stable across turns ends the hold; an optimistic position never releases it.
+        if (root.coversCursor(view) && root.contentY === root.restoreY) {
+            root.hiddenHeld = false
+            root.restoreY = -1
+            root.restoreTicks = 0
+            settle.restart()
+            return
+        }
+        root.restoreY = root.contentY
+        root.deferRestore()
+    }
+    // The parked check the return asserts through: the cursor row is inside the viewport.
+    function coversCursor(view) {
+        var top = root.originY + view * Theme.fileRowHeight
+        return root.contentY <= top + Theme.fileRowHeight && root.contentY + root.height >= top
+    }
+    // One more loop turn, with a deadlock guard that ends the hold rather than keeping it.
+    function deferRestore() {
+        if (!root.visible)
+            return
+        if (root.restoreTicks >= 60) {
+            root.hiddenHeld = false
+            root.restoreY = -1
+            root.restoreTicks = 0
+            settle.restart()
+            return
+        }
+        root.restoreTicks += 1
+        Qt.callLater(root.restoreCursorView)
+    }
+
+    // The renaming row's view index, the same mapping restoreCursorView uses.
+    readonly property int renameViewIndex: root.pane && root.pane.renamingIndex >= 0 ? Filter.viewOf(root.pane.shown, root.pane.renamingIndex) : -1
+    // The renaming delegate's error height, read once here rather than bound per row; none while hidden, when Grid or Columns owns the editor.
+    readonly property real renameErrorHeight: {
+        if (!root.visible || !root.pane || root.pane.renamingIndex < 0 || root.pane.renameError.length === 0) return 0
+        var ed = root.pane.renameEditor()
+        var f = ed ? ed.editorField : null
+        return f ? f.errorHeight : 0
+    }
+    // Set when an error line appears or grows, and spent by the view's next contentHeight change.
+    property bool containRenameError: false
+    onRenameErrorHeightChanged: root.containRenameError = root.renameErrorHeight > 0
+    // The error line's growth lands in contentHeight after layout, so the row is contained once then, never on a later scroll's estimate.
+    onContentHeightChanged: if (root.containRenameError && root.renameViewIndex >= 0) { root.containRenameError = false; root.positionViewAtIndex(root.renameViewIndex, ListView.Contain) }
+
+    // Pane's own open() and its Connections.onRows reach these two through the wrapper functions below.
+    Timer {
+        id: coalesce
+        interval: root.pane.coalesceMs
+        repeat: false
+        onTriggered: root.requestIfDrifted()
+    }
+
+    // The cursor keeps three rows of context above and below while scrolling; every cursor move routes through here.
+    function showCursor(view, context) {
+        var to = ScrollOff.cursorY(root, view, root.pane.shownTotal, Theme.fileRowHeight, context)
+        if (to !== null)
+            root.contentY = to
+    }
+
+    // Resize and filter changes can change the visible work without moving contentY.
+    Connections {
+        target: root.pane
+        function onVisibleRowsChanged() { if (root.visible) settle.restart() }
+        function onRenamingIndexChanged() { root.renameHeld = root.visible && root.pane.renamingIndex >= 0 }
+        function onFilterQueryChanged() {
+            if (!root.visible) return
+            var work = Filter.cut({ask: [], drop: []}, root.pane.shown, root.pane.thumbState)
+            work.drop = work.drop.filter(function(index) { return index !== root.pane.previewIndex })
+            if (work.drop.length > 0) {
+                root.pane.backend.thumbcancel(work.drop)
+                root.thumbsApplied(work)
+            }
+            // A scroll never cancels a size the user asked for (src/dirsize.js).
+            settle.restart()
+        }
+    }
+
+    Connections {
+        target: ViewState
+        function onThumbnailModeChanged() { if (root.visible) settle.restart() }
+        // A hidden-then-shown Size column asks for the visible rows at that moment.
+        function onHiddenColsChanged() { if (root.visible) settle.restart() }
+    }
+
+    Timer {
+        id: settle
+        interval: root.pane.firstSettleMs
+        repeat: false
+        onTriggered: { root.requestThumbs(); root.requestDirSizes() }
+    }
+
+    // Pane.open() primes the next settle to the short first-screen interval before any row arrives.
+    function primeSettle() { settle.interval = root.pane.firstSettleMs }
+    function restartCoalesce() { coalesce.restart() }
+    function restartSettle() { settle.restart() }
+
+    // Only the visible rows, only once each, and only after the list has stopped moving.
+    // Unknown storage holds until fsinfo names it, so the first screen never decodes as local.
+    function requestThumbs() {
+        if (!root.visible || root.pane.listInFlight || !root.pane.storageKnown)
+            return
+        var view = root.visibleRange()
+        // A filtered viewport covers a set and not a run, so the run it spans is what the planner
+        // gets and Filter.cut takes back every row inside that run the filter is hiding.
+        var span = Filter.span(root.pane.shown, view.first, view.last)
+        var work = Filter.cut(Thumbs.plan(root.pane.thumbState, root.pane.rows, root.pane.held, span.first, span.last, ViewState.thumbnailMode), root.pane.shown, root.pane.thumbState)
+        work.drop = work.drop.filter(function (index) { return index !== root.pane.previewIndex })
+        root.pane.backend.thumbcancel(work.drop)
+        // An off class still asks; the backend answers from the cache alone, see ui/js/ExtThumbs.js.
+        work.cacheOnly = ExtThumbs.cacheOnly(root.pane.storageClass, ViewState.preview)
+        root.pane.backend.thumb(work.ask, work.cacheOnly)
+        // The short first settle latches to the fling debounce only once a request has actually gone out.
+        if (work.ask.length > 0)
+            settle.interval = root.pane.settleMs
+        root.thumbsApplied(work)
+    }
+
+    function thumbFor(index) {
+        return Thumbs.allowed(root.pane.rowFor(index), ViewState.thumbnailMode) ? Thumbs.fileFor(root.pane.thumbState, index) : ""
+    }
+
+    function dirSizeFor(index) {
+        return DirSizes.sizeFor(root.pane.dirSizeState, index)
+    }
+
+    // Same idiom as requestThumbs, minus a cancel: onContentYChanged already sent it, see above.
+    function requestDirSizes() {
+        // Folder sizes are measured only when the user asks: a ⚖️ click, see Pane.measureDirs.
+        return
+        if (!root.visible || root.pane.shownTotal === 0 || root.pane.listInFlight)
+            return
+        // A hidden Size column or a network or phone folder draws no size, so it asks for no walk.
+        if (!DirSizes.wantsSizes("list", ViewState.hiddenCols, root.pane.storageClass, root.pane.storageKnown))
+            return
+        // Thumbs.viewport() is reused: it takes no thumb-specific state, only geometry.
+        var view = root.visibleRange()
+        var span = Filter.span(root.pane.shown, view.first, view.last)
+        var ask = Filter.keep(DirSizes.plan(root.pane.dirSizeState, root.pane.rows, root.pane.held, span.first, span.last, ViewState.thumbnailMode), root.pane.shown)
+        if (ask.length > 0) {
+            root.pane.backend.dirsize(ask)
+            settle.interval = root.pane.settleMs
+        }
+        root.dirSizesApplied(ask)
+    }
+
+    // Handle an empty held window explicitly before applying held-edge arithmetic.
+    function requestIfDrifted() {
+        // No window while hidden, while a filter narrows rows already held, nor while a listing is out, whose windows are the directory asked for.
+        if (!root.visible || root.pane.total === 0 || root.pane.shown !== null || root.pane.listInFlight)
+            return
+        var firstVisible = Math.floor((root.contentY - root.originY) / Theme.fileRowHeight)
+        var lastVisible = firstVisible + root.pane.visibleRows
+        if (root.pane.renamingIndex >= 0) {
+            var range = root.visibleRange()
+            firstVisible = range.first
+            lastVisible = range.last + 1
+        }
+        if (root.pane.rows.length === 0) {
+            root.requestAround(firstVisible)
+            return
+        }
+        var heldEnd = root.pane.held + root.pane.rows.length
+        if (firstVisible - root.pane.held < root.pane.refetchMargin && root.pane.held > 0) {
+            root.requestAround(firstVisible)
+        } else if (heldEnd - lastVisible < root.pane.refetchMargin && heldEnd < root.pane.total) {
+            root.requestAround(firstVisible)
+        }
+    }
+
+    function requestAround(firstVisible) {
+        var start = Math.max(0, firstVisible - root.pane.buffer)
+        root.pane.backend.window(start, root.pane.windowSize)
+    }
+}

package/ui/LoadingState.qml

@@ -0,0 +1,54 @@
+import QtQuick
+import "js/Swap.js" as Swap
+
+// The listing's loading touch, EmptyState's sibling: the caller places it over listArea and
+// gates visibility on listingState. The hold-off keeps a local listing, single-digit
+// milliseconds on this box, from ever flashing the mark; only slow sources (network mounts,
+// a cold spinning disk) live long enough to show it.
+Item {
+    id: root
+
+    property int holdOffMs: Swap.HOLD_MS
+    property bool armed: false
+    // Set when the listing swap already held the old rows for its own cap, which spent this hold-off.
+    property bool heldOff: false
+    // The mark and its word are on screen; ui/PaneStates.qml tells ui/PaneSwap.qml, which keeps them Swap.MIN_SHOW_MS.
+    readonly property bool shown: root.visible && (root.armed || root.heldOff)
+    // The crawl's own width, so a Columns pane can tell whether it clears the listed columns.
+    readonly property real naturalWidth: crawl.implicitWidth
+
+    // running binds to visibility rather than an onVisibleChanged handler: the pane starts life
+    // in "loading", so visible is true at creation and a change handler would never fire.
+    Timer {
+        id: holdOff
+        interval: root.holdOffMs
+        running: root.visible
+        onTriggered: root.armed = true
+    }
+
+    onVisibleChanged: if (!root.visible) root.armed = false
+
+    Column {
+        id: crawl
+        anchors.centerIn: parent
+        spacing: Theme.spacing.gap
+        visible: root.armed || root.heldOff
+
+        Spinner {
+            anchors.horizontalCenter: parent.horizontalCenter
+            // The same brand mark as EmptyState's hero, which States.dc.html draws at 48; two row heights was 74.
+            width: Theme.heroMarkSize
+            height: Theme.heroMarkSize
+        }
+
+        // States draws the crawl with one word under it, and one word is the whole of what it knows.
+        Text {
+            anchors.horizontalCenter: parent.horizontalCenter
+            text: "reading"
+            color: Theme.color.muted
+            font.family: Theme.font.family
+            font.pixelSize: Theme.font.caption
+            textFormat: Text.PlainText
+        }
+    }
+}