flea-qml 0.0.0-stage → 0.1.0

package/ui/js/Places.js

@@ -0,0 +1,265 @@
+.pragma library
+
+.import "Mounts.js" as Mounts
+.import "UserDirs.js" as UserDirs
+
+// Sample input: XDG_DOWNLOAD_DIR="$HOME/Downloads"
+function userDirs(body, home) {
+    return UserDirs.userDirs(body, home)
+}
+
+// Sample input: file:///home/gm/Downloads Downloads
+function bookmarks(body) {
+    var out = []
+    var lines = String(body || "").split("\n")
+    for (var i = 0; i < lines.length; i++) {
+        var line = lines[i].trim()
+        // corner: a bookmark may be smb:// or sftp://, which is a Location and not a Favorite.
+        if (line.indexOf("file://") !== 0)
+            continue
+        var space = line.indexOf(" ")
+        var uri = space < 0 ? line : line.substring(0, space)
+        var label = space < 0 ? "" : line.substring(space + 1).trim()
+        var path = Mounts.decodePath(uri.substring("file://".length))
+        out.push({ path: path, label: label.length > 0 ? label : leaf(path) })
+    }
+    return out
+}
+
+// The FAVORITES rail's rows, Home first and always, then XDG dirs and bookmarked places in file
+// order, a path seen twice keeping its first position. glyphFor resolves each row's mark so the
+// rail's Icons import stays the rail's own business; see ui/Sidebar.qml's rebuild.
+function favorites(home, dirsText, marksText, glyphFor) {
+    var favs = [{ path: home, label: "Home", group: "favorite", kind: "favorite", glyph: glyphFor("Home") }]
+    var seen = {}
+    seen[home] = true
+    var groups = [userDirs(dirsText, home), bookmarks(marksText)]
+    for (var g = 0; g < groups.length; g++) {
+        for (var i = 0; i < groups[g].length; i++) {
+            if (seen[groups[g][i].path])
+                continue
+            var e = groups[g][i]
+            seen[e.path] = true
+            favs.push({ path: e.path, label: e.label, group: "favorite", kind: "favorite", glyph: glyphFor(e.label) })
+        }
+    }
+    return favs
+}
+
+function leaf(path) {
+    var cut = path.lastIndexOf("/")
+    return cut < 0 ? path : path.substring(cut + 1)
+}
+
+// Sample input: "smb://192.168.1.10/data NAS"; see AGENTS.md "Places.relabel" for the matching, duplicate and control-character rules.
+function relabel(body, path, name) {
+    // A trust boundary: an embedded newline could otherwise split one bookmark into two lines.
+    var trimmed = String(name || "").replace(/[\r\n]/g, "").trim()
+    if (trimmed.length === 0)
+        return String(body || "")
+    var target = Mounts.normalize(path)
+    var lines = String(body || "").split("\n")
+    var found = false
+    for (var i = 0; i < lines.length; i++) {
+        // Read off the trimmed line the way Mounts.removeBookmark reads it, or an indented bookmark
+        // is one Remove can drop and this could only ever duplicate.
+        var line = lines[i].trim()
+        if (line.length === 0)
+            continue
+        var space = line.indexOf(" ")
+        var uri = space < 0 ? line : line.substring(0, space)
+        if (Mounts.normalize(uri) === target) {
+            lines[i] = uri + " " + trimmed
+            found = true
+        }
+    }
+    if (found)
+        return lines.join("\n")
+    var out = String(body || "")
+    if (out.length > 0 && out.charAt(out.length - 1) !== "\n")
+        out += "\n"
+    return out + target + " " + trimmed + "\n"
+}
+
+// Sample input: body as relabel's, oldUri the saved line being rewritten, newUri the address the
+// form's Mounts-as line showed. Matched the way relabel matches, so a live mount's trailing slash
+// still finds the saved line, and an empty oldUri matches nothing and appends instead. PR 21.
+function replace(body, oldUri, newUri, label) {
+    var next = Mounts.normalize(newUri)
+    if (next.length === 0)
+        return String(body || "")
+    // The same trust boundary relabel names: an embedded newline would split one bookmark into two.
+    var name = String(label || "").replace(/[\r\n]/g, "").trim()
+    if (name.length === 0)
+        name = leaf(next)
+    var target = Mounts.normalize(oldUri)
+    var lines = String(body || "").split("\n")
+    var found = false
+    for (var i = 0; i < lines.length; i++) {
+        var line = lines[i].trim()
+        if (line.length === 0)
+            continue
+        var space = line.indexOf(" ")
+        var uri = space < 0 ? line : line.substring(0, space)
+        if (target.length > 0 && Mounts.normalize(uri) === target) {
+            lines[i] = next + " " + name
+            found = true
+        }
+    }
+    if (found)
+        return lines.join("\n")
+    var out = String(body || "")
+    if (out.length > 0 && out.charAt(out.length - 1) !== "\n")
+        out += "\n"
+    return out + next + " " + name + "\n"
+}
+
+var WIDTH_STOPS = [160, 192, 224, 256]
+function sidebarWidth(value) {
+    if (typeof value !== "number" || !isFinite(value)) return 192
+    var nearest = WIDTH_STOPS[0]
+    for (var i = 1; i < WIDTH_STOPS.length; i++) {
+        if (Math.abs(WIDTH_STOPS[i] - value) < Math.abs(nearest - value)) nearest = WIDTH_STOPS[i]
+    }
+    return nearest
+}
+
+function recordError(record) {
+    if (!record || typeof record !== "object" || Array.isArray(record)) return "invalid favorite record"
+    if (typeof record.label !== "string" || record.label.trim().length === 0) return "label needs visible text"
+    if (typeof record.path !== "string" || /[\u0000-\u001f\u007f]/.test(record.path)) return "invalid path"
+    if (record.path.charAt(0) === "/" || record.path === "~" || record.path.indexOf("~/") === 0) return ""
+    var schemes = ["smb://", "sftp://", "ftp://", "dav://", "davs://", "afp://", "nfs://", "file://"]
+    for (var i = 0; i < schemes.length; i++) {
+        if (record.path.indexOf(schemes[i]) === 0 && record.path.length > schemes[i].length) return ""
+    }
+    return "use a full path, a path that starts with ~/, or a network address"
+}
+
+function storedEntries(records, home) {
+    var out = []
+    for (var i = 0; Array.isArray(records) && i < records.length; i++) {
+        var record = records[i]
+        var error = recordError(record)
+        var label = record && typeof record.label === "string" ? record.label : JSON.stringify(record)
+        var path = record && typeof record.path === "string" ? record.path : ""
+        var resolved = path === "~" ? home : path.indexOf("~/") === 0 ? home + path.substring(1) : path
+        out.push({ label: label || "Invalid favorite", path: resolved, storedPath: path,
+            error: error, original: record, favouriteIndex: i, group: "favourite", kind: "favourite",
+            glyph: path.indexOf("://") >= 0 ? "network" : "folder" })
+    }
+    return out
+}
+
+// flea-qml: Home, then the folders the backend found by looking (src/places.js), each
+// { path, label, glyph }. Upstream drew the folders user-dirs.dirs names, there or not; here a
+// row is a folder that answered, and until the backend's first line the list is Home alone.
+function homeEntries(home, probed, glyphFor) {
+    var entries = [{ label: "Home", path: home, group: "home", kind: "home", glyph: glyphFor("Home") }]
+    var rows = Array.isArray(probed) ? probed : []
+    for (var i = 0; i < rows.length; i++) {
+        var row = rows[i]
+        if (!row || typeof row.path !== "string" || row.path.length === 0 || row.path === home)
+            continue
+        entries.push({ label: String(row.label || row.path), path: row.path, group: "home", kind: "home", glyph: String(row.glyph || "folder") })
+    }
+    return entries
+}
+
+// flea-qml: the drives the backend found by looking, drawn under DEVICES as plain folders: a row
+// opens its path and offers a place's menu, and nothing here mounts or ejects. A drive lsblk
+// already lists, by the mount point of one of `listed`'s rows, is that row and not a second one.
+function volumeEntries(volumes, listed) {
+    var out = []
+    var rows = Array.isArray(volumes) ? volumes : []
+    var held = {}
+    for (var d = 0; Array.isArray(listed) && d < listed.length; d++) {
+        if (listed[d] && typeof listed[d].path === "string" && listed[d].path.length > 0)
+            held[listed[d].path] = true
+    }
+    for (var i = 0; i < rows.length; i++) {
+        var row = rows[i]
+        if (!row || typeof row.path !== "string" || row.path.length === 0 || held[row.path])
+            continue
+        out.push({ label: String(row.label || row.path), path: row.path, group: "home", kind: "home", volume: true,
+            glyph: String(row.glyph || "drive"), size: typeof row.size === "number" ? row.size : null })
+    }
+    return out
+}
+
+// The rail and query use the same validation, URI decoding and mount-first open.
+function openEntry(entry, ports) {
+    if (!entry) return
+    if (entry.kind === "trash") { ports.trash(); return }
+    var error = entry.kind === "favourite" ? recordError(entry.original) : ""
+    if (error) { ports.message("Could not open %1 · %2".replace(/%([12])/g, function (m, n) { return n === "1" ? entry.label : error }), true); return }
+    if (entry.path.indexOf("://") >= 0 && entry.path.indexOf("file://") !== 0) {
+        var host = ports.networkHost()
+        if (host) host.openChildShare(entry.path, entry.label, ports.pane)
+    } else {
+        ports.opened(entry.path.indexOf("file://") === 0 ? Mounts.decodePath(entry.path.substring(7)) : entry.path)
+    }
+}
+
+function railIdentity(entry) {
+    if (!entry) return ""
+    if (entry.kind === "favourite") return JSON.stringify([entry.kind, entry.original])
+    return JSON.stringify([entry.group, entry.kind, Mounts.railKey(entry) || entry.device || entry.uri || entry.path])
+}
+
+// Duplicate originals have no stored ID; a changed multiplicity cannot safely identify the selected occurrence.
+function railCursorAfter(before, after, index) {
+    if (before.length === 0 && index === 0) return 0
+    if (index < 0 || index >= before.length) return -1
+    var key = railIdentity(before[index]), oldCount = 0, occurrence = 0, matches = []
+    for (var i = 0; i < before.length; i++) {
+        if (railIdentity(before[i]) !== key) continue
+        oldCount++
+        if (i < index) occurrence++
+    }
+    for (var j = 0; j < after.length; j++) {
+        if (railIdentity(after[j]) === key) matches.push(j)
+    }
+    return matches.length === oldCount ? matches[occurrence] : -1
+}
+
+// Under gvfs only the mounted row opened under view.shareKey lights, never a folder prefix or the disk.
+function heldBy(entries, dir, view) {
+    var list = entries || []
+    var at = view || ({ kind: "dir" })
+    var path = String(dir || "")
+    var gvfs = Mounts.underGvfs(path)
+    var best = -1, depth = -1
+    for (var i = 0; i < list.length; i++) {
+        var e = list[i]
+        if (at.kind !== "dir") {
+            if (e.kind === at.kind && (at.kind !== "tag" || e.tag === at.tag))
+                return i
+            continue
+        }
+        if (e.kind === "recent" || e.kind === "trash" || e.kind === "tag" || e.error || e.mounted === false)
+            continue
+        if (gvfs) {
+            var key = String(at.shareKey || "")
+            if (key.length > 0 && !e.path && (Mounts.normalize(e.uri) === key || Mounts.normalize(e.mountUri) === key))
+                return i
+            continue
+        }
+        if (typeof e.path !== "string" || e.path.length === 0)
+            continue
+        if ((e.path === "/" ? path.charAt(0) === "/" : Mounts.inside(path, e.path)) && e.path.length > depth) {
+            best = i
+            depth = e.path.length
+        }
+    }
+    return best
+}
+
+// pathAlias is the pane's remembered gvfs share (or null); its key is the share's normalized address.
+function litView(trashOpened, recentMode, searchMode, answeredQuery, pathAlias) {
+    if (trashOpened || recentMode === "trash") return { kind: "trash" }
+    if (String(recentMode || "").length > 0) return { kind: "recent" }
+    var query = String(answeredQuery || "")
+    if (String(searchMode || "").length > 0 && query.indexOf("tag:") === 0) return { kind: "tag", tag: query.substring(4) }
+    return { kind: "dir", shareKey: pathAlias ? String(pathAlias.key || "") : "" }
+}

