@brftech/filex-core 0.42.1 → 0.43.0

package/src/lib/pluginMenu.ts

@@ -0,0 +1,253 @@
+/**
+ * pluginMenu — the file menu's plugin rows, as pure data.
+ *
+ * `FileExplorer.selectionActionList` splices these between the tags row and
+ * the desktop-sync rows. Kept out of the component so the gating can be
+ * tested without mounting the explorer: a row is offered only when the
+ * feature is on, the selection is a plain listing selection (not the trash,
+ * not inside an encrypted folder, not a storage mount row) and the action's
+ * `applies` rule accepts it.
+ *
+ * ⚠ v2: the rule reads the row's `app_state` too, so one app contributes
+ * DIFFERENT rows to the same menu depending on the file — "Sign / Fill"
+ * where a signature is pending, "Request signatures" where none is. They
+ * are ordinary rows beside the built-in verbs; nothing about them is a
+ * separate menu or a separate surface.
+ */
+import type { PluginActionRow, PluginGatedRule } from '../types/Plugins';
+import { appliesToNodes, type AppliesNodeLike } from './pluginApplies';
+import { labelOf } from './pluginLabel';
+
+/** The `ContextAction` fields a plugin row fills (the menu's own type owns the rest). */
+export interface PluginMenuRow {
+  key: string;
+  label: string;
+  icon?: string;
+  danger?: boolean;
+  divider?: boolean;
+  /** Greyed: offered once something the server lacks is there (`title` says what). */
+  disabled?: boolean;
+  title?: string;
+}
+
+export interface PluginMenuContext {
+  locale: string;
+  /** The trash view is open — plugins never run on trashed rows. */
+  trash?: boolean;
+  /** Inside an E2E-encrypted folder — the server would only see ciphertext. */
+  e2e?: boolean;
+  /**
+   * The selection sits on a read-only storage. An action whose result is
+   * WRITTEN there (`output_mode` `sibling` / `version`) is then not offered —
+   * see `pluginActionWrites`.
+   */
+  readOnly?: boolean;
+  /**
+   * The caller's level on one selected row (`none` | `viewer` | `editor` |
+   * `owner`), as the explorer's own write gate reads it (`rowPerm`). An
+   * action the level cannot run is not offered — see `pluginActionNeed`.
+   * Omitted, or any other answer (`''`, undefined: no ACL on that storage),
+   * leaves the row ungated; the server enforces either way.
+   */
+  permOf?: (node: PluginMenuNode) => string | undefined;
+  /** Which manifest icon names have a glyph; others fall back to `plugin`. */
+  hasIcon?: (name: string) => boolean;
+  /**
+   * The sentence for a greyed row (an action's `gated` rule): what the server
+   * lacks, in the reader's language. Absent, gated rows are not drawn.
+   */
+  needWords?: (need: PluginGatedRule['needs']) => string;
+}
+
+/** What the menu reads of a selected row. */
+export type PluginMenuNode = AppliesNodeLike & {
+  e2e?: boolean;
+  mime_type?: string | null;
+  /** The app holding the file read-only, if one does (listing `lock`). */
+  lock?: { plugin?: string } | null;
+};
+
+/**
+ * The Convert app's manifest name (BRF-Tech/filex-convert). Its actions
+ * replace the legacy iframe converter — see serviceGate `legacyConvertGate`.
+ */
+export const CONVERT_APP = 'convert';
+
+/** Whether the Convert app has any action on this instance for this caller. */
+export function convertAppOffered(actions: readonly Pick<PluginActionRow, 'plugin'>[]): boolean {
+  return actions.some((a) => a.plugin === CONVERT_APP);
+}
+
+/** The menu key for an action row: the server's, or `plugin:<plugin>/<id>`. */
+export function pluginActionKey(a: Pick<PluginActionRow, 'plugin' | 'id' | 'key'>): string {
+  return a.key || `plugin:${a.plugin}/${a.id}`;
+}
+
+/** Whether a menu key names a plugin action. */
+export function isPluginActionKey(key: string): boolean {
+  return key.startsWith('plugin:');
+}
+
+/**
+ * Whether running the action writes next to or over its file: its manifest
+ * output is `sibling` (a new file beside it) or `version` (a new version of
+ * it). The server's own test is the same one (handlers/app_plugins.go
+ * `authorise` → `jobOutputMode`), and it refuses those on a read-only storage
+ * with `409 read_only`.
+ *
+ * ⚠⚠ Why the menu asks at all (QA, 2026-09-21): on a read-only drive
+ * "Dönüştür…", "İmzala…" and "İmza iste…" were all offered, and the first
+ * one answered the click with a 409 and a toast that was gone in 2.5 s — for
+ * the person it did nothing. An action that can only be refused is not
+ * offered, the same rule the built-in verbs follow (Rename / Delete / Move
+ * are not in the menu of a read-only row either).
+ *
+ * ⚠ `none` answers false, and that is the limit of what the menu can know:
+ * an action with no file output may still write through the app's own
+ * permissions ("İmza iste…" starts a flow whose LAST step writes the signed
+ * copy). The app has to refuse that itself, in words, and the host's refusal
+ * path (useFileApi `refusalMessage`) says a `read_only` answer in words
+ * whichever surface it comes back through.
+ */
+export function pluginActionWrites(a: Pick<PluginActionRow, 'output_mode'> & { applies?: Pick<PluginActionRow['applies'], 'writable'> }): boolean {
+  return a.output_mode === 'sibling' || a.output_mode === 'version' || a.applies?.writable === true;
+}
+
+/**
+ * Not offered on a read-only storage: an action that writes there — unless
+ * its result may go into a folder the person chooses (`output_elsewhere`),
+ * whose screen then asks where.
+ */
+function refusedReadOnly(a: PluginActionRow): boolean {
+  return pluginActionWrites(a) && a.output_elsewhere !== true;
+}
+
+const LEVEL_RANK: Record<string, number> = { none: 0, viewer: 1, editor: 2, owner: 3 };
+
+/**
+ * The level a caller needs on every input to run the action — the server's
+ * `pluginACLNeed` (handlers/app_plugins.go), mirrored: `viewer` to read,
+ * `editor` once the job writes its result back, and whatever higher floor the
+ * manifest's `min_role` declares.
+ *
+ * ⚠⚠ Why the menu asks (v0.43.0 wave 2, 2026-09-22): the menu never read
+ * `min_role` at all. A person granted `viewer` on an RBAC storage was offered
+ * "Dönüştür…", "İmzala…" and "İmza iste…" on every file there, and each one
+ * answered the click with `403 insufficient permission` — the same "offered,
+ * then refused" the read-only rule above already removed. The built-in verbs
+ * follow the level (Rename / Delete are not in a viewer's menu); the app's
+ * rows now do too.
+ */
+export function pluginActionNeed(a: Pick<PluginActionRow, 'output_mode' | 'min_role'>): 'viewer' | 'editor' | 'owner' {
+  if (a.min_role === 'owner') return 'owner';
+  if (a.min_role === 'editor' || pluginActionWrites(a)) return 'editor';
+  return 'viewer';
+}
+
+/**
+ * Whether the caller's level on `node` lets them run `a`.
+ *
+ * ⚠ A row the SAME app has locked is not judged by its listed level: the
+ * listing caps a locked file at `viewer` for everyone (app_plugins_badges.go),
+ * which is the lock speaking, not the person's grant — and the app holding it
+ * is exactly the one that must still reach it ("Sign / Fill" on a document
+ * frozen while signatures are collected). The server decides that row.
+ */
+function levelAllows(a: PluginActionRow, node: PluginMenuNode, permOf: (n: PluginMenuNode) => string | undefined): boolean {
+  if (node.lock?.plugin && node.lock.plugin === a.plugin) return true;
+  const level = permOf(node);
+  if (level === undefined || !(level in LEVEL_RANK)) return true;
+  return LEVEL_RANK[level] >= LEVEL_RANK[pluginActionNeed(a)];
+}
+
+/** The action rows whose rule accepts this selection. */
+export function pluginActionsFor(
+  actions: readonly PluginActionRow[],
+  selection: readonly AppliesNodeLike[],
+): PluginActionRow[] {
+  if (selection.length === 0) return [];
+  // ⚠ `a.plugin` is not decoration: `applies.state` names the plugin's OWN
+  // keys while the rows carry them namespaced, so the matcher has to know
+  // whose keys to look for (lib/pluginApplies → stateKeysOf).
+  return actions.filter((a) => appliesToNodes(a.applies, selection as AppliesNodeLike[], a.plugin));
+}
+
+/**
+ * Menu rows for a selection, or `[]`.
+ *
+ * ONE GROUP PER APP, each behind its own divider. The first divider keeps its
+ * old key, `sep-plugins`, so the block still reads as its own group under
+ * Tags; every further app opens with `sep-plugin:<plugin>`.
+ *
+ * ⚠⚠ Why per app and not one block. The owner, 2026-09-21, looking at a PDF's
+ * right-click menu with the converter and the signing app both installed:
+ * "dönüştür ve imzalama pluginlerinin menüleri — yani her plugin'in menüleri —
+ * arasına çizgi çekelim". Eight rows from two apps in one undivided run read
+ * as one app's vocabulary, and "Convert to DOCX" sitting directly above
+ * "Request signatures" invited the question of which app would do what. The
+ * divider is the menu's own mechanism (`ContextAction.divider`), so the right
+ * click, the selection bar's "⋯" and the ⋮ all draw the same lines, and
+ * `ContextMenu` still collapses a divider that ends up leading, trailing or
+ * doubled.
+ *
+ * ⚠ Grouped by `plugin`, in the order each app's FIRST row arrived — not
+ * alphabetically and not by re-sorting the rows. The server lists an app's
+ * actions in manifest order and the app author chose that order; a stable
+ * grouping keeps it inside each app and only pulls apart rows that were
+ * interleaved (which the server does not do today, but a grouping that
+ * depended on it would break silently the day it did).
+ */
+export function pluginMenuRows(
+  actions: readonly PluginActionRow[],
+  selection: readonly PluginMenuNode[],
+  ctx: PluginMenuContext,
+): PluginMenuRow[] {
+  if (ctx.trash || ctx.e2e) return [];
+  if (selection.some((n) => n.e2e === true || n.mime_type === 'inode/storage')) return [];
+  const permOf = ctx.permOf;
+  const allowed = (a: PluginActionRow) =>
+    !(ctx.readOnly && refusedReadOnly(a)) && (!permOf || selection.every((n) => levelAllows(a, n, permOf)));
+  const offered = pluginActionsFor(actions, selection).filter(allowed);
+  // ⚠ Greyed WITH the reason — the owner's rule for anything that depends on
+  // how the server is set up ("not configured → disabled with the reason for
+  // administrators, hidden for everybody else"). The server sends `gated`
+  // to administrators only; here a row the selection would take once the
+  // missing piece is installed is drawn disabled, saying what is missing
+  // ("LibreOffice is not installed on this server").
+  const greyed = new Map<PluginActionRow, string>();
+  if (ctx.needWords) {
+    for (const a of actions) {
+      if (offered.includes(a) || !a.gated?.length || !allowed(a)) continue;
+      const gate = a.gated.find((g) =>
+        appliesToNodes({ ...a.applies, ext: g.ext ?? [], mime: [] }, selection as AppliesNodeLike[], a.plugin),
+      );
+      if (gate) greyed.set(a, ctx.needWords(gate.needs));
+    }
+  }
+  const rows = actions.filter((a) => offered.includes(a) || greyed.has(a));
+  if (rows.length === 0) return [];
+  const hasIcon = ctx.hasIcon ?? (() => false);
+  const byApp = new Map<string, PluginActionRow[]>();
+  for (const a of rows) {
+    const list = byApp.get(a.plugin);
+    if (list) list.push(a);
+    else byApp.set(a.plugin, [a]);
+  }
+  const out: PluginMenuRow[] = [];
+  let first = true;
+  for (const [plugin, list] of byApp) {
+    out.push({ divider: true, key: first ? 'sep-plugins' : `sep-plugin:${plugin}`, label: '' });
+    first = false;
+    for (const a of list) {
+      const why = greyed.get(a);
+      out.push({
+        key: pluginActionKey(a),
+        label: labelOf(a.label, ctx.locale),
+        icon: a.icon && hasIcon(a.icon) ? a.icon : 'plugin',
+        danger: a.danger === true,
+        ...(why ? { disabled: true, title: why } : {}),
+      });
+    }
+  }
+  return out;
+}

