entangled-worlds-orbiters-shared 4.2.0 → 5.0.0

package/README.md

@@ -99,12 +99,13 @@ The capability registry (`createCapabilityRegistry`, `validate` / `assertValid`,
 - `largestFunction`, `shrinkWasm` - The size check and the shrink step
 
 ### Keyboard shortcuts (`entangled-worlds-orbiters-shared/shortcuts`)
-- `ShortcutAction` - One catalogue entry: `id`, `section`, `label`, `defaultKeys` (by key place, `event.code`), `scope`
+- `ShortcutAction` - One catalogue entry: `id`, `label` (+ `names` by language), `defaultKeys` (by key place, `event.code`), `scope`
 - `matchShortcut(event, bindings)` - Which action a press is, or `null`: modifiers, a field being typed in and surface claims decided in one place
 - Key strings: `Shift+KeyR`, `Mod+KeyZ` (Ctrl or ⌘), `Shift?+KeyQ` (Shift may be held); `parseChord`, `chordsOverlap`
 - `resolveBindings(catalogue, overrides)`, `findClashes` - Defaults plus a person's overrides (`[{ id, keys }]` as their settings store them, `keys: []` unbinds), and the clash check
 - `claimKeys`, `isKeyClaimed` - A surface (an on-screen keyboard) takes letters away from the shortcuts while it is up
-- `ORBITERS_PLAY_SHORTCUTS`, `ORBITERS_STUDIO_SHORTCUTS` - The Orbiters catalogues
+- `createShortcutSource({ readCatalogue, readAccount })` - The catalogue (every app's actions and default keys, served by the backend: this package holds none) and a person's own keys, read at start and again when the page comes back to the front; `actions(...sectionIds)`, `bindings(actions)`, `subscribe`
+- `parseCatalogue`, `sectionActions`, `findSection`, `shortcutApps`, `localName` - Reading a served catalogue and its names in a language
 
 ### Uploads (`entangled-worlds-orbiters-shared/uploads`)
 - `uploadViaSignedUrl` - The API's signed-URL upload: `/spaces/upload-init` → PUT → `/spaces/upload-complete`, over the app's own authenticated JSON caller

package/dist/shortcuts/catalogue.d.ts

@@ -0,0 +1,72 @@
+import type { ShortcutAction, ShortcutNames } from './match.js';
+/** Something with a name: English `label`, other languages in `names`. */
+export interface ShortcutNamed {
+    readonly id: string;
+    readonly label: string;
+    readonly names?: ShortcutNames;
+}
+/** A row of a keys sheet (`?`): one line for one or more actions whose keys show together. */
+export interface ShortcutSheetRow extends ShortcutNamed {
+    readonly actions: readonly string[];
+}
+export interface ShortcutSheetColumn extends ShortcutNamed {
+    readonly rows: readonly ShortcutSheetRow[];
+}
+/** One surface's keys (`orbiters-play`, `ew-studio`, `site`). Two actions clash only inside a section. */
+export interface ShortcutSection {
+    readonly id: string;
+    /** The app it belongs to (`orbiters`) and that app's name. */
+    readonly app: string;
+    readonly appLabel: string;
+    readonly appNames?: ShortcutNames;
+    readonly label: string;
+    readonly names?: ShortcutNames;
+    /** Its name inside the app (`Play`, `Studio`); none when the app has only this section. */
+    readonly part?: string;
+    readonly partNames?: ShortcutNames;
+    /** How a command menu groups the actions, in its order. */
+    readonly groups: readonly ShortcutNamed[];
+    /** The keys sheet, where the app shows one in columns. */
+    readonly sheet?: readonly ShortcutSheetColumn[];
+    readonly actions: readonly ShortcutAction[];
+    /**
+     * Letters a surface of this section plays while it is open (`event.key`, lower-case; the Orbiters
+     * on-screen keyboard): a shortcut on one of them waits until it closes.
+     */
+    readonly heldKeys?: readonly string[];
+}
+export interface ShortcutCatalogue {
+    /** Changes whenever the catalogue is edited. */
+    readonly version: string;
+    readonly sections: readonly ShortcutSection[];
+}
+/** Before the catalogue is read: no sections, so no key does anything yet. */
+export declare const EMPTY_CATALOGUE: ShortcutCatalogue;
+/**
+ * The catalogue a response holds (`{ version, sections }`), or `null` when it holds none. A malformed
+ * section or action is left out rather than failing the whole read.
+ */
+export declare function parseCatalogue(value: unknown): ShortcutCatalogue | null;
+/** A name in a language (`es`, `es-AR`), the English when there is none in it. */
+export declare function localName(item: {
+    readonly label: string;
+    readonly names?: ShortcutNames;
+}, locale?: string): string;
+/** A section's app name in a language. */
+export declare function localAppName(section: Pick<ShortcutSection, 'appLabel' | 'appNames'>, locale?: string): string;
+/** A section's part name (`Play`, `Studio`) in a language; `undefined` when it has none. */
+export declare function localPartName(section: Pick<ShortcutSection, 'part' | 'partNames'>, locale?: string): string | undefined;
+/** The apps the catalogue has, in its order. */
+export declare function shortcutApps(catalogue: ShortcutCatalogue): ReadonlyArray<{
+    id: string;
+    label: string;
+    names?: ShortcutNames;
+}>;
+/**
+ * The actions of these sections, in the order named: where two sections hold one key, the first
+ * named wins (the Orbiter Studio lies over play). The same list object for as long as the catalogue
+ * is the same, so a cache keyed by it holds.
+ */
+export declare function sectionActions(catalogue: ShortcutCatalogue, ...sectionIds: string[]): readonly ShortcutAction[];
+/** One section, if the catalogue has it. */
+export declare function findSection(catalogue: ShortcutCatalogue, sectionId: string): ShortcutSection | undefined;

package/dist/shortcuts/catalogue.js

@@ -0,0 +1,118 @@
+// The shortcut catalogue as the apps read it: every app's sections of actions, their default keys and
+// names, as the backend serves them (from its config, so a key or a name changes without a library
+// release). This file only reads what was served; it holds no actions of its own.
+/** Before the catalogue is read: no sections, so no key does anything yet. */
+export const EMPTY_CATALOGUE = Object.freeze({ version: '', sections: Object.freeze([]) });
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const isString = (value) => typeof value === 'string' && value.length > 0;
+function names(value) {
+    if (!isRecord(value))
+        return undefined;
+    const out = {};
+    for (const [locale, name] of Object.entries(value))
+        if (isString(name))
+            out[locale] = name;
+    return Object.freeze(out);
+}
+function named(value) {
+    if (!isRecord(value) || !isString(value.id) || !isString(value.label))
+        return null;
+    return { id: value.id, label: value.label, names: names(value.names) };
+}
+function action(value) {
+    const base = named(value);
+    if (!base || !isRecord(value) || !isString(value.scope) || !Array.isArray(value.defaultKeys))
+        return null;
+    return Object.freeze({
+        ...base,
+        defaultKeys: Object.freeze(value.defaultKeys.filter(isString)),
+        scope: value.scope,
+        ...(isString(value.group) ? { group: value.group } : {}),
+        ...(value.command === false ? { command: false } : {}),
+        ...(isString(value.href) ? { href: value.href } : {}),
+        ...(value.signedIn === true ? { signedIn: true } : {}),
+    });
+}
+const list = (value, read) => Object.freeze(Array.isArray(value) ? value.map(read).filter((item) => item !== null) : []);
+function section(value) {
+    const base = named(value);
+    if (!base || !isRecord(value) || !isString(value.app) || !isString(value.appLabel))
+        return null;
+    return Object.freeze({
+        ...base,
+        app: value.app,
+        appLabel: value.appLabel,
+        appNames: names(value.appNames),
+        ...(isString(value.part) ? { part: value.part, partNames: names(value.partNames) } : {}),
+        groups: list(value.groups, named),
+        ...(Array.isArray(value.sheet)
+            ? {
+                sheet: list(value.sheet, (column) => {
+                    const head = named(column);
+                    if (!head || !isRecord(column))
+                        return null;
+                    return Object.freeze({
+                        ...head,
+                        rows: list(column.rows, (row) => {
+                            const line = named(row);
+                            return line && isRecord(row) ? Object.freeze({ ...line, actions: list(row.actions, (id) => (isString(id) ? id : null)) }) : null;
+                        }),
+                    });
+                }),
+            }
+            : {}),
+        actions: list(value.actions, action),
+        ...(Array.isArray(value.heldKeys) ? { heldKeys: list(value.heldKeys, (key) => (isString(key) ? key : null)) } : {}),
+    });
+}
+/**
+ * The catalogue a response holds (`{ version, sections }`), or `null` when it holds none. A malformed
+ * section or action is left out rather than failing the whole read.
+ */
+export function parseCatalogue(value) {
+    if (!isRecord(value) || !Array.isArray(value.sections))
+        return null;
+    return Object.freeze({ version: typeof value.version === 'string' ? value.version : '', sections: list(value.sections, section) });
+}
+/** A name in a language (`es`, `es-AR`), the English when there is none in it. */
+export function localName(item, locale) {
+    return item.names?.[(locale ?? '').slice(0, 2).toLowerCase()] ?? item.label;
+}
+/** A section's app name in a language. */
+export function localAppName(section, locale) {
+    return localName({ label: section.appLabel, names: section.appNames }, locale);
+}
+/** A section's part name (`Play`, `Studio`) in a language; `undefined` when it has none. */
+export function localPartName(section, locale) {
+    return section.part === undefined ? undefined : localName({ label: section.part, names: section.partNames }, locale);
+}
+/** The apps the catalogue has, in its order. */
+export function shortcutApps(catalogue) {
+    const seen = new Map();
+    for (const s of catalogue.sections)
+        if (!seen.has(s.app))
+            seen.set(s.app, { id: s.app, label: s.appLabel, names: s.appNames });
+    return [...seen.values()];
+}
+const actionLists = new WeakMap();
+/**
+ * The actions of these sections, in the order named: where two sections hold one key, the first
+ * named wins (the Orbiter Studio lies over play). The same list object for as long as the catalogue
+ * is the same, so a cache keyed by it holds.
+ */
+export function sectionActions(catalogue, ...sectionIds) {
+    let lists = actionLists.get(catalogue);
+    if (!lists)
+        actionLists.set(catalogue, (lists = new Map()));
+    const key = sectionIds.join('\n');
+    let found = lists.get(key);
+    if (!found) {
+        found = Object.freeze(sectionIds.flatMap((id) => catalogue.sections.find((s) => s.id === id)?.actions ?? []));
+        lists.set(key, found);
+    }
+    return found;
+}
+/** One section, if the catalogue has it. */
+export function findSection(catalogue, sectionId) {
+    return catalogue.sections.find((s) => s.id === sectionId);
+}

package/dist/shortcuts/index.d.ts

@@ -1,9 +1,5 @@
 export { parseChord, parseKeys, keysOverlap, chordMatches, chordsOverlap, isCommandChord, type Chord, type ModifierRule, type ModifierState, } from './chord.js';
-export { matchShortcut, createShortcutMatcher, SEQUENCE_WAIT_MS, resolveBindings, findClashes, claimKeys, isKeyClaimed, isTypingTarget, type ShortcutAction, type ShortcutBindings, type ShortcutOverrides, type ShortcutEvent, } from './match.js';
-export { ORBITERS_PLAY_SHORTCUTS, ORBITERS_STUDIO_SHORTCUTS, ORBITERS_PLAY_SECTION, ORBITERS_STUDIO_SECTION, ORBITERS_KEYBOARD_SURFACE_KEYS, ORBITERS_COMMAND_GROUPS, ORBITERS_PLAY_SHEET, type OrbitersShortcut, type OrbitersShortcutScope, } from './orbiters.js';
+export { matchShortcut, createShortcutMatcher, SEQUENCE_WAIT_MS, resolveBindings, findClashes, claimKeys, isKeyClaimed, isTypingTarget, type ShortcutAction, type ShortcutNames, type ShortcutBindings, type ShortcutOverrides, type ShortcutEvent, } from './match.js';
 export { shortcutPlatform, keyLabel, chordParts, formatChord, chordFromEvent, mergedKeyParts, recordedKeys, type ShortcutPlatform, type KeyLayout, } from './format.js';
-export { SHORTCUT_SECTIONS, SHORTCUT_APPS, type ShortcutSection, type ShortcutAppId } from './sections.js';
-export { SITE_SHORTCUTS, SITE_SECTION, type SiteShortcut } from './site.js';
-export { EW_STUDIO_SHORTCUTS, EW_PLAYER_SHORTCUTS, EW_STUDIO_SECTION, EW_PLAYER_SECTION, EW_STUDIO_COMMAND_GROUPS, type EntangledWorldsShortcut, } from './entangledWorlds.js';
-export { shortcutLabel, shortcutSectionLabel, shortcutName } from './labels.js';
-export { createShortcutOverridesSource, parseOverrides, type ShortcutOverridesSource, type ReadAccountSettings, } from './overrides.js';
+export { EMPTY_CATALOGUE, parseCatalogue, localName, localAppName, localPartName, shortcutApps, sectionActions, findSection, type ShortcutCatalogue, type ShortcutSection, type ShortcutNamed, type ShortcutSheetColumn, type ShortcutSheetRow, } from './catalogue.js';
+export { createShortcutSource, localShortcutCatalogueStore, CATALOGUE_STORAGE_KEY, parseOverrides, type ShortcutCatalogueStore, type ShortcutSource, type ReadAccountSettings, type ReadShortcutCatalogue, } from './source.js';

package/dist/shortcuts/index.js

@@ -1,13 +1,9 @@
-// Keyboard shortcuts, one system for every app: each app's catalogue of actions (id, section, label,
-// default keys, scope) and one matcher that says which action a key press is. Keys are named by
-// their place on the keyboard (`KeyboardEvent.code`). Framework-free: no React, no DOM beyond reading
-// a key event.
+// Keyboard shortcuts, one system for every app: the reader of the shortcut catalogue (every app's
+// actions and default keys, served by the backend) and of a person's own keys, and one matcher that
+// says which action a key press is. Keys are named by their place on the keyboard
+// (`KeyboardEvent.code`). Framework-free: no React, no DOM beyond reading a key event.
 export { parseChord, parseKeys, keysOverlap, chordMatches, chordsOverlap, isCommandChord, } from './chord.js';
 export { matchShortcut, createShortcutMatcher, SEQUENCE_WAIT_MS, resolveBindings, findClashes, claimKeys, isKeyClaimed, isTypingTarget, } from './match.js';
-export { ORBITERS_PLAY_SHORTCUTS, ORBITERS_STUDIO_SHORTCUTS, ORBITERS_PLAY_SECTION, ORBITERS_STUDIO_SECTION, ORBITERS_KEYBOARD_SURFACE_KEYS, ORBITERS_COMMAND_GROUPS, ORBITERS_PLAY_SHEET, } from './orbiters.js';
 export { shortcutPlatform, keyLabel, chordParts, formatChord, chordFromEvent, mergedKeyParts, recordedKeys, } from './format.js';
-export { SHORTCUT_SECTIONS, SHORTCUT_APPS } from './sections.js';
-export { SITE_SHORTCUTS, SITE_SECTION } from './site.js';
-export { EW_STUDIO_SHORTCUTS, EW_PLAYER_SHORTCUTS, EW_STUDIO_SECTION, EW_PLAYER_SECTION, EW_STUDIO_COMMAND_GROUPS, } from './entangledWorlds.js';
-export { shortcutLabel, shortcutSectionLabel, shortcutName } from './labels.js';
-export { createShortcutOverridesSource, parseOverrides, } from './overrides.js';
+export { EMPTY_CATALOGUE, parseCatalogue, localName, localAppName, localPartName, shortcutApps, sectionActions, findSection, } from './catalogue.js';
+export { createShortcutSource, localShortcutCatalogueStore, CATALOGUE_STORAGE_KEY, parseOverrides, } from './source.js';

package/dist/shortcuts/match.d.ts

@@ -1,12 +1,12 @@
 import { type ModifierState } from './chord.js';
-/** One thing a key can do, as an app's catalogue declares it. */
+/** One thing a key can do, as the shortcut catalogue (served by the backend) lists it. */
 export interface ShortcutAction<Scope extends string = string> {
     /** `<app>.<area>.<action>`, e.g. `orbiters.play.panel.jamming`: the key a person's override is stored under. */
     readonly id: string;
-    /** The group it is shown in, one per app surface (`orbiters-play`). Keys clash only inside a section. */
-    readonly section: string;
-    /** What it does, in sentence case. */
+    /** What it does, in sentence case, in English. */
     readonly label: string;
+    /** Its name in other languages, by locale (`{ es: '…' }`); see `localName`. */
+    readonly names?: ShortcutNames;
     /** The keys it has until the person changes them (chord strings, see `chord.ts`). */
     readonly defaultKeys: readonly string[];
     /** What it acts on, in the app's own terms (Orbiters: one deck, or this machine). */
@@ -15,12 +15,18 @@ export interface ShortcutAction<Scope extends string = string> {
     readonly group?: string;
     /** `false`: a key only, never a command to pick from a list (a key held down, the menu itself). */
     readonly command?: boolean;
+    /** A site action: the page it opens (`{username}` stands for the signed-in person's). */
+    readonly href?: string;
+    /** It needs someone signed in. */
+    readonly signedIn?: boolean;
 }
+/** A name in other languages than English, by locale (`es`). */
+export type ShortcutNames = Readonly<Record<string, string>>;
 /** The keys of each action, in the order they are tried: the first action a press matches is the one. */
 export type ShortcutBindings = Iterable<readonly [actionId: string, keys: readonly string[]]>;
 /**
  * A person's changes, as their settings store them: an action's own keys (`[]` = no key). An action
- * left out keeps its defaults, so a default changed in code reaches everyone who never touched it.
+ * left out keeps its defaults, so a default changed in the catalogue reaches everyone who never touched it.
  */
 export type ShortcutOverrides = ReadonlyArray<{
     readonly id: string;

package/dist/shortcuts/source.d.ts

@@ -0,0 +1,62 @@
+import { type ShortcutCatalogue } from './catalogue.js';
+import { type ShortcutAction, type ShortcutOverrides } from './match.js';
+/** The overrides in a stored value, or `null` when it is not a list of `{ id, keys }`. */
+export declare function parseOverrides(value: unknown): ShortcutOverrides | null;
+/**
+ * How the app reads the signed-in person's settings: `null` when no one is signed in (the
+ * default keys); `undefined` when the read failed (the overrides in force are kept: a blip must not
+ * swap someone's keys for the defaults).
+ */
+export type ReadAccountSettings = (options: {
+    fresh: boolean;
+}) => Promise<{
+    shortcuts?: unknown;
+} | null | undefined>;
+/**
+ * How the app reads the catalogue (`{ version, sections }`); `undefined` or a throw when the read
+ * failed (the catalogue in force is kept). There is no copy in the app: until the first read
+ * answers, no key does anything.
+ */
+export type ReadShortcutCatalogue = (options: {
+    fresh: boolean;
+}) => Promise<unknown>;
+export interface ShortcutSource {
+    /** The catalogue in force (empty until it is read). */
+    catalogue(): ShortcutCatalogue;
+    /** The actions of these sections, the first named winning a shared key; the same list until the catalogue changes. */
+    actions(...sectionIds: string[]): readonly ShortcutAction[];
+    /** The person's overrides in force. */
+    overrides(): ShortcutOverrides;
+    /** A list of actions with their keys now (kept until the catalogue or the overrides change). */
+    bindings(actions: readonly ShortcutAction[]): Map<string, readonly string[]>;
+    /** Called whenever the catalogue or the overrides change; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Read both again (`fresh`: past the app's own cached read). The newest read of each wins, whatever order they end in. */
+    refresh(options?: {
+        fresh?: boolean;
+    }): Promise<void>;
+    /** Read now, and again whenever the page comes back to the front; once per source. */
+    bind(): void;
+    /** For tests: set the overrides directly. */
+    setOverrides(overrides: ShortcutOverrides): void;
+    /** For tests: set the catalogue directly. */
+    setCatalogue(catalogue: ShortcutCatalogue): void;
+}
+/**
+ * Where a device keeps the last catalogue it read: offline (the desktop app with no connection) the
+ * keys are the ones it last had, and on every start they answer before the read comes back. A copy of
+ * what was served, never a list of its own.
+ */
+export interface ShortcutCatalogueStore {
+    load(): unknown;
+    save(value: unknown): void;
+}
+export declare const CATALOGUE_STORAGE_KEY = "ps.shortcutCatalogue";
+/** This browser's localStorage, when there is one and it may be used; otherwise nothing is kept. */
+export declare function localShortcutCatalogueStore(): ShortcutCatalogueStore | null;
+export declare function createShortcutSource({ readCatalogue, readAccount, store, }: {
+    readCatalogue: ReadShortcutCatalogue;
+    readAccount: ReadAccountSettings;
+    /** Where the last catalogue read is kept (this browser's localStorage by default; `null`: nowhere). */
+    store?: ShortcutCatalogueStore | null;
+}): ShortcutSource;

package/dist/shortcuts/source.js

@@ -0,0 +1,139 @@
+// Where an app's keys come from, read the same way by every app: the catalogue (every action and its
+// default keys, from the backend) and the person's own changes (their account's settings; someone
+// signed out has the defaults). Both are read at start and again whenever the page comes back to the
+// front, so a key changed in the catalogue or on the settings page applies on return, without a reload.
+//
+// Framework-free: the app hands in how it reads each (its own API client) and gets the catalogue, the
+// overrides, and each list of actions' resolved keys back, kept until either changes.
+import { EMPTY_CATALOGUE, parseCatalogue, sectionActions } from './catalogue.js';
+import { resolveBindings } from './match.js';
+/** The overrides in a stored value, or `null` when it is not a list of `{ id, keys }`. */
+export function parseOverrides(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.filter((entry) => !!entry && typeof entry.id === 'string' && Array.isArray(entry.keys) && entry.keys.every((k) => typeof k === 'string'));
+}
+export const CATALOGUE_STORAGE_KEY = 'ps.shortcutCatalogue';
+/** This browser's localStorage, when there is one and it may be used; otherwise nothing is kept. */
+export function localShortcutCatalogueStore() {
+    const storage = globalThis.localStorage;
+    if (!storage)
+        return null;
+    return {
+        load() {
+            try {
+                const raw = storage.getItem(CATALOGUE_STORAGE_KEY);
+                return raw ? JSON.parse(raw) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        save(value) {
+            try {
+                storage.setItem(CATALOGUE_STORAGE_KEY, JSON.stringify(value));
+            }
+            catch {
+                // Full or refused (a private window): the next start reads the backend first, as without a store.
+            }
+        },
+    };
+}
+/** Coming back to the front twice in a row (visible, then focus) reads once. */
+const REFRESH_GAP_MS = 2000;
+/** Keeps the answer of the newest read that answered: an older one ending later says nothing new. */
+function newestRead(read, apply) {
+    let latest = 0;
+    let applied = 0;
+    return async (fresh) => {
+        const ticket = ++latest;
+        let value;
+        try {
+            value = await read(fresh);
+        }
+        catch {
+            value = undefined;
+        }
+        if (value === undefined || ticket < applied)
+            return;
+        applied = ticket;
+        apply(value);
+    };
+}
+export function createShortcutSource({ readCatalogue, readAccount, store = localShortcutCatalogueStore(), }) {
+    let catalogue = (store && parseCatalogue(store.load())) || EMPTY_CATALOGUE;
+    let overrides = [];
+    let resolved = new WeakMap();
+    let lastRefreshAt = -Infinity;
+    let bound = false;
+    const listeners = new Set();
+    const changed = () => {
+        resolved = new WeakMap();
+        listeners.forEach((listener) => listener());
+    };
+    const applyOverrides = (next) => {
+        if (JSON.stringify(next) === JSON.stringify(overrides))
+            return;
+        overrides = next;
+        changed();
+    };
+    const applyCatalogue = (next) => {
+        if (next === catalogue || (next.version && next.version === catalogue.version && next.sections.length === catalogue.sections.length))
+            return;
+        catalogue = next;
+        changed();
+    };
+    const refreshCatalogue = newestRead(async (fresh) => {
+        const value = await readCatalogue({ fresh });
+        const read = value === undefined ? null : parseCatalogue(value);
+        if (!read)
+            return undefined;
+        if (read.version !== catalogue.version)
+            store?.save(value);
+        return read;
+    }, applyCatalogue);
+    const refreshAccount = newestRead(async (fresh) => {
+        const settings = await readAccount({ fresh });
+        return settings === undefined ? undefined : settings === null ? [] : (parseOverrides(settings.shortcuts) ?? []);
+    }, applyOverrides);
+    const refresh = async ({ fresh = false } = {}) => {
+        lastRefreshAt = Date.now();
+        await Promise.all([refreshCatalogue(fresh), refreshAccount(fresh)]);
+    };
+    return {
+        catalogue: () => catalogue,
+        actions: (...sectionIds) => sectionActions(catalogue, ...sectionIds),
+        overrides: () => overrides,
+        bindings(actions) {
+            let map = resolved.get(actions);
+            if (!map) {
+                map = resolveBindings(actions, overrides);
+                resolved.set(actions, map);
+            }
+            return map;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        refresh,
+        bind() {
+            const win = globalThis;
+            if (bound || typeof win.addEventListener !== 'function' || !win.document?.addEventListener)
+                return;
+            bound = true;
+            void refresh();
+            const onFront = () => {
+                if (win.document?.visibilityState !== 'visible' || Date.now() - lastRefreshAt < REFRESH_GAP_MS)
+                    return;
+                void refresh({ fresh: true });
+            };
+            win.document.addEventListener('visibilitychange', onFront);
+            win.addEventListener('focus', onFront);
+        },
+        setOverrides: applyOverrides,
+        setCatalogue: applyCatalogue,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "dist/index.js",