package/ui/js/PreviewAsk.js

@@ -0,0 +1,21 @@
+.pragma library
+
+.import "PreviewSettle.js" as PreviewSettle
+.import "ExtThumbs.js" as ExtThumbs
+
+// The cursor row's single thumbnail ask, shared by the early ask and load()'s askThumb, so the second sends nothing twice.
+
+// Sample input: canRead, storageKnown, one selection, index 3, rowT, unasked, local storage answers {ask: [3], drop: [], cacheOnly: false}.
+function workFor(o) {
+    if (!o.canRead || !o.storageKnown || o.selectionCount > 1) return null
+    if (o.index < 0 || o.rowT !== true || o.asked === true) return null
+    return { ask: [o.index], drop: [], cacheOnly: ExtThumbs.cacheOnly(o.storageClass, o.preview) }
+}
+
+// The idle half of the early ask is the settle's own rule: a walk step trails and asks nothing early.
+function earlyWorkFor(o) {
+    if (PreviewSettle.plan(o.now, o.lastMoveAt, o.interval, o.key, o.lastMoveKey, o.armed, o.pending) !== "now")
+        return null
+    if (ExtThumbs.manualHold(o.storageClass, o.preview)) return null
+    return workFor(o)
+}

package/ui/js/PreviewKeys.js