package/src/lib/pluginPage.ts

@@ -0,0 +1,58 @@
+/**
+ * pluginPage — where an app plugin's `page` view lives, and how it is opened.
+ *
+ * A `modal` view is a dialog over the listing. A `page` view is the SAME
+ * conversation (same `GET …/views/{p}/{v}?path=`, same `POST …/event`) drawn
+ * as a whole page in a NEW TAB — for a wizard that needs the document beside
+ * it, where a dialog's inner scroll would cramp both. The action row says
+ * which (`view_placement`), so nothing about the plugin changes between the
+ * two; only the frame does.
+ *
+ * ⚠⚠ This lives in the package, not in the admin SPA, because the rule is the
+ * same everywhere the explorer runs — fm.example.com, the desktop shell, the
+ * work.example.com and fishapp embeds. What differs per host is only WHERE the
+ * page is served and HOW a new surface is opened, and those are the two
+ * things `ExplorerConfig` asks the host for (`pluginPageBase`,
+ * `openPluginPage`). A host that wires neither keeps the modal: a `page`
+ * action still works, it just opens in a dialog rather than a tab. That is a
+ * degraded frame, never a missing feature.
+ *
+ * ⚠ The address in the contract (`/apps/{plugin}/{view}?path=…`) is relative
+ * to the SPA's MOUNT BASE, not to the site root: the same bundle is served
+ * from `/admin/` and `/drive/` (backend routes.go → wireStatic), and
+ * only those prefixes fall back to index.html. A bare `/apps/…` is a 404 on
+ * the server, so the host passes the base it was served from.
+ */
+
+/** The path segment under a mount base that a plugin page lives at. */
+export const PLUGIN_PAGE_SEGMENT = 'apps';
+
+export interface PluginPageTarget {
+  plugin: string;
+  view: string;
+  /** Adapter-qualified path of the row the action was invoked on. */
+  path?: string;
+}
+
+/** `apps/sign/wizard?path=docs%3A%2F%2Fnda.pdf` — no leading slash. */
+export function pluginPagePath(target: PluginPageTarget): string {
+  const p = `${PLUGIN_PAGE_SEGMENT}/${encodeURIComponent(target.plugin)}/${encodeURIComponent(target.view)}`;
+  return target.path ? `${p}?path=${encodeURIComponent(target.path)}` : p;
+}
+
+/**
+ * The full address, given the base the SPA is mounted at (`/admin/`,
+ * `/drive/`, `https://fm.example.com/admin/` — with or without its trailing
+ * slash). An empty base yields a root-relative `/apps/…`, which is right for
+ * a host that serves the SPA at the root and wrong for one that does not —
+ * hence the config field rather than a guess.
+ */
+export function pluginPageUrl(base: string | undefined | null, target: PluginPageTarget): string {
+  const b = String(base ?? '').replace(/\/+$/, '');
+  return `${b}/${pluginPagePath(target)}`;
+}
+
+/** Does this action open its view as a full page rather than a dialog? */
+export function isPagePlacement(placement: string | undefined | null): boolean {
+  return placement === 'page';
+}

