plexora 0.0.1__py3-none-any.whl

plexora/plugins/figure_builder/server/sources.py

@@ -0,0 +1,120 @@
+"""Identifying a source image, and noticing when it has changed underneath.
+
+A figure keeps a reference, not a copy. That is what makes it small and what
+makes it fragile in one specific way: the project it points at can be re-imported
+with a different slide, have its channels renamed, or be deleted. A panel drawn
+on the old image renders perfectly plausibly on the new one, in the wrong place,
+and nothing about the pixels says otherwise.
+
+So every source carries a fingerprint taken at capture time, and it is compared
+on open. The comparison never rerenders anything: it produces `ok`, `changed`
+or `missing`, and a `changed` source keeps its cached preview until the user
+says what should happen. Silently re-rendering a scientifically established
+panel from materially different data is the one outcome this whole module
+exists to prevent.
+
+**Nothing here loads a datasource.** Everything is read from the project record
+(config.json), which is why this can be asked about eight sources in a row
+without evicting the one the user is actually looking at -- `data_model` holds a
+single loaded datasource behind a lock, and touching it here would make opening
+a figure library unload the viewer.
+
+The one fact that is NOT in the record is the physical pixel size, which lives
+in the OME metadata and only comes back through a loader. It is therefore
+captured client-side, at the moment of capture, for the datasource already on
+screen -- and stored on the source. See `figureSceneSnapshot.js`.
+"""
+
+from __future__ import annotations
+
+from plexora import api
+
+
+def channel_key(channel) -> str:
+    """The stable id of one image channel.
+
+    The last segment of the tile URL (`/generated/data/<ds>/<key>/`), which is
+    generated at import from the file name and the channel's position. It
+    survives renaming, which `fullname` is precisely what does not: a user who
+    relabels "LSP20209_2" as "CD8a" has not changed which channel it is, and a
+    figure that identified it by name would lose it.
+    """
+    src = (channel or {}).get("src") or ""
+    return src.strip("/").rsplit("/", 1)[-1]
+
+
+def describe(datasource) -> dict:
+    """What a figure records about a project image, ready to store as a source.
+
+    Raises KeyError if there is no such project.
+    """
+    handle = api.dataset(datasource)
+    width, height = handle.image.size
+    channels = [
+        {"key": channel_key(channel),
+         "fullname_at_capture": channel.get("fullname") or channel.get("name") or ""}
+        for channel in handle.image.channels
+        if channel_key(channel)
+    ]
+    return {
+        "kind": "plexora_project",
+        "datasource": datasource,
+        "display_name": datasource,
+        "image": {"width": int(width or 0), "height": int(height or 0)},
+        "channels": channels,
+        "fingerprint": fingerprint(datasource),
+        "status": "ok",
+    }
+
+
+def fingerprint(datasource) -> dict:
+    """The cheap identity check: dimensions, channel keys, mask present.
+
+    Deliberately not a hash of the pixels. Hashing a 40 GB pyramid to answer
+    "is this still the same slide" is a check nobody runs twice, and these four
+    facts catch every re-import that would put a panel in the wrong place.
+    """
+    handle = api.dataset(datasource)
+    width, height = handle.image.size
+    return {
+        "image_width": int(width or 0),
+        "image_height": int(height or 0),
+        "channel_keys": [channel_key(c) for c in handle.image.channels if channel_key(c)],
+        "has_segmentation": bool(handle.segmentation.available),
+    }
+
+
+def status_of(source) -> dict:
+    """Compare a stored source against the project it names.
+
+    Returns `{status, reasons, fingerprint}`. `reasons` is a list of short codes
+    -- never prose -- because the client branches on them and wording is not an
+    API.
+    """
+    if source.get("kind") != "plexora_project":
+        # An imported asset lives inside the figure's own directory; nothing
+        # outside can change it.
+        return {"status": "ok", "reasons": [], "fingerprint": source.get("fingerprint") or {}}
+
+    datasource = source.get("datasource") or ""
+    try:
+        current = fingerprint(datasource)
+    except KeyError:
+        return {"status": "missing", "reasons": ["no_such_project"], "fingerprint": {}}
+
+    stored = source.get("fingerprint") or {}
+    reasons = []
+    if stored.get("image_width") and (stored.get("image_width"), stored.get("image_height")) != (
+            current["image_width"], current["image_height"]):
+        reasons.append("dimensions_changed")
+    stored_keys = set(stored.get("channel_keys") or [])
+    if stored_keys and not stored_keys.issubset(set(current["channel_keys"])):
+        reasons.append("channels_removed")
+    if stored.get("has_segmentation") and not current["has_segmentation"]:
+        reasons.append("segmentation_removed")
+
+    return {
+        "status": "changed" if reasons else "ok",
+        "reasons": reasons,
+        "fingerprint": current,
+    }