@@ -0,0 +1,155 @@
+.pragma library
+
+.import "Filter.js" as Filter
+.import "Marks.js" as Marks
+.import "Search.js" as Search
+.import "Thumbs.js" as Thumbs
+.import "Scroll.js" as Scroll
+
+// What the preview overlay does with a key, split out of Focus.js at its 300-line hard cap the
+// same way ui/js/Trash.js was: Focus.js decides which surface owns a key, and this is the surface.
+
+// Left/Right's seek step, Task 22's operator ruling; act is the only reader.
+var SEEK_MS = 5000
+// The zoom ladder Quick Look's PDF strip walks: the bottom rung fits the frame, one step a press, up to four times.
+var PDF_ZOOM_MIN = 1
+var PDF_ZOOM_MAX = 4
+var PDF_ZOOM_STEP = 0.25
+
+// A zoom after steps presses (negative steps down), kept on the ladder; the image pane walks the same rungs as the PDF.
+function zoomStep(zoom, steps) {
+    return Math.max(PDF_ZOOM_MIN, Math.min(PDF_ZOOM_MAX, zoom + steps * PDF_ZOOM_STEP))
+}
+
+// All advertised page keys share one route in Quick Look and the preview column.
+function pageDirection(action) {
+    if (action === "pageDown" || action === "previewPageForward") return 1
+    if (action === "pageUp" || action === "previewPageBack") return -1
+    return 0
+}
+
+function pageViewport(view, direction) {
+    if (!view || !direction) return
+    if (typeof view.cancelFlick === "function") view.cancelFlick()
+    Scroll.stopTail(view)
+    var bounds = Scroll.limitsY(view)
+    view.contentY = Math.max(bounds.min, Math.min(bounds.max, view.contentY + direction * view.height))
+    if (typeof view.forceLayout === "function") view.forceLayout()
+}
+
+// The column's PDF has no strip: pages scroll, and Space, Return or e opens Quick Look at the page in view.
+function columnPdfAction(action, viewer) {
+    if (pageDirection(action)) { viewer.pageBy(pageDirection(action)); return }
+    if (action === "open" || action === "preview" || action === "expand") viewer.toggleExpand()
+    else if (action === "seekBack" || action === "parent") viewer.turnPage(-1)
+    else if (action === "seekForward" || action === "pageForward") viewer.turnPage(1)
+    else if (action === "cursorDown" || action === "cursorUp") viewer.scrollPage(action === "cursorDown" ? 1 : -1)
+}
+
+function pdfAction(action, viewer) {
+    if (pageDirection(action)) { viewer.pageBy(pageDirection(action)); return }
+    var controls = viewer.pdfControls
+    if (controls === undefined) return columnPdfAction(action, viewer)
+    if (action === "focusNext" || action === "focusPrevious") {
+        var step = action === "focusPrevious" ? -1 : 1
+        var next = viewer.pdfControlIndex
+        if (next < 0) next = step > 0 ? -1 : 0
+        for (var i = 0; i < controls.length; i++) {
+            next = (next + step + controls.length) % controls.length
+            if (controls[next].enabled && controls[next].visible) {
+                viewer.pdfControlIndex = next
+                break
+            }
+        }
+    } else if (action === "open" || action === "preview") {
+        var control = controls[viewer.pdfControlIndex]
+        if (control && control.enabled && control.visible) control.activated()
+    } else if (action === "seekBack" || action === "parent") viewer.turnPage(-1)
+    else if (action === "seekForward" || action === "pageForward") viewer.turnPage(1)
+    else if (action === "zoomOut") viewer.zoomBy(-1)
+    else if (action === "zoomIn") viewer.zoomBy(1)
+    else if (action === "expand") viewer.toggleExpand()
+    else if (action === "cursorDown" || action === "cursorUp") viewer.scrollPage(action === "cursorDown" ? 1 : -1)
+}
+
+// Space on a folder is a silent no-op; a file carries its cached thumbnail so the overlay shows it at once.
+function open(root) {
+    if (!Filter.cursorShown(root)) return
+    var row = root.rowFor(root.cursorIndex)
+    if (row && !row.d)
+        root.quickLook().open(root.join(Search.baseOf(root), row.n), row.i, row.s, root.kindNames[row.k] || "",
+            root.thumbState && root.thumbState.file ? Thumbs.fileFor(root.thumbState, root.cursorIndex) : "")
+}
+
+// Preview open: j/k move the cursor and the preview follows; escape always closes, and so does a
+// second space, on every kind including media (decided 2026-09-11: pressing Space a second time
+// closes the preview, the way Finder does). That reverses Task 22, which had space toggle
+// play/pause on a media preview; the strip's own play control still does that with the pointer.
+// Any key reveals the media strip, even one that does nothing else, matching "move the mouse or
+// press anything" from the same ruling.
+function act(action, root) {
+    root.preview.revealStrip()
+    if (pageDirection(action)) { root.preview.pageBy(pageDirection(action)); return }
+    switch (action) {
+    // A Compare overlay names two files, so the cursor moving under it opens no other file in its place.
+    case "cursorDown":
+    case "cursorUp":
+        var direction = action === "cursorDown" ? 1 : -1
+        if (!root.preview.isCompare) { Filter.moveCursor(root, direction); Marks.follow(root); follow(root) }
+        return
+    case "preview": root.preview.close(); return
+    // Space closes every kind now, so playback has its own key; it self-guards, because p reaches
+    // this only in the media context and a still image has nothing to play.
+    case "playPause":
+        if (root.preview.isMedia) root.preview.togglePlay()
+        return
+    case "focusPreview":
+    case "escape": root.preview.close(); return
+    // Compare's y: the whole patch goes to the clipboard; the overlay guards on its own kind.
+    case "copyPatch": root.preview.copyPatch(); return
+    case "seekBack":
+        if (root.preview.isPdf) root.preview.turnPage(-1)
+        else root.preview.seek(-SEEK_MS)
+        return
+    case "seekForward":
+        if (root.preview.isPdf) root.preview.turnPage(1)
+        else root.preview.seek(SEEK_MS)
+        return
+    // h keeps its own "parent" name from keys.toml; turnPage self-guards, so a media preview
+    // ignores both of these rather than seeking on a key the strip never advertised.
+    case "parent": root.preview.turnPage(-1); return
+    case "pageForward": root.preview.turnPage(1); return
+    case "zoomOut": root.preview.zoomBy(-1); return
+    case "zoomIn": root.preview.zoomBy(1); return
+    case "zoomFit": root.preview.zoomFit(); return
+    case "expand": root.preview.toggleExpand(); return
+    // MediaMute rule 5: the flag is the preview's to flip, and it silences without pausing.
+    case "mute": root.preview.toggleMute(); return
+    // r flips only the open document Quick Look between rendered and source.
+    case "markdownView":
+        if (root.preview.isDocument) root.preview.toggleMarkdownView()
+        return
+    // Focus.js lets w through for a code or text Quick Look only; the choice is remembered in ui.json.
+    case "toggleWrap": root.preview.toggleWrap(); return
+    // The text bar toggles Close; Compare owns its actual Copy and Close focus walk.
+    case "focusNext":
+    case "focusPrevious":
+        if (root.preview.isCompare) {
+            var compare = root.preview.surfaceItem()
+            if (compare) compare.stepFocus(action === "focusPrevious")
+        } else if (root.preview.hasBar) root.preview.toggleMarkdownClose()
+        return
+    case "open":
+        if (root.preview.hasBar && root.preview.markdownCloseFocused) root.preview.close()
+        return
+    }
+}
+
+// The row under the moved cursor, handed to Preview.follow so a held key settles before it reloads.
+function follow(root) {
+    if (!Filter.cursorShown(root)) return
+    var row = root.rowFor(root.cursorIndex)
+    if (row && !row.d)
+        root.preview.follow(root.join(Search.baseOf(root), row.n), row.i, row.s, root.kindNames[row.k] || "",
+            root.thumbState && root.thumbState.file ? Thumbs.fileFor(root.thumbState, root.cursorIndex) : "")
+}