package/src/lib/plural.ts

@@ -0,0 +1,181 @@
+/**
+ * plural — which form of a counted message a language reads for a number.
+ *
+ * ⚠⚠ Why this exists. Both catalogues used to have ONE plural rule, English's:
+ * the explorer chose `<key>_one` when the count was exactly 1 and `<key>`
+ * otherwise, and the admin panel left vue-i18n on its default (two forms:
+ * 1 → first, else second; three forms: 0 / 1 / else). That is enough for
+ * English and Turkish and for nothing much else. The Arabic pack's translator
+ * could not write the language at all — Arabic has SIX cardinal categories
+ * (zero, one, two, few, many, other) — and Russian, Polish, Czech and
+ * Ukrainian need few/many beside one (found by the Arabic pack, v0.43.0).
+ *
+ * The categories are the Unicode CLDR's, and they come from the runtime's own
+ * `Intl.PluralRules`: every browser and Node ship the CLDR tables, so the
+ * product does not carry (and cannot get out of date with) a copy of them.
+ *
+ * The grammar a pack writes, which `docs/` and the pack validator describe:
+ *
+ *   explorer (packages/core/src/locales, flat keys)
+ *     `<key>_zero` `<key>_one` `<key>_two` `<key>_few` `<key>_many`, and the
+ *     plain `<key>` IS the `other` form (there is no `_other` key). A language
+ *     writes only the categories it has; see `useLocale → countedKey`.
+ *
+ *   admin (web/src/locales, vue-i18n `a | b | …`)
+ *     as many forms as the language has categories (those whole numbers
+ *     0 … 999 reach, plus `other` — see `pluralCategories`), in CLDR order —
+ *     Arabic `zero | one | two | few | many | other`, Russian `one | few |
+ *     many | other` — or the old 1 / 2 / 3-form shapes; see
+ *     `pluralChoiceIndex`.
+ */
+
+/** The CLDR cardinal categories in the order a message lists its forms. */
+export const CLDR_ORDER = ['zero', 'one', 'two', 'few', 'many', 'other'] as const;
+export type PluralCategory = (typeof CLDR_ORDER)[number];
+
+/** What a runtime with no usable `Intl.PluralRules` is treated as: English. */
+const ENGLISH_CATEGORIES: readonly string[] = ['one', 'other'];
+
+/**
+ * One `Intl.PluralRules` per language. `null` = the runtime has none at all.
+ *
+ * ⚠ Cached because `t()` asks once per counted string per repaint, and
+ * constructing a `PluralRules` is the expensive part (`select` is cheap). A
+ * session has two or three distinct tags.
+ */
+const rulesCache = new Map<string, Intl.PluralRules | null>();
+
+function rulesFor(lang: string | undefined | null): Intl.PluralRules | null {
+  const key = String(lang ?? '');
+  const hit = rulesCache.get(key);
+  if (hit !== undefined) return hit;
+  let rules: Intl.PluralRules | null = null;
+  if (typeof Intl !== 'undefined' && typeof Intl.PluralRules === 'function') {
+    try {
+      rules = new Intl.PluralRules(key || 'en');
+    } catch {
+      // ⚠ A tag `Intl` refuses (`RangeError: Incorrect locale information`)
+      // must not take the page down with it — a pack names its language
+      // itself, and the host only checks that it LOOKS like a tag. English
+      // rules are what the rest of the interface falls back to as well.
+      try {
+        rules = new Intl.PluralRules('en');
+      } catch {
+        rules = null;
+      }
+    }
+  }
+  rulesCache.set(key, rules);
+  return rules;
+}
+
+const categoriesCache = new Map<string, readonly string[]>();
+
+/** The whole numbers sampled to find a language's categories: 0 … 999. */
+const SAMPLE_MAX = 999;
+
+/**
+ * The categories `lang` HAS, in CLDR order: every category some whole number
+ * from 0 to 999 falls in, plus `other` always.
+ *
+ * ⚠⚠ NOT `resolvedOptions().pluralCategories`. Current ICU lists `many` for
+ * Spanish, French, Italian, Portuguese and Catalan — a category only exact
+ * millions and compact numbers reach (`select(1000000)` is 'many') — so
+ * Spanish would have three categories, and a Spanish admin string written in
+ * the classic three forms `zero | one | other` would be read in CLDR order
+ * (`one | many | other`): 1 would pick the "zero" form. Counting what whole
+ * numbers people actually see select gives es/fr/it/pt `one | other`, Russian
+ * `one | few | many | other`, Arabic all six, Japanese `other`, Latvian
+ * `zero | one | other`, Romanian `one | few | other`.
+ *
+ * ⚠ The SAME definition as the pack validator (scripts/i18n-validate.mjs) and
+ * the server (Go, golang.org/x/text CLDR tables, sampled 0 … 999 + other). A
+ * third definition here would pass a pack there that renders wrong here.
+ *
+ * ⚠ In CLDR order, whatever order the runtime answers in: the admin panel
+ * maps a message's forms to categories BY POSITION — an unsorted list would
+ * hand Arabic's "few" form to the number 0.
+ *
+ * Cached: a thousand `select` calls, once per language per page.
+ */
+export function pluralCategories(lang: string | undefined | null): readonly string[] {
+  const key = String(lang ?? '');
+  const hit = categoriesCache.get(key);
+  if (hit) return hit;
+  let out: readonly string[] = ENGLISH_CATEGORIES;
+  const rules = rulesFor(key);
+  if (rules) {
+    try {
+      const seen = new Set<string>(['other']);
+      for (let n = 0; n <= SAMPLE_MAX; n++) seen.add(rules.select(n));
+      out = CLDR_ORDER.filter((c) => seen.has(c));
+    } catch {
+      out = ENGLISH_CATEGORIES;
+    }
+  }
+  categoriesCache.set(key, out);
+  return out;
+}
+
+/**
+ * The category `lang` puts the number `n` in — `'one'`, `'few'`, `'other'`…
+ *
+ * ⚠ The absolute value: "−1 day" agrees like "1 day", and `select` has no
+ * opinion about a sign. A count that is not a finite number (a formatted
+ * "1,234" that `Number()` could not read) is `other`, the plain form, which
+ * is what the single `_one` rule this replaced did with it too.
+ */
+export function pluralCategory(lang: string | undefined | null, n: number): string {
+  if (!Number.isFinite(n)) return 'other';
+  const abs = Math.abs(n);
+  const rules = rulesFor(lang);
+  if (!rules) return abs === 1 ? 'one' : 'other';
+  try {
+    return rules.select(abs);
+  } catch {
+    return abs === 1 ? 'one' : 'other';
+  }
+}
+
+/**
+ * Which of a vue-i18n message's `|`-separated forms `lang` reads for `choice`
+ * — a vue-i18n `pluralRules` entry, `(choice, choicesLength) => index`.
+ *
+ *   - as many forms as the language has categories (more than one, and
+ *     "has" as `pluralCategories` counts them): those categories, in CLDR
+ *     order — Arabic `zero | one | two | few | many | other`, Russian
+ *     `one | few | many | other`, Romanian `one | few | other`;
+ *   - one form: that form (a language that does not inflect);
+ *   - two: `one | other`;
+ *   - three: the classic `zero | one | other`;
+ *   - anything else: the last form, which is the `other` one.
+ *
+ * ⚠ The first rule outranks the next three, so a language with exactly three
+ * categories (Latvian, Romanian) writes three forms in CLDR order, not as
+ * `zero | one | other`. Spanish, French, Italian and Portuguese are NOT among
+ * them — see `pluralCategories` on the `many` ICU lists for round millions —
+ * so their three-form strings stay classic.
+ *
+ * ⚠ English and Turkish are not routed here — they keep vue-i18n's own rule,
+ * which the shipped catalogues were written against (web/src/i18n).
+ */
+export function pluralChoiceIndex(
+  lang: string | undefined | null,
+  choice: number,
+  choicesLength: number,
+): number {
+  const n = Math.abs(choice);
+  const cats = pluralCategories(lang);
+  const c = pluralCategory(lang, n);
+  if (choicesLength === cats.length && choicesLength > 1) {
+    // ⚠ A category outside the sampled list is real: Spanish `select(1000000)`
+    // is 'many', and Spanish's list is `one | other`. It reads the last form
+    // (`other`) — -1 would make vue-i18n print nothing at all.
+    const i = cats.indexOf(c);
+    return i >= 0 ? i : choicesLength - 1;
+  }
+  if (choicesLength === 1) return 0;
+  if (choicesLength === 2) return c === 'one' ? 0 : 1;
+  if (choicesLength === 3) return n === 0 ? 0 : c === 'one' ? 1 : 2;
+  return choicesLength - 1;
+}

