entangled-worlds-orbiters-shared 4.2.0 → 5.1.0

package/dist/sky/sky.js

@@ -0,0 +1,268 @@
+// The sky behind a world: stars (one Points draw), an optional nebula + Milky Way whose shape is
+// baked into a small cube target shared by every sky on the renderer with the same shape (one
+// textured box per frame, coloured live), and, under a world sky, the constellation figures (one
+// LineSegments). All three draw after the opaque bodies with depth test
+// on, so sky behind a planet costs nothing.
+//
+// Cost, measured against the six-face painted skycube it replaces (bench/sky): stars alone about
+// 40% of its frame time; with the nebula about the same frame time, at 1/5–1/15 of its GPU memory
+// and with nothing to download.
+import * as THREE from 'three';
+import { DEFAULT_SKY_PARAMS, SKY_LOOK_KEYS, normalizeSkyParams } from './params.js';
+import { buildLineGeometry, buildStarGeometry, galacticBandFrame, seededBandFrame } from './geometry.js';
+import { createLcg } from '../star/layout.js';
+import { BAKE_FRAGMENT, BAKE_VERTEX, GLOW_SEEDED, GLOW_WORLD, LINE_FRAGMENT, LINE_VERTEX, NEBULA_FRAGMENT, NEBULA_VERTEX, STAR_FRAGMENT, STAR_VERTEX, } from './shaders.js';
+const RENDER_ORDER = 1000;
+const kits = new WeakMap();
+function kitFor(renderer) {
+    let kit = kits.get(renderer);
+    if (!kit) {
+        const uniforms = {
+            uSeed: { value: 0 },
+            uBand: { value: 0 },
+            uToBand: { value: new THREE.Matrix3() },
+            uCoreDir: { value: new THREE.Vector3(1, 0, 0) },
+        };
+        const geometry = new THREE.BoxGeometry(2, 2, 2);
+        const material = new THREE.ShaderMaterial({ uniforms, vertexShader: BAKE_VERTEX, fragmentShader: BAKE_FRAGMENT, side: THREE.BackSide, depthTest: false, depthWrite: false });
+        const scene = new THREE.Scene();
+        scene.add(new THREE.Mesh(geometry, material));
+        kit = { scene, geometry, material, fields: new Map() };
+        kits.set(renderer, kit);
+    }
+    return kit;
+}
+function acquireField(renderer, size, seed, band, frame, frameKey) {
+    const kit = kitFor(renderer);
+    const key = `${size}|${seed}|${band}|${frameKey}`;
+    let field = kit.fields.get(key);
+    if (!field) {
+        // Half-float where the GPU can render to it: the glow fades into the black over a handful of
+        // 8-bit levels, which show as hard stair-stepped contours. No depth: the bake tests none.
+        const ext = renderer.extensions;
+        const halfFloat = Boolean(ext?.has('EXT_color_buffer_half_float') || ext?.has('EXT_color_buffer_float'));
+        const target = new THREE.WebGLCubeRenderTarget(size, {
+            generateMipmaps: false,
+            depthBuffer: false,
+            minFilter: THREE.LinearFilter,
+            magFilter: THREE.LinearFilter,
+            type: halfFloat ? THREE.HalfFloatType : THREE.UnsignedByteType,
+        });
+        field = { target, bytes: 6 * size * size * (halfFloat ? 8 : 4), refs: 0, baked: false, seed, band, frame };
+        kit.fields.set(key, field);
+    }
+    field.refs++;
+    return { key, field };
+}
+function releaseField(renderer, key) {
+    const kit = kits.get(renderer);
+    const field = kit?.fields.get(key);
+    if (!kit || !field || --field.refs > 0)
+        return;
+    field.target.dispose();
+    kit.fields.delete(key);
+    // The last field gone: the bake's own box and shader go too, until a glow is wanted again.
+    if (kit.fields.size === 0) {
+        kit.geometry.dispose();
+        kit.material.dispose();
+        kits.delete(renderer);
+    }
+}
+function bakeField(renderer, field) {
+    const kit = kitFor(renderer);
+    const u = kit.material.uniforms;
+    // The shader offsets noise by the seed in float32: a 31-bit seed would erase its fraction, so
+    // the shader gets a small value derived from it.
+    u.uSeed.value = createLcg(field.seed)() * 1000;
+    u.uBand.value = field.band;
+    u.uToBand.value.setFromMatrix4(field.frame.basis).transpose();
+    u.uCoreDir.value.copy(field.frame.core);
+    new THREE.CubeCamera(0.1, 10, field.target).update(renderer, kit.scene);
+    field.baked = true;
+}
+export function createSky(renderer, initial = {}, options = {}) {
+    let p = normalizeSkyParams({ ...DEFAULT_SKY_PARAMS, ...initial });
+    let world = options.world ?? null;
+    const nebulaSize = options.nebulaSize ?? 512;
+    const usesWorld = () => p.source === 'world' && world !== null;
+    const frame = () => (usesWorld() ? galacticBandFrame() : seededBandFrame(p.seed, p.bandTilt));
+    const frameKey = () => (usesWorld() ? 'galactic' : `seeded:${p.bandTilt}`);
+    const farUniform = { value: 1000 };
+    const starUniforms = {
+        uTime: { value: 0 },
+        uBrightness: { value: p.brightness },
+        uSize: { value: p.size },
+        uColour: { value: p.colour },
+        uTwinkle: { value: p.twinkle },
+        uPixelScale: { value: 1 },
+        uGlowAt: { value: GLOW_SEEDED },
+    };
+    const starMat = new THREE.ShaderMaterial({
+        uniforms: starUniforms,
+        vertexShader: STAR_VERTEX,
+        fragmentShader: STAR_FRAGMENT,
+        blending: THREE.AdditiveBlending,
+        depthWrite: false,
+        transparent: true,
+    });
+    // The glow: a box at infinity sampling the shared field, coloured by these uniforms.
+    const nebulaUniforms = {
+        uNebula: { value: null },
+        uFar: farUniform,
+        uAmount: { value: p.nebula },
+        uHue: { value: p.hue },
+        uSpread: { value: p.hueSpread },
+    };
+    const nebulaMat = new THREE.ShaderMaterial({
+        uniforms: nebulaUniforms,
+        vertexShader: NEBULA_VERTEX,
+        fragmentShader: NEBULA_FRAGMENT,
+        side: THREE.BackSide,
+        depthWrite: false,
+    });
+    const nebula = new THREE.Mesh(new THREE.BoxGeometry(2, 2, 2), nebulaMat);
+    nebula.name = 'SkyNebula';
+    nebula.frustumCulled = false;
+    // Opaque, but drawn after every opaque body: the depth test skips the pixels a planet covers.
+    nebula.renderOrder = RENDER_ORDER;
+    // Every layer reads the camera's far plane: whichever draws first sets it for the frame.
+    const trackFar = (_r, _s, cam) => {
+        farUniform.value = cam.far;
+    };
+    nebula.onBeforeRender = trackFar;
+    const lineUniforms = { uLines: { value: p.constellations }, uFar: farUniform };
+    const lineMat = new THREE.ShaderMaterial({ uniforms: lineUniforms, vertexShader: LINE_VERTEX, fragmentShader: LINE_FRAGMENT, blending: THREE.AdditiveBlending, depthWrite: false, transparent: true });
+    const object = new THREE.Group();
+    object.name = 'Sky';
+    object.add(nebula);
+    let stars = null;
+    let lines = null;
+    let linesFor = null;
+    // The glow field this sky holds (none while the glow is off: its memory goes back).
+    let held = null;
+    const syncGlow = () => {
+        const wanted = p.nebula > 0 ? `${nebulaSize}|${p.seed}|${p.band}|${frameKey()}` : null;
+        if (held?.key === wanted)
+            return;
+        if (held)
+            releaseField(renderer, held.key);
+        held = wanted ? acquireField(renderer, nebulaSize, p.seed, p.band, frame(), frameKey()) : null;
+        nebulaUniforms.uNebula.value = held ? held.field.target.texture : null;
+        nebula.visible = held !== null;
+    };
+    const buildStars = () => {
+        if (stars) {
+            object.remove(stars);
+            stars.geometry.dispose();
+        }
+        const w = usesWorld() ? world : null;
+        stars = new THREE.Points(buildStarGeometry({ seed: p.seed, count: p.count, band: p.band, frame: frame(), world: w }), starMat);
+        stars.name = 'SkyStars';
+        stars.frustumCulled = false;
+        stars.renderOrder = RENDER_ORDER + 1;
+        stars.onBeforeRender = trackFar;
+        object.add(stars);
+        starUniforms.uGlowAt.value = w ? GLOW_WORLD : GLOW_SEEDED;
+    };
+    // The figures depend on the world sky alone: kept across every other change.
+    const syncLines = () => {
+        const w = usesWorld() ? world : null;
+        if (w === linesFor)
+            return;
+        linesFor = w;
+        if (lines) {
+            object.remove(lines);
+            lines.geometry.dispose();
+            lines = null;
+        }
+        if (w && w.lines.length > 0) {
+            lines = new THREE.LineSegments(buildLineGeometry(w), lineMat);
+            lines.name = 'SkyConstellations';
+            lines.frustumCulled = false;
+            lines.renderOrder = RENDER_ORDER + 2;
+            lines.onBeforeRender = trackFar;
+            object.add(lines);
+        }
+    };
+    const applyLook = () => {
+        starUniforms.uBrightness.value = p.brightness;
+        starUniforms.uSize.value = p.size;
+        starUniforms.uColour.value = p.colour;
+        starUniforms.uTwinkle.value = p.twinkle;
+        lineUniforms.uLines.value = p.constellations;
+        if (lines)
+            lines.visible = p.constellations > 0;
+        nebulaUniforms.uAmount.value = p.nebula;
+        nebulaUniforms.uHue.value = p.hue;
+        nebulaUniforms.uSpread.value = p.hueSpread;
+    };
+    // A rebuild runs at most once a frame, from `update`: a density drag that moves many times
+    // between frames builds once.
+    let rebuildPending = false;
+    const rebuild = () => {
+        buildStars();
+        syncLines();
+        syncGlow();
+        applyLook();
+    };
+    rebuild();
+    const bytes = (g) => {
+        let n = 0;
+        for (const a of Object.values(g.attributes))
+            n += a.array.byteLength;
+        return n;
+    };
+    return {
+        object,
+        setParams(next) {
+            const prev = p;
+            p = normalizeSkyParams({ ...p, ...next });
+            // A world sky's band is the galactic plane: its tilt changes nothing there.
+            const changed = Object.keys(next).filter((k) => prev[k] !== p[k] && !(k === 'bandTilt' && usesWorld()));
+            if (changed.length === 0)
+                return;
+            applyLook();
+            // Glow on or off: hold or let go of its field now (no star work).
+            syncGlow();
+            if (!changed.every((k) => SKY_LOOK_KEYS.includes(k)))
+                rebuildPending = true;
+        },
+        setWorld(next) {
+            if (next === world)
+                return;
+            world = next;
+            if (p.source === 'world')
+                rebuildPending = true;
+        },
+        update(timeSec, drawingBufferHeight) {
+            if (rebuildPending) {
+                rebuildPending = false;
+                rebuild();
+            }
+            if (held && !held.field.baked)
+                bakeField(renderer, held.field);
+            starUniforms.uTime.value = timeSec;
+            starUniforms.uPixelScale.value = drawingBufferHeight / 1080;
+        },
+        gpuBytes() {
+            let n = stars ? bytes(stars.geometry) : 0;
+            if (lines)
+                n += bytes(lines.geometry);
+            // The glow field is shared: each sky holding it counts its share.
+            if (held)
+                n += held.field.bytes / held.field.refs;
+            return n;
+        },
+        dispose() {
+            stars?.geometry.dispose();
+            lines?.geometry.dispose();
+            starMat.dispose();
+            lineMat.dispose();
+            nebula.geometry.dispose();
+            nebulaMat.dispose();
+            if (held)
+                releaseField(renderer, held.key);
+            held = null;
+        },
+    };
+}