plexora/plugins/figure_builder/server/textmetrics.py

@@ -0,0 +1,155 @@
+"""Typographic constants, in one table, for three renderers.
+
+The canvas, the PDF writer and the raster writer all have to put a baseline in
+the same place. They cannot share code -- one of them is JavaScript -- so they
+share a TABLE instead, and `figureRichText.js` carries a copy that
+`test_the_two_sides_agree_on_the_typographic_constants` holds equal to this one.
+That is the same arrangement as `export._arrow_head` and
+`FigureCanvas.arrowHeadPoints`: one rule, two languages, pinned by a test.
+
+Only the twelve Adobe core fonts are offered, and that is a deliberate ceiling
+rather than a first step. reportlab knows their metrics without a font file, so
+nothing has to ship, nothing has to be licensed, and no export can fail because
+a font did not load. The three families also have metric-compatible substitutes
+on every desktop platform -- Arial for Helvetica, Liberation Serif for Times,
+Courier New for Courier -- so a browser measuring a string gets the same answer
+the PDF writer will, which is what makes "wrap as you type" safe to store.
+
+Sizes here are in POINTS and positions in MILLIMETRES, because that is the split
+the rest of the plugin already uses: type is specified in points and the page is
+measured in millimetres.
+"""
+
+from __future__ import annotations
+
+#: Millimetres in one typographic point. Computed rather than written out:
+#: `FigureCanvas.PT_PER_MM` is the rounded literal 2.8346 and the two must not
+#: be confused. Rounding here would put a floor under how exactly the canvas and
+#: the exporter can be asserted to agree.
+MM_PER_PT = 25.4 / 72.0
+
+#: Line box height as a multiple of the type size. 1.2 is the usual default and
+#: replaces the 1.25 that `.fb-annotation-text` used to set in CSS -- the canvas
+#: no longer leaves leading to the browser, so the number has to live somewhere
+#: both languages can read it.
+LINE_HEIGHT = 1.2
+
+#: The type size a text box starts at, in points.
+#:
+#: NOT `settings.style.font_size_pt`, which is 8 and has to stay 8: that one is
+#: the size of the furniture drawn ON a panel -- legend rows and the scale bar's
+#: caption, both of which sit inside the image and have to be small enough to
+#: stay out of it (see compose._panel_furniture). A caption BESIDE a figure is
+#: read at a normal reading size, and it was inheriting the panel-label size
+#: instead -- `FigureCanvas.drawStyle` asked for `label_size_pt`, which is the
+#: size of the letter "A" in the corner of a panel and has nothing to do with a
+#: sentence.
+#:
+#: Overridable on every box, so this is only where a new one starts.
+DEFAULT_TEXT_SIZE_PT = 14.0
+
+#: Ascent and descent as a fraction of the em, from the Adobe core AFM files.
+#: Used to centre a line inside its line box, which is what makes vertical
+#: alignment and multi-size lines land in the same place on all three renderers.
+ASCENT = {
+    "Helvetica": 0.718,
+    "Times-Roman": 0.683,
+    "Courier": 0.629,
+}
+DESCENT = {
+    "Helvetica": 0.207,
+    "Times-Roman": 0.217,
+    "Courier": 0.157,
+}
+
+#: Underline and strike-through, as a fraction of the em from the baseline.
+#: Drawn explicitly by every renderer rather than delegated to `text-decoration`
+#: or whatever the PDF viewer would do: SVG takes its underline position from
+#: the font file actually in use, so a browser showing Arial and a PDF holding
+#: Helvetica would put the rule in two different places.
+UNDERLINE_OFFSET_EM = 0.12
+UNDERLINE_THICKNESS_EM = 0.06
+STRIKE_OFFSET_EM = 0.26
+
+#: The families a document may name. These are PostScript base names rather than
+#: abstract keys like "sans", because `settings.style.font_family` already holds
+#: "Helvetica" and hands it straight to reportlab's `setFont`. Keeping that
+#: vocabulary means a figure written by this build still renders in the right
+#: typeface in a build that predates this module.
+FAMILIES = ("Helvetica", "Times-Roman", "Courier")
+DEFAULT_FAMILY = "Helvetica"
+
+_POSTSCRIPT = {
+    ("Helvetica", False, False): "Helvetica",
+    ("Helvetica", True, False): "Helvetica-Bold",
+    ("Helvetica", False, True): "Helvetica-Oblique",
+    ("Helvetica", True, True): "Helvetica-BoldOblique",
+    ("Times-Roman", False, False): "Times-Roman",
+    ("Times-Roman", True, False): "Times-Bold",
+    ("Times-Roman", False, True): "Times-Italic",
+    ("Times-Roman", True, True): "Times-BoldItalic",
+    ("Courier", False, False): "Courier",
+    ("Courier", True, False): "Courier-Bold",
+    ("Courier", False, True): "Courier-Oblique",
+    ("Courier", True, True): "Courier-BoldOblique",
+}
+
+#: What the browser should ask for, per family. Every stack names substitutes
+#: that are metric-compatible with the core font, in the order they are likely
+#: to exist: Arial (Windows/macOS) and Liberation Sans (Linux) were both drawn
+#: to Helvetica's widths, so a line that fits on screen fits in the PDF.
+#:
+#: This lives here and not in the stylesheet so that the family list is one
+#: table. `figureRichText.js` carries the same three strings.
+CSS_STACK = {
+    "Helvetica": 'Helvetica, Arial, "Liberation Sans", sans-serif',
+    "Times-Roman": '"Times New Roman", Times, "Liberation Serif", serif',
+    "Courier": '"Courier New", Courier, "Liberation Mono", monospace',
+}
+
+
+def family(value):
+    """A family this build can draw, or the default.
+
+    Never raises. An unknown family is a style problem, and the document it
+    arrived in still has words in it worth showing.
+    """
+    return value if value in FAMILIES else DEFAULT_FAMILY
+
+
+def postscript_name(name, bold=False, italic=False):
+    """The PostScript font for one family and weight.
+
+    Raises `KeyError` on a family this module does not know, deliberately: by
+    the time a run reaches here it has been through `schema.normalize_annotation`
+    and its family is whitelisted, so a miss is a typo in `_POSTSCRIPT` or a
+    family added to the UI and not to this table. The export path catches it,
+    substitutes the default and says so on the provenance page rather than
+    silently shipping the wrong typeface.
+    """
+    return _POSTSCRIPT[(name, bool(bold), bool(italic))]
+
+
+def em_mm(size_pt):
+    """One em of this type size, in millimetres."""
+    return size_pt * MM_PER_PT
+
+
+def line_metrics(runs, line_height=LINE_HEIGHT):
+    """Height and baseline offset of the line box holding these runs.
+
+    The tallest run sets the line box, and the line is centred inside it -- half
+    the leading above, half below -- so that a line mixing an 8 pt caption with
+    a 6 pt superscript sits where a reader expects rather than riding on the
+    bottom of its box.
+
+    Returns `(lead_mm, ascent_mm, descent_mm)`, where the baseline of the line
+    is `lead_mm - ascent_mm - descent_mm` halved, plus `ascent_mm`, below the top
+    of the box. `text_layout` does that sum; this function only measures.
+    """
+    if not runs:
+        return (0.0, 0.0, 0.0)
+    tallest = max(runs, key=lambda run: run["size_pt"])
+    em = em_mm(tallest["size_pt"])
+    name = family(tallest.get("family"))
+    return (em * line_height, em * ASCENT[name], em * DESCENT[name])

