plexora 0.0.1__py3-none-any.whl

plexora/client/src/js/pluginRegistry.js

@@ -0,0 +1,108 @@
+/**
+ * pluginRegistry.js - where client-side plugins announce themselves.
+ *
+ * A plugin's script self-registers at load time; main.js then activates
+ * whatever is registered. Core never names a concrete plugin class.
+ *
+ * This replaces window.AppModules, which held an array core only ever read as
+ * `registry[0]` -- a single slot dressed up as a list, matching the old
+ * one-module-per-process server. Several plugins can now be active at once, so
+ * registration is keyed by name and activation iterates.
+ *
+ * Plugin definition (only `name` is required):
+ *
+ *   Plexora.registerPlugin({
+ *     name: "gating",
+ *
+ *     // Build the plugin's main object. ctx: { config, columns, dataLayer,
+ *     // eventHandler, dataset, store, viewer, url, onCleanup }
+ *     createInstance(ctx): object,
+ *
+ *     // Optional sidebar panel controller. ctx adds { sidebar, instance }.
+ *     // May implement setup/fetchSaved/applyOrDefault/persistIfNeeded/onShow.
+ *     //
+ *     // onHide() is the counterpart of onShow(): toolLoader.js calls it when
+ *     // this tool's panel is closed or another tool is opened over it. A
+ *     // controller that only owns widgets inside its own panel can ignore it --
+ *     // the panel is merely hidden and its state is kept, which is what makes
+ *     // reopening instant. One that reaches OUTSIDE its panel must not: viewer
+ *     // canvas handlers and document-level keyboard shortcuts go on listening
+ *     // to a panel the user cannot see, so two tools loaded at once both act on
+ *     // the same keypress. Stand those down in onHide() and re-arm in onShow().
+ *     //
+ *     // onVisibilityChange(on) is a different question from onShow/onHide, and
+ *     // the difference is the point of the card model: SHOWN is "this is the
+ *     // tool being worked on", VISIBLE is "this tool's drawing is on screen".
+ *     // A plugin that colours cells needs nothing here -- core switches its
+ *     // layer for it. A plugin that draws its own overlay (ROI) does, or the
+ *     // eye on its card is a button with nothing behind it.
+ *     createSidebarController(ctx): object | null,
+ *
+ *     // Wire event-bus handlers. ctx adds { viewer, channelList, instance }
+ *     // plus the core actions updateSeaDragonSelection /
+ *     // updateCentroidsForGate / runSegmentationGate.
+ *     bindEvents(ctx): void,
+ *
+ *     // Declares that this plugin draws cells in the viewer. It gets a LAYER of
+ *     // its own -- its own colours, its own gate, its own mode and opacity --
+ *     // and a card in the sidebar. Several may be live at once and the card
+ *     // order is the order they composite in, so a phenotype map and a gate can
+ *     // be looked at together. See ImageViewer.registerCellLayer.
+ *     ownsCellLayer: boolean,
+ *
+ *     // How this plugin would like the mask drawn when its layer is first
+ *     // turned on: "filled" | "outlines" | "centroids". A tool that colours
+ *     // every cell by a phenotype wants filled; one that marks a few cells
+ *     // wants outlines over visible tissue. Ignored when the project's recorded
+ *     // layer or the mask itself cannot do it, and it never overrules a choice
+ *     // the user has already made. Defaults to "outlines". See enableCellLayer.
+ *     preferredCellMode: string,
+ *
+ *     // Which representations this plugin can actually work with, as a subset
+ *     // of ["centroids", "outlines", "filled"]. The shared Cells control offers
+ *     // the intersection of this and what the project can draw while this
+ *     // plugin's layer is the active one, so a tool that has no use for one of
+ *     // them is not offering a button whose result it did not design for.
+ *     // Omit for "whatever the project can do", which is the common case.
+ *     supportedCellModes: string[],
+ *
+ *     // Release anything global. Called before the plugin is torn down.
+ *     // Prefer ctx.onCleanup(fn), which is invoked for you.
+ *     destroy(): void,
+ *   });
+ */
+window.Plexora = window.Plexora || {};
+
+window.Plexora.plugins = (function () {
+    const byName = new Map();
+
+    return {
+        /** Register a plugin definition. Re-registering a name replaces it,
+         *  which is what makes a script that gets loaded twice harmless. */
+        register(definition) {
+            if (!definition || !definition.name) {
+                console.error("Plexora.registerPlugin: definition needs a name", definition);
+                return;
+            }
+            byName.set(definition.name, definition);
+        },
+
+        get(name) {
+            return byName.get(name) || null;
+        },
+
+        /** Every registered definition, in registration order. */
+        all() {
+            return Array.from(byName.values());
+        },
+
+        get size() {
+            return byName.size;
+        },
+    };
+})();
+
+/** Convenience alias, so a plugin script reads as one call. */
+window.Plexora.registerPlugin = function (definition) {
+    window.Plexora.plugins.register(definition);
+};