package/dist/sky/worldSkyFile.d.ts

@@ -0,0 +1,16 @@
+export declare const WORLD_SKY_MAGIC = "WSKY";
+export declare const WORLD_SKY_FORMAT = 1;
+export interface WorldSky {
+    datasetVersion: number;
+    starCount: number;
+    /** Star directions, `Int16 × 3` per star; a view into the file. */
+    directions: Int16Array;
+    /** Star colour + brightness, `Uint8 × 4` per star; a view into the file. */
+    colourBrightness: Uint8Array;
+    /** Constellation line vertices, `Int16 × 3` each, in segment pairs; a view into the file. */
+    lines: Int16Array;
+    /** Seeded stars to add so a far host's sky still reads Earth-like. */
+    standIns: number;
+}
+/** Wraps a world-sky file. Throws on anything that is not a complete format-1 file. */
+export declare function parseWorldSky(buffer: ArrayBuffer): WorldSky;

package/dist/sky/worldSkyFile.js

@@ -0,0 +1,51 @@
+// The world-sky file: a host star's night sky, worked out once by the backend's catalogue sync and
+// read here without a copy or any star maths. Format 1, little-endian (N stars, L line vertices):
+//
+//   offset        size   type        field
+//   0             4      ASCII       magic "WSKY"
+//   4             2      uint16      format version (1)
+//   6             2      uint16      header size in bytes; stars start here
+//   8             4      uint32      dataset version
+//   12            4      uint32      N, star count
+//   16            4      uint32      L, line-vertex count (even: vertices 2k, 2k+1 are one segment)
+//   20            4      uint32      stand-in count: seeded stars to add for an Earth-like sky
+//   24            8      —           reserved
+//   H             6·N    int16 × 3   star directions (unit vector × 32767), scene frame
+//   H + 6N        4·N    uint8 × 4   star colour (r g b) + apparent brightness (a: mag −1 → 255, 6.5 → 0)
+//   H + 10N       6·L    int16 × 3   constellation line vertices (arcs already split)
+//
+// Scene frame: y toward celestial north; x = cos(dec)·cos(ra), z = −cos(dec)·sin(ra).
+export const WORLD_SKY_MAGIC = 'WSKY';
+export const WORLD_SKY_FORMAT = 1;
+/** Wraps a world-sky file. Throws on anything that is not a complete format-1 file. */
+export function parseWorldSky(buffer) {
+    if (buffer.byteLength < 24)
+        throw new Error('world sky: file too short');
+    const view = new DataView(buffer);
+    const magic = String.fromCharCode(view.getUint8(0), view.getUint8(1), view.getUint8(2), view.getUint8(3));
+    if (magic !== WORLD_SKY_MAGIC)
+        throw new Error('world sky: not a WSKY file');
+    const format = view.getUint16(4, true);
+    if (format !== WORLD_SKY_FORMAT)
+        throw new Error(`world sky: unsupported format ${format}`);
+    const header = view.getUint16(6, true);
+    const datasetVersion = view.getUint32(8, true);
+    const starCount = view.getUint32(12, true);
+    const lineVertices = view.getUint32(16, true);
+    const standIns = view.getUint32(20, true);
+    if (header < 24 || header % 2 !== 0)
+        throw new Error('world sky: bad header size');
+    if (lineVertices % 2 !== 0)
+        throw new Error('world sky: odd line-vertex count');
+    const size = header + 10 * starCount + 6 * lineVertices;
+    if (buffer.byteLength < size)
+        throw new Error('world sky: file truncated');
+    return {
+        datasetVersion,
+        starCount,
+        directions: new Int16Array(buffer, header, 3 * starCount),
+        colourBrightness: new Uint8Array(buffer, header + 6 * starCount, 4 * starCount),
+        lines: new Int16Array(buffer, header + 10 * starCount, 3 * lineVertices),
+        standIns,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "4.2.0",
+  "version": "5.1.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "dist/index.js",
@@ -83,6 +83,10 @@
       "types": "./dist/star/index.d.ts",
       "import": "./dist/star/index.js"
     },
+    "./sky": {
+      "types": "./dist/sky/index.d.ts",
+      "import": "./dist/sky/index.js"
+    },
     "./audio": {
       "types": "./dist/audio/index.d.ts",
       "import": "./dist/audio/index.js"
@@ -154,6 +158,8 @@
     "baseline:release": "tsx scripts/api-baseline.ts release",
     "check:exports": "tsx scripts/check-exports.ts",
     "bench:star:build": "esbuild bench/star/main.ts --bundle --format=esm --target=es2022 --outfile=bench/star/build/main.js --log-level=warning",
-    "bench:star": "npm run bench:star:build && tsx bench/star/run.ts"
+    "bench:star": "npm run bench:star:build && tsx bench/star/run.ts",
+    "bench:sky:build": "esbuild bench/sky/main.ts --bundle --format=esm --target=es2022 --outfile=bench/sky/build/main.js --log-level=warning",
+    "bench:sky": "npm run bench:sky:build && tsx bench/sky/run.ts"
   }
 }