package/ui/js/PreviewSettle.js

@@ -0,0 +1,29 @@
+.pragma library
+
+// Cursor preview loads stamp distinct moves: due(200, 0, 120) and due(100, 200, 120) load now; due(50, 0, 120) trails.
+function due(now, last, interval) {
+    var elapsed = now - last
+    return elapsed >= interval || elapsed < 0
+}
+
+// A settle armed for this row before its move reached the clock (ColumnsArea's folder to file step) is left to the clock.
+// plan(50, 0, 120, "b", "b", true) keeps the pending timer; plan(1000, 0, 120, "c", "b", true, false) is "now".
+function plan(now, last, interval, key, lastKey, armedForKey, pending) {
+    if (key === lastKey && armedForKey === true)
+        return "same"
+    if (pending === true)
+        return "later"
+    return due(now, last, interval) ? "now" : "later"
+}
+
+// A PDF opens at once only when the cursor is idle and no page render is in flight.
+function pdfOpenNow(now, lastRequestAt, intervalMs, renderLoading) {
+    return renderLoading !== true && due(now, lastRequestAt, intervalMs)
+}
+
+// A lone selection never keys on the version Marks.follow bumps on every plain move.
+function selectionKey(count, version) {
+    if (count <= 1)
+        return ""
+    return count + ":" + version
+}