plexora/plugins/figure_builder/static/figureActions.js

@@ -0,0 +1,363 @@
+/**
+ * What can be done to a selection, declared once.
+ *
+ * The bar that floats over the selection and the right-click menu are two
+ * surfaces onto ONE list. They were two hand-maintained lists, and they had
+ * already drifted: the menu marked "Bring to front" disabled when nothing in
+ * the selection could be reordered, while the bar offered it live on a text box
+ * where `reorderZ` filtered annotations out and did nothing at all. Two lists
+ * meant two answers to "can this be done", and only one of them was right.
+ *
+ * The rule the reference designs encode, and the one used here:
+ *
+ *   * an action that only means something for one kind appears only for that
+ *     kind -- "Split into channels" on a caption is not disabled, it is noise;
+ *   * an action that applies to ANY object is always REACHABLE, but a generic
+ *     one that cannot run right now is reachable through "More" rather than as
+ *     a dead icon on the bar.
+ *
+ * That second half used to read "always present, and greyed when it cannot
+ * run", and on a panel it was fine. On a text box it was not: Align, Distribute,
+ * Match size, Layout and Group all need two objects, so selecting one caption
+ * gave a bar of five grey icons and one live one, with everything actually
+ * worth pressing hidden behind the overflow. A greyed icon with no label is not
+ * an affordance; a greyed ROW that says "Align" is, because it names itself and
+ * the menu has room to. So the action stays in the vocabulary either way and
+ * only its surface moves -- which is still one declaration per action, with
+ * nothing branching on the type of the selection.
+ *
+ * `applies` decides whether an action exists for this selection at all, and
+ * `enabled` decides both whether it is clickable and, for a generic action,
+ * which of the two surfaces it lands on.
+ *
+ * Text FORMATTING is deliberately not here. Font, size, colour and the rest
+ * live in the text sidebar, because they are properties of one kind of object
+ * rather than actions on any object -- and putting them here is what would turn
+ * this back into a per-type list.
+ */
+class FigureSelection {
+
+    /**
+     * Everything the predicates below need, computed once per selection change.
+     *
+     * Pure: it reads the document and the canvas but changes nothing, so a
+     * probe can build one from a plain object.
+     */
+    static describe(ids, state, canvas) {
+        const annotations = ids
+            .map((id) => state.document.annotations[id]).filter(Boolean);
+        const panels = ids.map((id) => state.panel(id)).filter(Boolean);
+        const single = ids.length === 1
+            ? (panels[0] || annotations[0] || null) : null;
+        const kinds = new Set(panels.map(() => "panel")
+            .concat(annotations.map((annotation) => annotation.type)));
+
+        return {
+            ids: ids,
+            count: ids.length,
+            panels: panels,
+            annotations: annotations,
+            single: single,
+            kinds: kinds,
+            singlePanel: ids.length === 1 && panels.length === 1 ? panels[0] : null,
+            singleAnnotation:
+                ids.length === 1 && annotations.length === 1 ? annotations[0] : null,
+            isText: annotations.length === ids.length && ids.length > 0
+                    && annotations.every((a) => a.type === "text"),
+            // A box, as opposed to a line or an arrow, whose geometry is a
+            // vector and which therefore has no corners to rotate about.
+            allBoxes: ids.length > 0 && annotations.length === ids.length
+                      && annotations.every((a) => !["line", "arrow"].includes(a.type)),
+            grouped: ids.some((id) => canvas.groupFor(id)),
+            placed: panels.filter((panel) => panel.placement),
+            // How many of the selected objects have a RECTANGLE that Align,
+            // Distribute, Match size and Layout can act on, which is not the
+            // same as how many objects there are. `count > 1` was the test, and
+            // it was wrong twice over: it counted a panel still in the tray,
+            // which has no placement to move, and it counted a line, whose
+            // `w_mm`/`h_mm` are the two components of a vector rather than a
+            // size -- "same width" on one would flip its direction. Two
+            // captions now enable these; two arrows do not, and say so by being
+            // greyed in "More" rather than by doing nothing when pressed.
+            arrangeable: panels.filter((panel) => panel.placement).length
+                + annotations.filter(
+                    (a) => !["line", "arrow"].includes(a.type)).length,
+        };
+    }
+}
+
+
+class FigureActions {
+
+    /**
+     * The vocabulary. `surface` says where an action can appear:
+     *
+     *   bar       a button on the floating bar
+     *   overflow  a row in the bar's "More" menu
+     *   menu      a row in the right-click menu
+     *
+     * An action may name several. `popover: true` means the bar button opens a
+     * popover whose body `FigureContextBar.popoverMarkup` builds -- the detail
+     * of a scale bar or a legend is panel-specific and belongs there; what
+     * belongs HERE is only whether the button exists at all.
+     *
+     * `label` is the full sentence a menu row can afford. `short` is what the
+     * bar prints under the icon, and it is a separate field rather than a
+     * truncation because "Title, label and numbering" cut to fit says nothing
+     * and "Titles" says the whole thing. An action with no `short` prints its
+     * `label`, which is right for the ones that are already one word.
+     *
+     * `shortcut` is a FIELD and not two spaces and a glyph on the end of the
+     * label, which is how it was written first. A menu row sets the label and
+     * the key in two columns -- the labels ranged left, the keys ranged right
+     * and greyed -- and that is only possible if the row is given them
+     * separately. Concatenated, the keys landed wherever each label happened to
+     * end, which is a ragged column of the least important text on screen; and
+     * the bar's tooltip read "Group  ⌘G" with the double space in it.
+     */
+    static get ALL() {
+        const always = () => true;
+        return [
+            // -- type-specific, present only for what they mean something to --
+            { id: "edit_text", icon: "i-cursor", label: "Edit the text",
+              short: "Edit", surface: ["bar", "menu"],
+              applies: (sel) => Boolean(sel.singleAnnotation)
+                                && sel.singleAnnotation.type === "text",
+              enabled: always,
+              run: (ctx) => ctx.handlers.onEditText?.(ctx.ids[0]) },
+
+            // A character palette rather than a search box: the ones a figure
+            // caption actually needs are two dozen, and a grid of two dozen is
+            // faster to read than any field is to type into. It is on the BAR
+            // and not only in the sidebar because the caret it inserts at is on
+            // the canvas, and walking away to a panel to reach it is what loses
+            // the caret.
+            { id: "symbol", icon: "icons", label: "Insert a symbol",
+              short: "Symbol", surface: ["bar"], popover: true,
+              applies: (sel) => Boolean(sel.singleAnnotation)
+                                && sel.singleAnnotation.type === "text",
+              enabled: always },
+
+            { id: "quick_edit", icon: "sliders", label: "Quick Edit…",
+              short: "Quick Edit", surface: ["bar", "menu"],
+              applies: (sel) => Boolean(sel.singlePanel),
+              enabled: (sel, ctx) => FigureActions.reopenable(sel.singlePanel, ctx),
+              run: (ctx) => ctx.handlers.onQuickEdit?.(ctx.ids[0]) },
+
+            { id: "edit", icon: "arrow-up-right-from-square",
+              label: "Open in Main Viewer", short: "Viewer",
+              surface: ["bar", "menu"],
+              applies: (sel) => Boolean(sel.singlePanel),
+              enabled: (sel, ctx) => FigureActions.reopenable(sel.singlePanel, ctx),
+              run: (ctx) => ctx.handlers.onEditPanel?.(ctx.ids[0]) },
+
+            { id: "titles", icon: "font", label: "Title, label and numbering",
+              short: "Titles", surface: ["bar"], popover: true,
+              applies: (sel) => Boolean(sel.singlePanel), enabled: always },
+
+            { id: "split", icon: "table-columns", label: "Split into channels",
+              short: "Split", surface: ["bar"], popover: true,
+              applies: (sel) => Boolean(sel.singlePanel)
+                                && (sel.singlePanel.scene.channels || []).length > 1,
+              enabled: always },
+
+            { id: "scalebar", icon: "ruler-horizontal", label: "Scale bar",
+              surface: ["bar"], popover: true,
+              applies: (sel) => sel.panels.length > 0, enabled: always,
+              pressed: (sel) => sel.panels.some((panel) => panel.scalebar.visible) },
+
+            { id: "legend", icon: "list", label: "Legend",
+              surface: ["bar"], popover: true,
+              applies: (sel) => sel.panels.length > 0, enabled: always,
+              pressed: (sel) => sel.panels.some(
+                  (panel) => panel.legend.channels || panel.legend.plugins) },
+
+            { id: "stroke", icon: "pen", label: "Line and fill", short: "Line",
+              surface: ["bar"], popover: true,
+              applies: (sel) => Boolean(sel.singleAnnotation)
+                                && sel.singleAnnotation.type !== "text",
+              enabled: always },
+
+            { id: "colour", icon: "palette", label: "Color",
+              surface: ["bar"], popover: true,
+              // Not for text: a caption's colour belongs with its font and its
+              // size, in the sidebar, and offering it in two places is how the
+              // two end up disagreeing about what "the colour" means when only
+              // half the sentence is red.
+              applies: (sel) => Boolean(sel.singleAnnotation)
+                                && sel.singleAnnotation.type !== "text",
+              enabled: always },
+
+            // -- generic: on the bar when they can run, in "More" when not ----
+            { id: "align", icon: "align-center", label: "Align",
+              surface: ["bar"], popover: true, generic: true,
+              applies: always, enabled: (sel) => sel.arrangeable > 1 },
+
+            { id: "distribute", icon: "arrows-left-right", label: "Distribute",
+              surface: ["bar"], popover: true, generic: true,
+              applies: always, enabled: (sel) => sel.arrangeable > 2 },
+
+            // `expand`, not `vector-square`. The second is a Font Awesome 5/6
+            // name that FA 7 no longer ships, and an icon name the set does not
+            // have renders as nothing at all -- so this was a button captioned
+            // "Match" with a blank square above it. tests/test_tool_assets.py
+            // now checks every name in this tree against the set.
+            { id: "resize", icon: "expand", label: "Match size",
+              short: "Match", surface: ["bar"], popover: true, generic: true,
+              applies: always, enabled: (sel) => sel.arrangeable > 1 },
+
+            // "Layout", not "Arrange". Arrange is z-order in every design tool
+            // and in the reference this bar follows; the row/column/grid one
+            // needed the other name. `data-arrange` stays as it is -- it is the
+            // contract FigureCanvas answers to, and this is a label change.
+            { id: "layout", icon: "table-cells", label: "Layout",
+              surface: ["bar"], popover: true, generic: true,
+              applies: always, enabled: (sel) => sel.arrangeable > 1 },
+
+            // Z-order as one popover rather than four overflow rows. "Arrange"
+            // means z-order in every design tool, which is why the row/column
+            // /grid action above had to take the name "Layout" -- and it is the
+            // one generic action that is live on a selection of ONE, which is
+            // what makes it worth a button rather than a menu row.
+            { id: "arrange", icon: "layer-group", label: "Arrange",
+              surface: ["bar"], popover: true, generic: true,
+              applies: always,
+              enabled: (sel) => sel.placed.length > 0 || sel.annotations.length > 0 },
+
+            // Position and size as numbers, for the times the pointer cannot
+            // get there: a 0.5 mm nudge at 40% zoom, or two captions that have
+            // to be exactly the same width as each other.
+            { id: "transform", icon: "up-down-left-right", label: "Transform",
+              surface: ["bar"], popover: true, generic: true,
+              applies: always,
+              // One object, and one that HAS a width and a height. A field
+              // showing a single number for a selection of three is either
+              // lying or blank, and a line's `w_mm`/`h_mm` are the two
+              // components of a vector rather than a size -- a box to type a
+              // width into would be a box that means something else.
+              enabled: (sel) => sel.count === 1
+                                && (Boolean(sel.singlePanel) || sel.allBoxes) },
+
+            { id: "group", icon: "object-group", label: "Group", shortcut: "⌘G",
+              short: "Group", surface: ["bar", "menu"], generic: true,
+              applies: (sel) => !sel.grouped, enabled: (sel) => sel.count > 1,
+              run: (ctx) => ctx.canvas.groupSelection() },
+
+            { id: "ungroup", icon: "object-ungroup", label: "Ungroup", shortcut: "⇧⌘G",
+              short: "Ungroup", surface: ["bar", "menu"], generic: true,
+              applies: (sel) => sel.grouped, enabled: always,
+              run: (ctx) => ctx.canvas.ungroupSelection() },
+
+            // Duplicate and Delete earn a button for the same reason Arrange
+            // does: they are the two things anyone does to a single object of
+            // any kind, and they were the reason the overflow had to be opened
+            // at all on a text selection.
+            { id: "duplicate", icon: "clone", label: "Duplicate", shortcut: "⌘D",
+              short: "Duplicate", surface: ["bar", "menu"],
+              generic: true, applies: always, enabled: (sel) => sel.count > 0,
+              run: (ctx) => ctx.canvas.duplicateSelection() },
+
+            // -- generic, in the overflow and the right-click menu ------------
+            { id: "copy", icon: "copy", label: "Copy", shortcut: "⌘C",
+              surface: ["overflow", "menu"],
+              generic: true, applies: always, enabled: (sel) => sel.count > 0,
+              run: (ctx) => ctx.canvas.copySelection() },
+
+            // The four z-order commands, reached on the bar through the Arrange
+            // popover -- which is why none of them is on it directly. One
+            // command in two places on the same toolbar is how the bar and the
+            // right-click menu ended up disagreeing before.
+            //
+            // Four rather than two: "to the front" and "one place forward" are
+            // different intents, and getting a panel BETWEEN two others is only
+            // possible with the relative pair.
+            { id: "front", icon: "angles-up", label: "Bring to front", shortcut: "⌘⇧]",
+              surface: ["menu"], generic: true, applies: always,
+              // Enabled for annotations too, now that `reorderZ` reorders them.
+              // This was the drift: the menu said no and the bar said yes, and
+              // the bar was wrong.
+              enabled: (sel) => sel.placed.length > 0 || sel.annotations.length > 0,
+              run: (ctx) => ctx.canvas.reorderZ("front") },
+
+            { id: "forward", icon: "angle-up", label: "Bring forward", shortcut: "⌘]",
+              surface: ["menu"], generic: true, applies: always,
+              enabled: (sel) => sel.placed.length > 0 || sel.annotations.length > 0,
+              run: (ctx) => ctx.canvas.reorderZ("forward") },
+
+            { id: "backward", icon: "angle-down", label: "Send backward", shortcut: "⌘[",
+              surface: ["menu"], generic: true, applies: always,
+              enabled: (sel) => sel.placed.length > 0 || sel.annotations.length > 0,
+              run: (ctx) => ctx.canvas.reorderZ("backward") },
+
+            { id: "back", icon: "angles-down", label: "Send to back", shortcut: "⌘⇧[",
+              surface: ["menu"], generic: true, applies: always,
+              enabled: (sel) => sel.placed.length > 0 || sel.annotations.length > 0,
+              run: (ctx) => ctx.canvas.reorderZ("back") },
+
+            // The tray, because that is where it goes: off the page and back
+            // into the figure's holding area, which is the whole difference
+            // between this row and Delete two rows down.
+            { id: "remove_page", icon: "inbox", label: "Remove from page",
+              surface: ["overflow", "menu"], generic: true,
+              applies: (sel) => sel.panels.length > 0, enabled: always,
+              run: (ctx) => ctx.handlers.onRemoveFromPage?.() },
+
+            { id: "delete", icon: "trash", label: "Delete from figure",
+              short: "Delete", shortcut: "⌫", danger: true,
+              surface: ["bar", "menu"],
+              generic: true, applies: always, enabled: (sel) => sel.count > 0,
+              run: (ctx) => ctx.handlers.onDeleteFromFigure?.(ctx.ids) },
+        ];
+    }
+
+    /** The four z-order commands, in the order they belong in a menu: nearest
+     *  the viewer at the top. Named here rather than in the bar, so the popover
+     *  and the right-click menu cannot end up listing different ones. */
+    static get ARRANGE() {
+        return ["front", "forward", "backward", "back"];
+    }
+
+    /** A panel can be reopened only if its source is a project that is still
+     *  there -- an imported PNG has no viewer to go back to. */
+    static reopenable(panel, ctx) {
+        if (!panel) return false;
+        const source = ctx.state.source(panel.source_id);
+        return Boolean(source && source.kind === "plexora_project" && source.datasource);
+    }
+
+    /**
+     * The actions one surface should show for this selection, in order.
+     *
+     * The bar and the overflow are one list split in two by whether a generic
+     * action can currently run, so an action never falls out of reach: what the
+     * bar drops, "More" picks up, named and greyed. Type-specific actions are
+     * not moved -- they are on the bar because they are the point of having
+     * selected that kind of object, and `applies` has already decided they
+     * belong. The right-click menu takes everything its entries declare,
+     * enabled or not, because there every row carries its own label.
+     */
+    static forSurface(surface, sel, ctx) {
+        const available = FigureActions.ALL
+            .filter((action) => action.applies(sel, ctx))
+            .map((action) => ({
+                ...action,
+                isEnabled: Boolean(action.enabled(sel, ctx)),
+                isPressed: Boolean(action.pressed && action.pressed(sel, ctx)),
+            }));
+
+        if (surface === "bar") {
+            return available.filter((action) => action.surface.includes("bar")
+                && (action.isEnabled || !action.generic));
+        }
+        if (surface === "overflow") {
+            return available.filter((action) => action.surface.includes("overflow")
+                || (action.surface.includes("bar") && action.generic
+                    && !action.isEnabled));
+        }
+        return available.filter((action) => action.surface.includes(surface));
+    }
+
+    static byId(id) {
+        return FigureActions.ALL.find((action) => action.id === id) || null;
+    }
+}