entangled-worlds-orbiters-shared 4.0.0 → 4.2.0

package/src/shortcuts/match.ts

@@ -0,0 +1,195 @@
+// Which action a key press is. Each app keeps what its actions DO; this only answers which one a
+// press names, so every app reads keys the same way: the modifiers, a field being typed in, and a
+// surface that holds letters of its own are decided here, once.
+
+import { chordMatches, isCommandChord, isModifierCode, keysOverlap, parseChord, parseKeys, type Chord, type ModifierState } from './chord.js'
+
+/** One thing a key can do, as an app's catalogue declares 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. */
+  readonly label: string
+  /** 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). */
+  readonly scope: Scope
+  /** Where a command menu lists it (`panels`, `snapshots`); unset, under the section itself. */
+  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
+}
+
+/** 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.
+ */
+export type ShortcutOverrides = ReadonlyArray<{ readonly id: string; readonly keys: readonly string[] }>
+
+/** The key press as the matcher reads it: a `KeyboardEvent` has all of it. */
+export interface ShortcutEvent extends ModifierState {
+  readonly code: string
+  readonly key: string
+  readonly target?: unknown
+}
+
+/**
+ * Every action's keys: its defaults, or the person's override (unknown actions and keys that name no
+ * chord are dropped). Catalogue order is kept, so the earlier catalogue wins where two match one press.
+ */
+export function resolveBindings(
+  catalogue: Iterable<ShortcutAction>,
+  overrides: ShortcutOverrides = [],
+): Map<string, readonly string[]> {
+  const own = new Map<string, readonly string[]>()
+  for (const entry of Array.isArray(overrides) ? overrides : []) {
+    if (entry && typeof entry.id === 'string' && Array.isArray(entry.keys)) own.set(entry.id, entry.keys)
+  }
+  const bindings = new Map<string, readonly string[]>()
+  for (const action of catalogue) {
+    const keys = own.get(action.id) ?? action.defaultKeys
+    bindings.set(action.id, keys.filter((key) => typeof key === 'string' && parseKeys(key) !== null))
+  }
+  return bindings
+}
+
+/** Two actions one press could be: `[first, second, the key of the first that clashes]`. */
+export function findClashes(bindings: ShortcutBindings): Array<readonly [string, string, string]> {
+  const entries = [...bindings]
+  const clashes: Array<readonly [string, string, string]> = []
+  entries.forEach(([a, aKeys], i) => {
+    for (const [b, bKeys] of entries.slice(i + 1)) {
+      const key = aKeys.find((ak) => bKeys.some((bk) => keysOverlap(ak, bk)))
+      if (key !== undefined) clashes.push([a, b, key])
+    }
+  })
+  return clashes
+}
+
+// ---------------------------------------------------------------------------------------------
+// Surface claims
+
+const claims = new Set<ReadonlySet<string>>()
+
+/**
+ * Take letters away from the shortcuts while a surface is on screen, until the returned release is
+ * called. An on-screen keyboard plays from the computer keyboard, and a note key that also switched a
+ * panel would take the keyboard away mid-phrase. Keys are `event.key` values, lower-cased (the
+ * character, as the keyboard surface reads them).
+ */
+export function claimKeys(keys: Iterable<string>): () => void {
+  const claim: ReadonlySet<string> = new Set([...keys].map((key) => key.toLowerCase()))
+  claims.add(claim)
+  return () => {
+    claims.delete(claim)
+  }
+}
+
+/** Whether a surface holds this key. A key with Ctrl, ⌘ or Option is never claimed (⌘Z stays undo). */
+export function isKeyClaimed(event: Pick<ShortcutEvent, 'key' | 'metaKey' | 'ctrlKey' | 'altKey'>): boolean {
+  if (!claims.size || typeof event.key !== 'string' || event.metaKey || event.ctrlKey || event.altKey) return false
+  const key = event.key.toLowerCase()
+  for (const claim of claims) if (claim.has(key)) return true
+  return false
+}
+
+// ---------------------------------------------------------------------------------------------
+// Typing
+
+interface TargetLike {
+  readonly isContentEditable?: boolean
+  readonly tagName?: unknown
+  readonly type?: unknown
+  getAttribute?(name: string): string | null
+}
+
+const asTarget = (target: unknown): TargetLike | null =>
+  target !== null && typeof target === 'object' ? (target as TargetLike) : null
+
+const roleOf = (el: TargetLike) => (typeof el.getAttribute === 'function' ? el.getAttribute('role') : null)
+
+/** Inputs that take no typing: a slider keeps the shortcuts working while it holds focus. */
+const UNTYPED_INPUTS = new Set(['range', 'color', 'file'])
+
+/** A text field: every key typed there is the field's, ⌘Z included (it undoes the typing). */
+export function isTypingTarget(target: unknown): boolean {
+  const el = asTarget(target)
+  if (!el) return false
+  if (el.isContentEditable === true || roleOf(el) === 'textbox') return true
+  const tag = typeof el.tagName === 'string' ? el.tagName.toUpperCase() : ''
+  if (tag === 'INPUT') return !UNTYPED_INPUTS.has(typeof el.type === 'string' ? el.type.toLowerCase() : '')
+  return tag === 'TEXTAREA' || tag === 'SELECT'
+}
+
+/** A widget that reads typed characters (a combobox's type-to-find), though it is no text field. */
+function readsCharacters(target: unknown): boolean {
+  const el = asTarget(target)
+  return el !== null && roleOf(el) === 'combobox'
+}
+
+/**
+ * The action this press is, or `null`. Not one while the person is typing in a field, nor a key a
+ * surface holds; a widget that reads characters keeps its characters but not the ⌘ commands.
+ */
+export function matchShortcut(event: ShortcutEvent, bindings: ShortcutBindings): string | null {
+  if (!event.code || isTypingTarget(event.target) || isKeyClaimed(event)) return null
+  const characters = readsCharacters(event.target)
+  for (const [actionId, keys] of bindings) {
+    for (const key of keys) {
+      const chord = parseChord(key)
+      if (!chord || !chordMatches(chord, event.code, event)) continue
+      if (characters && !isCommandChord(chord)) return null
+      return actionId
+    }
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------------------------
+// Sequences
+
+/** How long the second key of a sequence (`G`, then `H`) may follow the first. */
+export const SEQUENCE_WAIT_MS = 1500
+
+// The sequences of a set of bindings, read once per bindings object (they change with the overrides).
+const sequencesOf = new WeakMap<object, Array<readonly [string, Chord[]]>>()
+function sequences(bindings: ShortcutBindings): Array<readonly [string, Chord[]]> {
+  const known = typeof bindings === 'object' ? sequencesOf.get(bindings) : undefined
+  if (known) return known
+  const found = [...bindings].flatMap(([id, keys]) =>
+    keys.map((k) => [id, parseKeys(k)] as const).filter((entry): entry is readonly [string, Chord[]] => entry[1]?.length === 2))
+  if (typeof bindings === 'object') sequencesOf.set(bindings, found)
+  return found
+}
+
+/**
+ * A matcher that also knows sequences: it remembers the first key of one for a moment and answers
+ * the action when the second follows. One per listener (it holds that moment). A first key answers
+ * nothing; any other key, a typed one or a wait past `waitMs` forgets it.
+ */
+export function createShortcutMatcher(waitMs: number = SEQUENCE_WAIT_MS, now: () => number = Date.now) {
+  let first: (ModifierState & { code: string; at: number }) | null = null
+  return function match(event: ShortcutEvent, bindings: ShortcutBindings): string | null {
+    if (event.code && isModifierCode(event.code)) return null
+    const pending = first && now() - first.at <= waitMs ? first : null
+    first = null
+    if (!event.code || isTypingTarget(event.target) || isKeyClaimed(event)) return null
+    // A widget that reads characters keeps them: no sequence starts or ends there.
+    const characters = readsCharacters(event.target)
+    const known = characters ? [] : sequences(bindings)
+    if (pending) {
+      for (const [id, [one, two]] of known)
+        if (chordMatches(one, pending.code, pending) && chordMatches(two, event.code, event)) return id
+    }
+    if (known.some(([, [one]]) => chordMatches(one, event.code, event))) {
+      first = { code: event.code, shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey, at: now() }
+      return null
+    }
+    return matchShortcut(event, bindings)
+  }
+}

package/src/shortcuts/orbiters.ts

@@ -0,0 +1,132 @@
+// The Orbiters catalogues: every key Orbiters answers, with the keys it has by default.
+//
+// `voice` acts on the focused deck(s), so in a shared session it only reaches a deck this person
+// holds; `client` is about this machine and no deck (MIDI learn, performance mode, the Studio).
+
+import type { ShortcutAction } from './match.js'
+
+export type OrbitersShortcutScope = 'voice' | 'client'
+export type OrbitersShortcut = ShortcutAction<OrbitersShortcutScope>
+
+export const ORBITERS_PLAY_SECTION = 'orbiters-play'
+export const ORBITERS_STUDIO_SECTION = 'orbiters-studio'
+
+interface ActionOptions {
+  scope?: OrbitersShortcutScope
+  group?: string
+  command?: boolean
+}
+
+const play = (id: string, label: string, defaultKeys: readonly string[], { scope = 'voice', group, command }: ActionOptions = {}): OrbitersShortcut =>
+  Object.freeze({
+    id: `orbiters.play.${id}`, section: ORBITERS_PLAY_SECTION, label, defaultKeys: Object.freeze([...defaultKeys]), scope,
+    ...(group ? { group } : {}), ...(command === false ? { command } : {}),
+  })
+
+const studio = (id: string, label: string, defaultKeys: readonly string[]): OrbitersShortcut =>
+  Object.freeze({ id: `orbiters.studio.${id}`, section: ORBITERS_STUDIO_SECTION, label, defaultKeys: Object.freeze([...defaultKeys]), scope: 'client', group: 'studio' })
+
+/** How a command menu groups the actions, in its order. */
+export const ORBITERS_COMMAND_GROUPS = Object.freeze([
+  { id: 'transport', label: 'Transport' },
+  { id: 'view', label: 'View' },
+  { id: 'snapshots', label: 'Snapshots' },
+  { id: 'panels', label: 'Panels' },
+  { id: 'orbiter', label: 'Orbiter' },
+  { id: 'studio', label: 'Studio' },
+] as const)
+
+/** The snapshot slots, by the number each shows: the number row, 1 to 9, then 0. */
+const SLOT_NUMBERS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 0]
+
+/** Undo and redo, the same keys wherever an edit can be taken back. */
+const UNDO_KEYS = ['Mod+KeyZ']
+const REDO_KEYS = ['Mod+Shift+KeyZ', 'Ctrl+Shift?+KeyY']
+
+/**
+ * Playing an Orbiter. Shift is free on most keys (`Shift?`): it is held to select several decks,
+ * and a key pressed while selecting means what it means alone.
+ */
+export const ORBITERS_PLAY_SHORTCUTS: readonly OrbitersShortcut[] = Object.freeze([
+  // Space takes Ctrl, Option and ⌘ as it comes: only Shift changes what it does.
+  play('transport.toggle', 'Play or pause', ['Alt?+Ctrl?+Meta?+Space'], { group: 'transport' }),
+  play('transport.restart', 'Play from the beginning', ['Shift+Alt?+Ctrl?+Meta?+Space'], { group: 'transport' }),
+  play('rec.hold', 'Record while held', ['KeyR'], { group: 'transport', command: false }),
+  play('rec.toggle', 'Rec on or off', ['Shift+KeyR'], { group: 'transport' }),
+  play('history.undo', 'Undo', UNDO_KEYS, { group: 'transport' }),
+  play('history.redo', 'Redo', REDO_KEYS, { group: 'transport' }),
+  play('dimension.1', 'First dimension', ['Shift?+Digit1'], { group: 'view' }),
+  play('dimension.2', 'Second dimension', ['Shift?+Digit2'], { group: 'view' }),
+  play('dimension.3', 'Third dimension', ['Shift?+Digit3'], { group: 'view' }),
+  play('body.world', 'World', ['Shift?+KeyQ'], { group: 'view' }),
+  play('body.moon', 'Moon', ['Shift?+KeyW'], { group: 'view' }),
+  play('body.star', 'Star', ['Shift?+KeyE'], { group: 'view' }),
+  ...SLOT_NUMBERS.map((n) => play(`snapshot.recall.${n}`, `Recall snapshot ${n}`, [`Alt+Digit${n}`], { group: 'snapshots' })),
+  ...SLOT_NUMBERS.map((n) => play(`snapshot.store.${n}`, `Store snapshot ${n}`, [`Alt+Shift+Digit${n}`], { group: 'snapshots' })),
+  // The panels, from the bottom of the rail up.
+  play('panel.jamming', 'Jamming', ['KeyA'], { group: 'panels' }),
+  play('panel.playback', 'Playback', ['KeyS'], { group: 'panels' }),
+  play('panel.cosmicLfo', 'Cosmic LFO', ['KeyD'], { group: 'panels' }),
+  play('panel.sensors', 'Sensors', ['KeyF'], { group: 'panels' }),
+  // The More menu, and this machine's switches.
+  play('midiLearn', 'MIDI learn', ['Shift?+KeyM'], { scope: 'client', group: 'orbiter' }),
+  play('performanceMode', 'Performance mode', ['Shift?+KeyP'], { scope: 'client', group: 'orbiter' }),
+  play('screenCapture', 'Screen capture', [], { scope: 'client', group: 'orbiter' }),
+  play('share', 'Share', [], { scope: 'client', group: 'orbiter' }),
+  play('fullscreen', 'Fullscreen', [], { scope: 'client', group: 'orbiter' }),
+  // `?` on a US keyboard: the key's place, whatever this keyboard prints there.
+  play('help', 'Keyboard shortcuts', ['Shift?+Slash'], { scope: 'client', group: 'orbiter', command: false }),
+  play('commands', 'Commands', ['Mod+KeyK'], { scope: 'client', group: 'orbiter', command: false }),
+])
+
+/**
+ * The keys sheet (`?`): what to look up at a glance, in three columns. A row may stand for several
+ * actions whose keys differ only in the last key ("Dimension I · II · III — 1 2 3"); the keys
+ * shown are always this person's (`mergedKeyParts`).
+ */
+export const ORBITERS_PLAY_SHEET = Object.freeze([
+  { id: 'transport', label: 'Transport', rows: [
+    { id: 'playPause', label: 'Play / pause', actions: ['transport.toggle'] },
+    { id: 'playFromStart', label: 'Play from start', actions: ['transport.restart'] },
+    { id: 'recHeld', label: 'REC while held', actions: ['rec.hold'] },
+    { id: 'recLatch', label: 'REC latch', actions: ['rec.toggle'] },
+    { id: 'undo', label: 'Undo', actions: ['history.undo'] },
+    { id: 'redo', label: 'Redo', actions: ['history.redo'] },
+  ] },
+  { id: 'view', label: 'View', rows: [
+    { id: 'dimensions', label: 'Dimension I · II · III', actions: ['dimension.1', 'dimension.2', 'dimension.3'] },
+    { id: 'bodies', label: 'World · Moon · Star', actions: ['body.world', 'body.moon', 'body.star'] },
+    { id: 'snapshotRecall', label: 'Snapshot recall', actions: SLOT_NUMBERS.map((n) => `snapshot.recall.${n}`) },
+    { id: 'snapshotStore', label: 'Snapshot store', actions: SLOT_NUMBERS.map((n) => `snapshot.store.${n}`) },
+  ] },
+  { id: 'panels', label: 'Panels', rows: [
+    { id: 'jamming', label: 'Jamming', actions: ['panel.jamming'] },
+    { id: 'playback', label: 'Playback', actions: ['panel.playback'] },
+    { id: 'cosmicLfo', label: 'Cosmic LFO', actions: ['panel.cosmicLfo'] },
+    { id: 'sensors', label: 'Sensors', actions: ['panel.sensors'] },
+    { id: 'midiLearn', label: 'MIDI learn', actions: ['midiLearn'] },
+    { id: 'performanceMode', label: 'Performance mode', actions: ['performanceMode'] },
+  ] },
+].map((column) => Object.freeze({
+  ...column,
+  rows: Object.freeze(column.rows.map((row) => Object.freeze({ ...row, actions: Object.freeze(row.actions.map((a) => `orbiters.play.${a}`)) }))),
+})))
+
+/**
+ * The Studio. It is open over play, so the play keys above still work there; where both name a key,
+ * the Studio's action is the one.
+ */
+export const ORBITERS_STUDIO_SHORTCUTS: readonly OrbitersShortcut[] = Object.freeze([
+  studio('undo', 'Undo', UNDO_KEYS),
+  studio('redo', 'Redo', REDO_KEYS),
+  studio('map', 'Map', ['Shift+KeyM']),
+])
+
+/**
+ * The letters the on-screen keyboard plays while it is open (`event.key`, lower-case): the piano row,
+ * then Z and X for the octave and C and V for velocity. While it is up they are its notes, and the
+ * shortcuts on them wait (`claimKeys`); a settings page says so beside those keys.
+ */
+export const ORBITERS_KEYBOARD_SURFACE_KEYS: readonly string[] = Object.freeze([
+  'a', 'w', 's', 'e', 'd', 'f', 't', 'g', 'y', 'h', 'u', 'j', 'k', 'o', 'l', 'p', ';', "'", 'z', 'x', 'c', 'v',
+])

package/src/shortcuts/overrides.ts

@@ -0,0 +1,110 @@
+// A person's shortcut overrides, read the same way by every app: from their account when signed in
+// (someone signed out has the default keys), and again whenever the page comes back to the front (a key changed
+// on the settings page applies on return, without a reload).
+//
+// Framework-free: the app hands in how it reads the account (its own API client) and gets the
+// overrides and each catalogue's resolved keys back, kept until the overrides change.
+
+import { resolveBindings, 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 function parseOverrides(value: unknown): ShortcutOverrides | null {
+  if (!Array.isArray(value)) return null
+  return value.filter(
+    (entry): entry is { id: string; keys: string[] } =>
+      !!entry && typeof entry.id === 'string' && Array.isArray(entry.keys) && entry.keys.every((k: unknown) => typeof k === 'string'),
+  )
+}
+
+/**
+ * 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>
+
+export interface ShortcutOverridesSource {
+  /** The overrides in force. */
+  get(): ShortcutOverrides
+  /** A catalogue's actions with their keys now (kept until the overrides change). */
+  bindings(catalogue: readonly ShortcutAction[]): Map<string, readonly string[]>
+  /** Called whenever the overrides change; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void
+  /** Read again (`fresh`: past the app's own cached read). The newest read 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. */
+  set(overrides: ShortcutOverrides): void
+}
+
+/** Coming back to the front twice in a row (visible, then focus) asks the account once. */
+const REFRESH_GAP_MS = 2000
+
+export function createShortcutOverridesSource(readAccount: ReadAccountSettings): ShortcutOverridesSource {
+  let overrides: ShortcutOverrides = []
+  let resolved = new WeakMap<readonly ShortcutAction[], Map<string, readonly string[]>>()
+  let latest = 0
+  let applied = 0
+  let lastRefreshAt = -Infinity
+  let bound = false
+  const listeners = new Set<() => void>()
+
+  const apply = (next: ShortcutOverrides) => {
+    if (JSON.stringify(next) === JSON.stringify(overrides)) return
+    overrides = next
+    resolved = new WeakMap()
+    listeners.forEach((listener) => listener())
+  }
+
+  const refresh = async ({ fresh = false }: { fresh?: boolean } = {}) => {
+    const ticket = ++latest
+    lastRefreshAt = Date.now()
+    let settings: { shortcuts?: unknown } | null | undefined
+    try {
+      settings = await readAccount({ fresh })
+    } catch {
+      settings = undefined
+    }
+    // The newest read that answered wins: an older one ending after it says nothing new, and a newer
+    // one that failed does not throw away an older one's answer.
+    if (settings === undefined || ticket < applied) return
+    applied = ticket
+    apply(settings === null ? [] : (parseOverrides(settings.shortcuts) ?? []))
+  }
+
+  return {
+    get: () => overrides,
+    bindings(catalogue) {
+      let map = resolved.get(catalogue)
+      if (!map) {
+        map = resolveBindings(catalogue, overrides)
+        resolved.set(catalogue, map)
+      }
+      return map
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    refresh,
+    bind() {
+      const win = globalThis as unknown as {
+        addEventListener?: (type: string, fn: () => void) => void
+        document?: { visibilityState?: string; addEventListener?: (type: string, fn: () => void) => void }
+      }
+      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)
+    },
+    set: apply,
+  }
+}

package/src/shortcuts/sections.ts

@@ -0,0 +1,36 @@
+// Every app's catalogue in one place, in the order a settings page shows them. A section is one
+// surface's keys; two actions may share a key only across sections (the Orbiter Studio lies over
+// play, and takes ⌘Z from it while it is open).
+
+import type { ShortcutAction } from './match.js'
+import { EW_PLAYER_SECTION, EW_PLAYER_SHORTCUTS, EW_STUDIO_SECTION, EW_STUDIO_SHORTCUTS } from './entangledWorlds.js'
+import { ORBITERS_PLAY_SECTION, ORBITERS_PLAY_SHORTCUTS, ORBITERS_STUDIO_SECTION, ORBITERS_STUDIO_SHORTCUTS } from './orbiters.js'
+import { SITE_SECTION, SITE_SHORTCUTS } from './site.js'
+
+/** The apps a person tells apart, in the order a settings page shows them. */
+export const SHORTCUT_APPS = Object.freeze([
+  Object.freeze({ id: 'plantasia-space', label: 'Plantasia Space' }),
+  Object.freeze({ id: 'orbiters', label: 'Orbiters' }),
+  Object.freeze({ id: 'entangled-worlds', label: 'Entangled Worlds' }),
+] as const)
+
+export type ShortcutAppId = (typeof SHORTCUT_APPS)[number]['id']
+
+export interface ShortcutSection {
+  readonly id: string
+  readonly label: string
+  /** The app it belongs to. */
+  readonly app: ShortcutAppId
+  /** Its name inside that app (`Play`, `Studio`); none when the app has only this section. */
+  readonly part?: string
+  readonly actions: readonly ShortcutAction[]
+}
+
+export const SHORTCUT_SECTIONS: readonly ShortcutSection[] = Object.freeze<ShortcutSection[]>([
+  Object.freeze({ id: SITE_SECTION, label: 'Plantasia Space', app: 'plantasia-space', actions: SITE_SHORTCUTS }),
+  Object.freeze({ id: ORBITERS_PLAY_SECTION, label: 'Orbiters play', app: 'orbiters', part: 'Play', actions: ORBITERS_PLAY_SHORTCUTS }),
+  Object.freeze({ id: ORBITERS_STUDIO_SECTION, label: 'Orbiter Studio', app: 'orbiters', part: 'Studio', actions: ORBITERS_STUDIO_SHORTCUTS }),
+  Object.freeze({ id: EW_STUDIO_SECTION, label: 'Entangled Worlds studio', app: 'entangled-worlds', part: 'Studio', actions: EW_STUDIO_SHORTCUTS }),
+  Object.freeze({ id: EW_PLAYER_SECTION, label: 'Entangled Worlds player', app: 'entangled-worlds', part: 'Player', actions: EW_PLAYER_SHORTCUTS }),
+])
+

package/src/shortcuts/site.ts

@@ -0,0 +1,33 @@
+// The Plantasia Space site's own keys: the pages around the apps (home, explore, settings). They
+// work on any page of the site, outside an Orbiter or a world.
+
+import type { ShortcutAction } from './match.js'
+
+export type SiteShortcut = ShortcutAction<'client'>
+
+export const SITE_SECTION = 'site'
+
+const site = (id: string, label: string, keys: string): SiteShortcut =>
+  Object.freeze({ id: `site.${id}`, section: SITE_SECTION, label, defaultKeys: Object.freeze([keys]), scope: 'client' as const })
+
+/**
+ * Two-key sequences move around the site (G, then H for Home; N, then O for a new Orbiter), as on
+ * many sites: a single letter is an Orbiter's on a page that plays one, and the browser holds most
+ * ⌘ and ⇧⌘ letters.
+ */
+export const SITE_SHORTCUTS: readonly SiteShortcut[] = Object.freeze([
+  site('settings', 'Open settings', 'Mod+Shift+Comma'),
+  site('commands', 'Commands', 'Mod+KeyK'),
+  site('search', 'Search', 'Slash'),
+  site('go.home', 'Home', 'KeyG KeyH'),
+  site('go.playground', 'Playground', 'KeyG KeyP'),
+  site('go.notifications', 'Notifications', 'KeyG KeyN'),
+  site('go.audios', 'My audios', 'KeyG KeyA'),
+  site('go.orbiters', 'My Orbiters', 'KeyG KeyO'),
+  site('go.worlds', 'My Entangled Worlds', 'KeyG KeyW'),
+  site('go.collections', 'My collections', 'KeyG KeyC'),
+  site('go.stars', 'My stars', 'KeyG KeyS'),
+  site('new.orbiter', 'New Orbiter', 'KeyN KeyO'),
+  site('new.audio', 'New audio', 'KeyN KeyA'),
+  site('new.world', 'New Entangled World', 'KeyN KeyW'),
+])