package/ui/js/PreviewSwap.js

@@ -0,0 +1,101 @@
+.pragma library
+
+.import "Swap.js" as Swap
+.import "Facts.js" as Facts
+
+// The preview swap's decisions, see AGENTS.md "The preview swap"; ui/PreviewSwap.qml holds the picture and the timer.
+
+// ui/PreviewPdf.qml opens a document only this long after its path settles (issue 117).
+var DOCUMENT_SETTLE_MS = 120
+
+// A capture draws on the next frame; one not drawn in this long means the window is not drawing at all.
+var CAPTURE_MS = 100
+
+// How long the new preview may build under the held picture from its own start; a PDF's document settle runs under it.
+function capMs(isPdf) {
+    return Swap.CAP_MS
+}
+
+// When a held preview lets go: -1 while the new one is not whole, else the ms a loading state on screen is still owed.
+function releaseIn(ready, started, shownAt, now) {
+    if (ready !== true || started !== true)
+        return -1
+    return Swap.showLeft(shownAt, now)
+}
+
+// Past the cap the loading state stands from shownAt or now; sample input: fallBack(true, 0, 1066) is { shownAt: 1066, left: 100, keeps: true }.
+function fallBack(held, shownAt, now) {
+    var at = shownAt > 0 ? shownAt : now
+    var left = Swap.showLeft(at, now)
+    return { shownAt: at, left: left, keeps: held === true && left > 0 }
+}
+
+// What a move does to a swap: start a hold, join the one already starting for this key, or, when the
+// host lets a burst end it, give up a picture that no longer names anything near the cursor.
+var HOLD = "hold"
+var JOIN = "join"
+var BURST = "burst"
+
+function onMove(state, key, burstEnds) {
+    if (!state.capturing && !state.holding)
+        return HOLD
+    if (state.key === key || burstEnds !== true)
+        return JOIN
+    return BURST
+}
+
+// A frame drawn with the swap in each state: "held" shows the old picture, "mid" is the defect a hold
+// exists to prevent, "loading" is the fallback's own state and allowed, held in the picture or live.
+function frameKind(held, ready, fellBack, showing) {
+    if (showing === true)
+        return "loading"
+    if (held === true)
+        return "held"
+    if (ready === true)
+        return ""
+    return fellBack === true ? "loading" : "mid"
+}
+
+// Sample input: { state: "image", thumb: true, frame: 1, noThumbComing: false, pdfDrawn: false,
+// pdfFailed: false, linesLoading: false, meta: true } for the preview column's cursor row, where frame is the
+// thumbnail Image's status (Image.Null 0, Ready 1, Loading 2, Error 3).
+function columnReady(p) {
+    switch (p.state) {
+    case Facts.LOADING:
+        return false
+    case Facts.IMAGE:
+        // The cache file, or with none coming the original the frame decodes itself, drawn or refused.
+        return (p.thumb === true || p.noThumbComing === true) && (p.frame === 1 || p.frame === 3)
+    case Facts.VIDEO:
+        // The poster drawn or refused, or none coming at all and the kind's mark standing in.
+        return p.thumb === true ? p.frame === 1 || p.frame === 3 : p.noThumbComing === true
+    case Facts.PDF:
+        return p.pdfDrawn === true || p.pdfFailed === true
+    case Facts.TEXT:
+    case Facts.CODE:
+        return p.linesLoading !== true
+    case Facts.ARCHIVE:
+        return p.meta === true
+    }
+    return true
+}
+
+// Quick Look is ready when nothing loads, a PDF shows a page or is refused, or the interim or a Markdown head shows whole.
+function lookReady(status, isPdf, pdfShown, pdfFailed, interimShown, headShown) {
+    if (interimShown === true || headShown === true)
+        return true
+    if (status === "loading")
+        return false
+    return isPdf !== true || pdfShown === true || pdfFailed === true
+}
+
+// Sample input: interimRect(754, 471, 6000, 4000, 1) is 706.5x471 at 24,0; upright aspect-fit, never enlarged, unknown is null.
+function interimRect(surfaceW, surfaceH, imageW, imageH, orient) {
+    if (!(imageW > 0) || !(imageH > 0))
+        return null
+    var ow = orient >= 5 ? imageH : imageW
+    var oh = orient >= 5 ? imageW : imageH
+    var s = Math.min(1, surfaceW / ow, surfaceH / oh)
+    var w = ow * s, h = oh * s
+    return { x: Math.round((surfaceW - w) / 2), y: Math.round((surfaceH - h) / 2), w: w, h: h }
+}