package/src/lib/popupLayer.ts

@@ -0,0 +1,103 @@
+/**
+ * Which layer a teleported popup has to sit on to be above whatever opened it.
+ *
+ * ⚠⚠ THE BUG THIS EXISTS FOR. A menu that teleports to `<body>` leaves its
+ * container's stacking context behind — that is the point, it is how a menu
+ * escapes `overflow: hidden` and a transformed ancestor. But it also leaves
+ * behind that container's PLACE in the stack. The explorer's Connections /
+ * API-keys overlay is `.fe-overlay`, `position: fixed; z-index: 130`; the
+ * context menu's backdrop is `z-index: 80`. So a row's "Actions" menu opened
+ * inside that overlay was painted UNDER it — the owner, testing v0.43.0:
+ * "explore kısmında api anahtarlarında ya da nasıl bağlanılar (yani popup
+ * ekranlar) içindeki aksiyon tuşlarının menüsü popup'ın altında kalıyor ve
+ * açılmıyor gibi gözüküyor". It opened every time; nobody could see it.
+ *
+ * ⚠ Why not simply raise `.fe-ctx-backdrop` to a big constant. Because the
+ * stack has deliberate orderings in it that a constant would flatten — the
+ * onboarding tour sits at 96 ABOVE the filter popovers at 90 on purpose, so a
+ * tour step is never hidden behind one. And in an EMBED the number we would
+ * have to beat is not ours at all: the host page decides what its own
+ * containers are worth, and no constant we pick is guaranteed to clear it.
+ *
+ * So the layer is MEASURED from the thing that opened the popup: walk the
+ * opener's ancestors, take the highest z-index any positioned one carries, and
+ * sit one above it — or stay on the base layer when nothing in the chain is
+ * raised at all, which is the ordinary case and leaves every existing ordering
+ * exactly as it was.
+ */
+
+/** The layer transient popups live on when nothing pushes them higher. */
+export const POPUP_BASE_Z = 80;
+
+/**
+ * The z-index for a popup opened from `openers`.
+ *
+ * Several openers may be passed because the caller usually has more than one
+ * imperfect clue about what was clicked (the focused element, the element under
+ * the pointer); the highest answer wins, and a null is simply ignored.
+ */
+export function popupLayer(
+  openers: Array<Element | null | undefined> | Element | null | undefined,
+  base: number = POPUP_BASE_Z,
+): number {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return base;
+  const list = Array.isArray(openers) ? openers : [openers];
+  let top = base;
+  for (const opener of list) {
+    let el: Element | null = opener ?? null;
+    /* A cycle is impossible through parentElement, but a shadow host hop is a
+     * jump the loop cannot prove terminates; 200 is far past any real tree. */
+    for (let guard = 0; el && guard < 200; guard++) {
+      if (el === document.body || el === document.documentElement) break;
+      let z = Number.NaN;
+      let positioned = false;
+      try {
+        const cs = window.getComputedStyle(el);
+        /* ⚠ `|| 'static'`: a DOM that has not resolved the cascade answers
+         * with the empty string rather than the initial value (happy-dom does,
+         * and so does a detached node in some engines). Reading that as "not
+         * static" would honour every inert `z-index` in the tree — the pinned
+         * Actions cell carries one — and shove the menu onto a layer nothing
+         * asked for. */
+        positioned = (cs.position || 'static') !== 'static';
+        z = Number.parseInt(cs.zIndex, 10);
+      } catch {
+        /* A detached or cross-document node: nothing to learn, keep climbing. */
+      }
+      /* ⚠ `position !== static` as well as a number: `z-index` on a static
+       * element is inert — honouring it would push the menu above a dialog
+       * because some unrelated cell in the row carried a leftover number. */
+      if (positioned && Number.isFinite(z) && z + 1 > top) top = z + 1;
+      el =
+        el.parentElement ??
+        /* Out the top of a shadow tree, if the host put us in one. */
+        ((el.getRootNode() as ShadowRoot | null)?.host ?? null);
+    }
+  }
+  return top;
+}
+
+/**
+ * The best guesses at what opened a popup, at the moment it opens.
+ *
+ * `document.activeElement` is the control a click just focused, and the element
+ * under the pointer is what a right-click or a synthetic open landed on. Either
+ * can be wrong on its own — a button that does not take focus, a coordinate on
+ * a border — and both are in the same subtree as the real opener whenever they
+ * are right, which is all `popupLayer` needs.
+ *
+ * ⚠ Call this BEFORE the popup renders. Once the backdrop is in the document it
+ * covers the viewport, and `elementFromPoint` answers with the backdrop.
+ */
+export function openerCandidates(x?: number, y?: number): Array<Element | null> {
+  if (typeof document === 'undefined') return [];
+  const out: Array<Element | null> = [document.activeElement];
+  if (typeof x === 'number' && typeof y === 'number' && document.elementFromPoint) {
+    try {
+      out.push(document.elementFromPoint(x, y));
+    } catch {
+      /* Out-of-viewport coordinates throw in some engines; the focus clue stands. */
+    }
+  }
+  return out;
+}