plexora/client/src/js/services/appStatus.js

@@ -0,0 +1,286 @@
+/**
+ * PlexoraStatus -- the application's single status indicator.
+ *
+ * Lives at the far right of the navbar on every page that extends base.html.
+ * Three states, using the shared accent tokens from tokens.css:
+ *
+ *   green  "Live"          nothing outstanding, the view is current
+ *   orange <1-2 word label> something is running that has no other visible sign
+ *   red    <short reason>   the server is unreachable, or a request failed
+ *
+ * Why this exists as one system rather than per feature: the app used to
+ * indicate work with `d3.select("body").style("cursor", "progress")` at two
+ * call sites in main.js -- both of which set and cleared the cursor
+ * *synchronously around an async call*, so they were on screen for microseconds
+ * and told the user nothing -- plus an opacity fade on individual auto buttons.
+ * Anything slow that wasn't one of those (auto-contrast, tiles streaming in
+ * after a channel toggle) was completely silent, which is what made a slow
+ * operation feel like a broken one.
+ *
+ * Usage:
+ *   const task = PlexoraStatus.begin("Auto-contrast");
+ *   ... ; task.done();                       // or task.fail("Fit failed")
+ *   await PlexoraStatus.track("Saving", promise);
+ *
+ * Tasks are refcounted, so overlapping work from unrelated features composes
+ * without either one clearing the other's indication. The label shown is the
+ * most recently begun task.
+ *
+ * Loaded early and NOT deferred, because it wraps window.fetch and must be in
+ * place before any other script issues a request.
+ */
+(function () {
+    "use strict";
+
+    const LIVE_LABEL = "Live";
+    // Don't flash orange for work that finishes almost immediately -- a warm
+    // channel toggle is ~120 ms and a blink there reads as a glitch.
+    const SHOW_DELAY_MS = 150;
+    // ...and once shown, hold it long enough to actually be read.
+    const MIN_BUSY_MS = 400;
+    // One dropped poll is a hiccup; two in a row is a dead server. At 5 s that
+    // bounds the "server died while the page sat idle" detection at ~10 s --
+    // measured 16 s at a 10 s interval, which is a long time to keep claiming
+    // everything is fine. The probe does no work server-side, so the extra
+    // traffic is 12 empty 204s a minute.
+    const HEALTH_INTERVAL_MS = 5000;
+    const HEALTH_FAILURES_BEFORE_ERROR = 2;
+
+    const tasks = new Map();
+    let nextId = 1;
+    let errorLabel = null;
+    let healthFailures = 0;
+    let unloading = false;
+
+    let rootEl = null;
+    let labelEl = null;
+    let rendered = null;
+    let showTimer = null;
+    let hideTimer = null;
+    let busySince = 0;
+
+    function desiredState() {
+        if (errorLabel) return { state: "error", label: errorLabel };
+        if (tasks.size) {
+            let label = LIVE_LABEL;
+            for (const value of tasks.values()) label = value;  // most recent wins
+            return { state: "busy", label };
+        }
+        return { state: "live", label: LIVE_LABEL };
+    }
+
+    function paint(next) {
+        rendered = next;
+        if (!rootEl) return;
+        rootEl.dataset.state = next.state;
+        rootEl.setAttribute("title", next.state === "error"
+            ? `Plexora: ${next.label}`
+            : next.state === "busy" ? `Plexora is working: ${next.label}` : "Plexora is up to date");
+        if (labelEl.textContent !== next.label) labelEl.textContent = next.label;
+    }
+
+    function sync() {
+        const next = desiredState();
+
+        if (next.state === "error") {
+            if (showTimer) { clearTimeout(showTimer); showTimer = null; }
+            if (hideTimer) { clearTimeout(hideTimer); hideTimer = null; }
+            paint(next);
+            return;
+        }
+
+        if (next.state === "busy") {
+            if (hideTimer) { clearTimeout(hideTimer); hideTimer = null; }
+            if (rendered && rendered.state === "busy") { paint(next); return; }
+            if (showTimer) return;
+            showTimer = setTimeout(() => {
+                showTimer = null;
+                const now = desiredState();
+                if (now.state === "busy") { busySince = Date.now(); paint(now); }
+            }, SHOW_DELAY_MS);
+            return;
+        }
+
+        // Going back to live.
+        if (showTimer) { clearTimeout(showTimer); showTimer = null; }
+        if (rendered && rendered.state === "busy") {
+            const held = Date.now() - busySince;
+            if (held < MIN_BUSY_MS) {
+                if (!hideTimer) {
+                    hideTimer = setTimeout(() => { hideTimer = null; sync(); }, MIN_BUSY_MS - held);
+                }
+                return;
+            }
+        }
+        paint(next);
+    }
+
+    function begin(label) {
+        const id = nextId++;
+        tasks.set(id, String(label || "Working"));
+        sync();
+        let settled = false;
+        return {
+            done() {
+                if (settled) return;
+                settled = true;
+                tasks.delete(id);
+                sync();
+            },
+            fail(reason) {
+                if (settled) return;
+                settled = true;
+                tasks.delete(id);
+                setError(reason || "Error");
+            },
+            relabel(next) {
+                if (settled) return;
+                tasks.set(id, String(next));
+                sync();
+            },
+        };
+    }
+
+    function track(label, promise) {
+        const task = begin(label);
+        return Promise.resolve(promise).then(
+            (value) => { task.done(); return value; },
+            (err) => { task.done(); throw err; },
+        );
+    }
+
+    function setError(label) {
+        errorLabel = String(label || "Error");
+        sync();
+    }
+
+    function clearError() {
+        if (!errorLabel) return;
+        errorLabel = null;
+        sync();
+    }
+
+    // --- transport: every fetch in the app reports its own health -----------
+    // Wrapping once here covers all ~40 call sites (26 in dataLayer.js alone,
+    // each with its own try/catch that swallows the failure) without touching
+    // any of them. Deliberately does NOT mark requests busy: most are fast, and
+    // a generic label would be less useful than the specific ones features
+    // supply via begin(). Errors are the part no feature reports today.
+    const nativeFetch = window.fetch ? window.fetch.bind(window) : null;
+    if (nativeFetch) {
+        window.fetch = function plexoraFetch(...args) {
+            return nativeFetch(...args).then((response) => {
+                if (response.status >= 500) {
+                    setError(`Server error ${response.status}`);
+                } else {
+                    healthFailures = 0;
+                    clearError();
+                }
+                return response;
+            }, (err) => {
+                // A request cancelled by navigation isn't a server problem.
+                if (!unloading && !(err && err.name === "AbortError")) {
+                    setError("Disconnected");
+                }
+                throw err;
+            });
+        };
+    }
+
+    window.addEventListener("beforeunload", () => { unloading = true; });
+
+    // --- transport: liveness while idle -------------------------------------
+    // An idle page issues no requests, so without this a server that died five
+    // minutes ago still shows green. Uses nativeFetch so a failed poll doesn't
+    // recurse through the wrapper's own error handling.
+    function pollHealth() {
+        if (!nativeFetch || document.visibilityState !== "visible") return;
+        nativeFetch(plexoraUrl("health"), { cache: "no-store" }).then((r) => {
+            if (!r.ok) throw new Error(String(r.status));
+            healthFailures = 0;
+            clearError();
+        }).catch(() => {
+            healthFailures += 1;
+            if (healthFailures >= HEALTH_FAILURES_BEFORE_ERROR) setError("Disconnected");
+        });
+    }
+
+    // --- viewer: tiles still streaming in -----------------------------------
+    // "A channel was switched on but hasn't finished loading."
+    //
+    // Tracked per TiledImage rather than through the Viewer's aggregate
+    // fully-loaded-change: that aggregate only recomputes when some TiledImage
+    // raises its own fully-loaded-change, and a freshly added image doesn't
+    // raise anything on the way in (it starts un-loaded, which is not a change
+    // for it). So the viewer's cached _fullyLoaded stays true through the whole
+    // load and then matches again once the image finishes -- meaning it fires
+    // no event at all for a newly added channel. Verified: zero events across a
+    // channel toggle.
+    //
+    // Tiles go through OSD's own XHR rather than fetch, so tile-load-failed is
+    // the only way this path can surface an error.
+    function watchViewer(viewer) {
+        if (!viewer || !viewer.addHandler || viewer.__plexoraStatusWatched) return;
+        viewer.__plexoraStatusWatched = true;
+
+        const pending = new Set();
+        let loading = null;
+        function refresh() {
+            if (pending.size && !loading) {
+                loading = begin("Loading");
+            } else if (!pending.size && loading) {
+                loading.done();
+                loading = null;
+            }
+        }
+        function trackItem(item) {
+            if (!item || !item.addHandler || item.__plexoraStatusTracked) return;
+            item.__plexoraStatusTracked = true;
+            const update = () => {
+                if (item.getFullyLoaded && item.getFullyLoaded()) pending.delete(item);
+                else pending.add(item);
+                refresh();
+            };
+            item.addHandler("fully-loaded-change", update);
+            update();
+        }
+        function forget(item) {
+            pending.delete(item);
+            refresh();
+        }
+
+        if (viewer.world) {
+            viewer.world.addHandler("add-item", (event) => trackItem(event.item));
+            viewer.world.addHandler("remove-item", (event) => forget(event.item));
+            for (let i = 0; i < viewer.world.getItemCount(); i++) {
+                trackItem(viewer.world.getItemAt(i));
+            }
+        }
+        viewer.addHandler("tile-load-failed", () => setError("Tile failed"));
+        viewer.addHandler("close", () => { pending.clear(); refresh(); });
+    }
+
+    // --- mount ---------------------------------------------------------------
+    function mount() {
+        rootEl = document.getElementById("app_status");
+        if (!rootEl) return;
+        rootEl.classList.add("app-status");
+        rootEl.innerHTML =
+            '<span class="app-status-glyph" aria-hidden="true"></span>' +
+            '<span class="app-status-label"></span>';
+        labelEl = rootEl.querySelector(".app-status-label");
+        rootEl.setAttribute("role", "status");
+        rootEl.setAttribute("aria-live", "polite");
+        rendered = null;
+        paint(desiredState());
+        window.setInterval(pollHealth, HEALTH_INTERVAL_MS);
+    }
+
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", mount);
+    } else {
+        mount();
+    }
+
+    window.PlexoraStatus = { begin, track, setError, clearError, watchViewer };
+})();