package/src/shortcuts/catalogue.ts

@@ -0,0 +1,172 @@
+// 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.
+
+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 const EMPTY_CATALOGUE: ShortcutCatalogue = Object.freeze({ version: '', sections: Object.freeze([]) })
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && !Array.isArray(value)
+const isString = (value: unknown): value is string => typeof value === 'string' && value.length > 0
+
+function names(value: unknown): ShortcutNames | undefined {
+  if (!isRecord(value)) return undefined
+  const out: Record<string, string> = {}
+  for (const [locale, name] of Object.entries(value)) if (isString(name)) out[locale] = name
+  return Object.freeze(out)
+}
+
+function named(value: unknown): ShortcutNamed | null {
+  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: unknown): ShortcutAction | null {
+  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 = <T>(value: unknown, read: (item: unknown) => T | null): readonly T[] =>
+  Object.freeze(Array.isArray(value) ? value.map(read).filter((item): item is T => item !== null) : [])
+
+function section(value: unknown): ShortcutSection | null {
+  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: unknown): ShortcutCatalogue | null {
+  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: { readonly label: string; readonly names?: ShortcutNames }, locale?: string): string {
+  return item.names?.[(locale ?? '').slice(0, 2).toLowerCase()] ?? item.label
+}
+
+/** A section's app name in a language. */
+export function localAppName(section: Pick<ShortcutSection, 'appLabel' | 'appNames'>, locale?: string): string {
+  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: Pick<ShortcutSection, 'part' | 'partNames'>, locale?: string): string | undefined {
+  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: ShortcutCatalogue): ReadonlyArray<{ id: string; label: string; names?: ShortcutNames }> {
+  const seen = new Map<string, { id: string; label: string; names?: ShortcutNames }>()
+  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<ShortcutCatalogue, Map<string, readonly ShortcutAction[]>>()
+
+/**
+ * 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: ShortcutCatalogue, ...sectionIds: string[]): readonly ShortcutAction[] {
+  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: ShortcutCatalogue, sectionId: string): ShortcutSection | undefined {
+  return catalogue.sections.find((s) => s.id === sectionId)
+}

package/src/shortcuts/chord.ts

@@ -1,7 +1,13 @@
 // One key with its modifiers, written as a string: `Shift+KeyR`, `Mod+KeyZ`, `Shift?+Digit1`.
 //
-// The last part is the key's PLACE (`KeyboardEvent.code`), so a French or German keyboard keeps the
-// same layout: the key, not the letter it prints. Before it, the modifiers:
+// The last part names the key the way a US keyboard does (`KeyboardEvent.code`: `KeyQ`, `Slash`,
+// `Digit1`). A press matches it by the CHARACTER it types wherever it types one, so `/` is the key
+// that prints `/` on this person's keyboard (Shift+7 on a Spanish one), and `KeyQ` is the key that
+// prints Q (top left on a French one). Only where the key types no character the US keyboard has
+// (a Greek or Cyrillic letter, ⌥ on a Mac changing it, a dead key, no letter on a letter key) is the
+// key matched by its place.
+// Digits match by character first, then by place: a French keyboard types `&` there.
+// Before the key, the modifiers:
 //
 //   Shift, Alt, Ctrl, Meta   held. One left out must NOT be held.
 //   Mod                      Ctrl or ⌘ (either, or both), the command key of every platform.
@@ -72,15 +78,99 @@ function parse(keys: string): Chord | null {
 
 const fits = (rule: ModifierRule, down: boolean) => rule === 'any' || (rule === 'held') === Boolean(down)
 
-/** Whether a press of `code` with these modifiers is this chord. */
-export function chordMatches(chord: Chord, code: string, state: ModifierState): boolean {
-  if (chord.code !== code) return false
-  if (!fits(chord.shift, state.shiftKey) || !fits(chord.alt, state.altKey)) return false
+/** A press as a chord reads it: the modifiers, the key's place and, when the browser says, the character it typed. */
+export interface ChordPress extends ModifierState {
+  readonly code: string
+  readonly key?: string
+}
+
+/**
+ * The punctuation keys a chord may name, and what a US keyboard types there without and with Shift:
+ * what the chord means on every keyboard. With these, Shift is part of the character (`?` is
+ * `Shift+Slash`), so a keyboard that needs Shift, or AltGr, for a `/` still types the `/`.
+ */
+const PUNCTUATION: Readonly<Record<string, readonly [string, string]>> = {
+  Minus: ['-', '_'], Equal: ['=', '+'], BracketLeft: ['[', '{'], BracketRight: [']', '}'], Backslash: ['\\', '|'],
+  Semicolon: [';', ':'], Quote: ["'", '"'], Backquote: ['`', '~'], Comma: [',', '<'], Period: ['.', '>'], Slash: ['/', '?'],
+}
+
+/** The code a US keyboard types each punctuation character at, and whether it takes Shift. */
+const PUNCTUATION_PLACE = new Map<string, readonly [code: string, shift: boolean]>(
+  Object.entries(PUNCTUATION).flatMap(([code, [plain, shifted]]): Array<[string, readonly [string, boolean]]> => [[plain, [code, false]], [shifted, [code, true]]]),
+)
+
+/** The character a press typed, when it is one a US keyboard has (printable ASCII); else `null`. */
+function typed(key: string | undefined): string | null {
+  return typeof key === 'string' && key.length === 1 && key >= '!' && key <= '~' ? key : null
+}
+
+/** How a press is this chord: by the character it typed, by the key's place, or not at all. */
+export type ChordMatch = 'character' | 'place' | null
+
+function commandFits(chord: Chord, state: ModifierState): boolean {
   if (chord.mod === 'held') return Boolean(state.ctrlKey || state.metaKey)
   if (chord.mod === 'any') return true
   return fits(chord.ctrl, state.ctrlKey) && fits(chord.meta, state.metaKey)
 }
 
+function placeMatch(chord: Chord, code: string, state: ModifierState): boolean {
+  return chord.code === code && fits(chord.shift, state.shiftKey) && fits(chord.alt, state.altKey) && commandFits(chord, state)
+}
+
+/**
+ * How a press is this chord. `character` beats `place`: on a Spanish keyboard Shift+7 types `/`, so it
+ * is the `/` key before it is the `7` key. A press with no `key` (an old caller) matches by place only.
+ */
+export function chordMatch(chord: Chord, press: ChordPress): ChordMatch {
+  const char = typed(press.key)
+  if (char === null) return placeMatch(chord, press.code, press) ? 'place' : null
+  const punctuation = PUNCTUATION[chord.code]
+  if (punctuation) {
+    // Shift is in the character (a Spanish `/` is Shift+7); with ⌘ some browsers report the key
+    // unshifted, so `⇧⌘,` is also a `,` with Shift held. Alt only when the chord asks for it (AltGr
+    // and ⌥ type characters).
+    const [plain, shifted] = punctuation
+    const asShifted = char === shifted || (isCommandChord(chord) && char === plain && press.shiftKey)
+    const ok = chord.shift === 'held' ? asShifted : chord.shift === 'any' ? char === plain || asShifted : char === plain
+    // A command (⇧⌘,) where this keyboard types another character there: the key's place, as menus do.
+    if (!ok) return isCommandChord(chord) && placeMatch(chord, press.code, press) ? 'place' : null
+    if (chord.alt === 'held' && !press.altKey) return null
+    // AltGr arrives as Ctrl+Alt on Windows: that Ctrl typed the character, it is no command.
+    const altGr = press.altKey && press.ctrlKey && !press.metaKey
+    return commandFits(chord, { ctrlKey: press.ctrlKey && !altGr, metaKey: press.metaKey, shiftKey: press.shiftKey, altKey: press.altKey }) ? 'character' : null
+  }
+  const letter = /^Key([A-Z])$/.exec(chord.code)?.[1]
+  if (letter) {
+    // A key that types no letter (`;` where Q is on a Greek keyboard) is read by its place.
+    if (!/^[a-zA-Z]$/.test(char)) return placeMatch(chord, press.code, press) ? 'place' : null
+    if (char.toUpperCase() !== letter) return null
+    return fits(chord.shift, press.shiftKey) && fits(chord.alt, press.altKey) && commandFits(chord, press) ? 'character' : null
+  }
+  const digit = /^Digit(\d)$/.exec(chord.code)?.[1]
+  // A digit typed; where the keyboard types something else there (`&` on a French one), its place.
+  if (digit && char === digit && fits(chord.shift, press.shiftKey) && fits(chord.alt, press.altKey) && commandFits(chord, press)) return 'character'
+  return placeMatch(chord, press.code, press) ? 'place' : null
+}
+
+/** Whether a press of `code` with these modifiers (and, when given, the character it typed) is this chord. */
+export function chordMatches(chord: Chord, code: string, state: ModifierState & { readonly key?: string }): boolean {
+  // Field by field: a browser's KeyboardEvent keeps them on its prototype, where a spread does not reach.
+  const { shiftKey, altKey, ctrlKey, metaKey, key } = state
+  return chordMatch(chord, { code, key, shiftKey, altKey, ctrlKey, metaKey }) !== null
+}
+
+/**
+ * The key string a typed character names (`/` → `Slash`, `?` → `Shift+Slash`, `q` → `KeyQ`), for
+ * someone setting a key; `null` for a character a US keyboard does not have, or none.
+ */
+export function typedKey(key: string | undefined): { readonly code: string; readonly shift?: boolean } | null {
+  const char = typed(key)
+  if (char === null) return null
+  if (/^[a-zA-Z]$/.test(char)) return { code: `Key${char.toUpperCase()}` }
+  const place = PUNCTUATION_PLACE.get(char)
+  return place ? { code: place[0], shift: place[1] } : null
+}
+
 /** A chord that needs Ctrl or ⌘: a command, never a character typed. */
 export function isCommandChord(chord: Chord): boolean {
   return chord.mod === 'held' || chord.ctrl === 'held' || chord.meta === 'held'