plexora/client/src/js/services/browsePicker.js

@@ -0,0 +1,73 @@
+/**
+ * browsePicker.js -- shared client for POST /browse_path (see
+ * server/utils/native_dialog.py), which pops a native OS file/folder dialog
+ * on the machine the server runs on and hands back the chosen path. Used by
+ * both the quick-view landing page and the upload page's per-field "Browse..."
+ * buttons; only works when there's a real desktop session for the dialog to
+ * appear on, so every caller needs an `onUnavailable` fallback (e.g. a manual
+ * text input) for the headless/remote-server case.
+ */
+
+/**
+ * @function browseForPath - opens a native file ("file") or folder
+ * ("directory") dialog and calls back with the chosen path.
+ * @param mode - "file" or "directory"
+ * @param filter - narrows the file-type dropdown for mode="file": one of
+ *   "image", "csv", "h5ad", or "any" (default -- just "All files"). Ignored
+ *   for mode="directory". Must match one of native_dialog.py's FILTERS keys.
+ * @param onPicked - called with the chosen path string; not called if the
+ *   user cancels the dialog (result.path === null)
+ * @param onUnavailable - called (with the error) if the dialog itself
+ *   couldn't be shown at all -- no desktop session, tkinter missing, etc.
+ */
+async function browseForPath({mode = "file", filter = "any", onPicked, onUnavailable} = {}) {
+    try {
+        const response = await fetch(plexoraUrl("browse_path"), {
+            method: "POST",
+            headers: {"Content-Type": "application/json"},
+            body: JSON.stringify({mode: mode, filter: filter}),
+        });
+        const result = await response.json();
+        if (!response.ok) {
+            throw new Error(result.error);
+        }
+        if (result.path && onPicked) {
+            onPicked(result.path);
+        }
+        // result.path === null just means the user cancelled the dialog.
+    } catch (error) {
+        if (onUnavailable) {
+            onUnavailable(error);
+        }
+    }
+}
+
+/**
+ * @function attachBrowseButton - wires a "Browse..." button to fill a text
+ * input with the picked path, dispatching an `input` event afterward so any
+ * existing onkeyup/oninput live-validation on that field runs unchanged.
+ */
+function attachBrowseButton(buttonEl, inputEl, {mode = "file", filter = "any"} = {}) {
+    if (!buttonEl || !inputEl) return;
+    buttonEl.addEventListener("click", () => {
+        browseForPath({
+            mode,
+            filter,
+            onPicked: (path) => {
+                inputEl.value = path;
+                inputEl.dispatchEvent(new Event("input"));
+                inputEl.dispatchEvent(new Event("keyup"));
+            },
+            // A dialog that cannot be shown must say so. This used to swallow
+            // the error, which turned a rejected filter name into a button
+            // that looked ordinary and did nothing when clicked -- with the
+            // path input right next to it, there was no way to tell the
+            // difference between "no dialog here" and "this button is broken".
+            onUnavailable: (error) => {
+                console.error("browsePicker: could not open the file dialog.", error);
+                window.PlexoraStatus?.begin?.("Browse")?.fail?.(
+                    error?.message || "Could not open the file browser — type the path instead.");
+            },
+        });
+    });
+}