@diffenderfer-games/hub 0.0.0-stage → 2.0.0-next.1

package/src/input/page-input.ts

@@ -0,0 +1,193 @@
+/**
+ * The page's one input system (plan §4.4). The game's copy of the client owns
+ * the page because the game defines the controls; the host menu reaches it
+ * through the stable {@link PageInputControl} slice. Remaps persist to
+ * localStorage (offline-safe) and, through the core client, to a reserved
+ * cloud save slot.
+ */
+import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
+import { claimSingleton, LEGACY_GLOBAL_NAMES } from '../globals';
+import { hasMethods, isObject, readField } from '../realtime/cross-bundle';
+import { InputSystem } from './input-system';
+import { isPageInputControl } from './page-control';
+import type { PageInputControl } from './page-control';
+import type { InputDef, InputHost, InputOverrides, VirtualOverride } from './types';
+
+/** The cross-bundle shape number of the `input` singleton. Bump only on an incompatible change. */
+export const INPUT_SINGLETON_API = 1;
+
+/** The public methods of every input system, v1 copies included. */
+const INPUT_SYSTEM_METHODS = [
+  'define', 'enable', 'disable', 'isEnabled', 'value', 'get', 'down', 'up', 'pressed', 'axis', 'vector', 'on',
+  'setVirtualHtml', 'showVirtual', 'setInsets', 'autoNavigate', 'clearAutoNavigate', 'attachMenu', 'setLegacyControls',
+  'openControls', 'rebind', 'setVirtual',
+] as const;
+
+/** Whether `candidate` is some bundle's input system (v1 copies included). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
+export function isInputSystem(candidate: unknown): candidate is InputSystem {
+  return hasMethods(candidate, INPUT_SYSTEM_METHODS);
+}
+
+/** How the core client connects the input system to its game. */
+export interface InputOptions {
+  /** This page's game slug (default: `window.__HUB__.slug`). */
+  slug?: string | null;
+  /** Mirror remaps to the cloud (the core client writes the `__controls` save slot). */
+  saveToCloud?: (overrides: InputOverrides) => void;
+}
+
+/** A finite number, or `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
+function finiteNumber(candidate: unknown): number | undefined {
+  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
+}
+
+/** A saved rebind: the keys or gamepad button the player chose. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
+function parseBinding(saved: unknown): Partial<InputDef> {
+  const binding: Partial<InputDef> = {};
+  const keys = readField(saved, 'keys');
+  if (Array.isArray(keys) && keys.every((key) => typeof key === 'string')) {
+    binding.keys = keys.filter((key): key is string => typeof key === 'string');
+  }
+  const button = finiteNumber(readField(readField(saved, 'gamepad'), 'button'));
+  if (button !== undefined) {
+    binding.gamepad = { button };
+  }
+  return binding;
+}
+
+/** A saved dragged spot. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
+function parseVirtualOverride(saved: unknown): VirtualOverride {
+  const spot: VirtualOverride = {};
+  const left = finiteNumber(readField(saved, 'x'));
+  const top = finiteNumber(readField(saved, 'y'));
+  if (left !== undefined) {
+    spot.x = left;
+  }
+  if (top !== undefined) {
+    spot.y = top;
+  }
+  return spot;
+}
+
+/** Entries of a saved record, parsed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: saved JSON
+function parseRecord<Parsed>(saved: unknown, parseEntry: (entry: unknown) => Parsed): Record<string, Parsed> | undefined {
+  if (!isObject(saved)) {
+    return undefined;
+  }
+  return Object.fromEntries(Object.entries(saved).map(([key, entry]) => [key, parseEntry(entry)]));
+}
+
+/** Saved overrides from JSON, keeping only well-formed fields. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON read back from localStorage
+export function parseInputOverrides(saved: unknown): InputOverrides {
+  const overrides: InputOverrides = {};
+  const bindings = parseRecord(readField(saved, 'bindings'), parseBinding);
+  const virtual = parseRecord(readField(saved, 'virtual'), parseVirtualOverride);
+  const showVirtual = readField(saved, 'showVirtual');
+  if (bindings !== undefined) {
+    overrides.bindings = bindings;
+  }
+  if (virtual !== undefined) {
+    overrides.virtual = virtual;
+  }
+  if (typeof showVirtual === 'boolean') {
+    overrides.showVirtual = showVirtual;
+  }
+  return overrides;
+}
+
+/** A field of the host's injected `window.__HUB__`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the host page's injected config, checked by the caller
+function injectedField(key: string): unknown {
+  return typeof window === 'undefined' ? undefined : readField(readField(window, '__HUB__'), key);
+}
+
+/** The slug the host injected, or `null`. */
+function injectedSlug(): string | null {
+  const slug = injectedField('slug');
+  return typeof slug === 'string' ? slug : null;
+}
+
+/** A new input system, starting from the host's injected `game.controls` (the menu may pass them again later). */
+function createInputSystem(options: InputOptions, isPageOwner: boolean): InputSystem {
+  const system = new InputSystem(createInputHost(options), { isPageOwner, claimPage: registerAsPageInput });
+  system.setLegacyControls(injectedField('controls') ?? null);
+  return system;
+}
+
+/** Persistence for remaps: localStorage under `hub:<slug>:input`, mirrored to the cloud when given. */
+function createInputHost(options: InputOptions): InputHost {
+  const slug = options.slug === undefined ? injectedSlug() : options.slug;
+  const storageKey = `hub:${slug ?? 'null'}:input`;
+  return {
+    slug,
+    loadOverrides() {
+      try {
+        const saved = localStorage.getItem(storageKey);
+        if (saved === null) {
+          return null;
+        }
+        // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON from localStorage, parsed straight away
+        const parsed: unknown = JSON.parse(saved);
+        return parseInputOverrides(parsed);
+      } catch {
+        return null;
+      }
+    },
+    saveOverrides(overrides) {
+      try {
+        localStorage.setItem(storageKey, JSON.stringify(overrides));
+      } catch {
+        // Storage full or blocked: the cloud copy still saves.
+      }
+      if (slug !== null) {
+        options.saveToCloud?.(overrides);
+      }
+    },
+  };
+}
+
+/** Make `system` the page's registered input system; returns the one it replaces. */
+function registerAsPageInput(system: InputSystem): PageInputControl | null {
+  const registry = window.__DG__ ?? {};
+  window.__DG__ = registry;
+  const previous = registry.input?.instance ?? window[LEGACY_GLOBAL_NAMES.input];
+  registry.input = { version: HUB_CLIENT_VERSION, api: INPUT_SINGLETON_API, instance: system };
+  window[LEGACY_GLOBAL_NAMES.input] = system;
+  return previous !== system && isPageInputControl(previous) ? previous : null;
+}
+
+/** Whether another bundle registered an input system with a different shape number. */
+function hasMismatchedPageInput(): boolean {
+  const registered = typeof window === 'undefined' ? undefined : window.__DG__?.input;
+  return registered !== undefined && registered.api !== INPUT_SINGLETON_API && isInputSystem(registered.instance);
+}
+
+let claimedInput: InputSystem | null = null;
+
+/**
+ * The page-wide input system, created on first use. `options` connect it to
+ * the core client (its slug, the cloud save); the first call's options win.
+ * When another client copy with a different shape owns the page, this copy
+ * gets a private instance that takes the page over once its game defines
+ * inputs.
+ */
+export function getInput(options: InputOptions = {}): InputSystem {
+  if (claimedInput !== null) {
+    return claimedInput;
+  }
+  const isPrivate = hasMismatchedPageInput();
+  claimedInput = claimSingleton({
+    name: 'input',
+    version: HUB_CLIENT_VERSION,
+    api: INPUT_SINGLETON_API,
+    create: () => createInputSystem(options, !isPrivate),
+    isInstance: isInputSystem,
+  });
+  return claimedInput;
+}

package/src/input/player-remaps.ts

@@ -0,0 +1,77 @@
+/**
+ * The player's remaps and on-screen control customisations for one game,
+ * persisted through the input host after every change.
+ */
+import type { InputDef, InputHost, InputOverrides, VirtualOverride } from './types';
+
+/** A readable label of an input's binding (`w/ArrowUp · Pad 0`). */
+export function describeBinding(definition: InputDef | undefined): string {
+  const parts: string[] = [];
+  if (definition?.keys !== undefined && definition.keys.length > 0) {
+    parts.push(definition.keys.join('/'));
+  }
+  if (definition?.gamepad?.button !== undefined) {
+    parts.push(`Pad ${String(definition.gamepad.button)}`);
+  }
+  if (definition?.gamepad?.axis !== undefined) {
+    parts.push(`Axis ${String(definition.gamepad.axis[0])}${definition.gamepad.axis[1]}`);
+  }
+  return parts.length > 0 ? parts.join(' · ') : '—';
+}
+
+/** The player's overrides, saved on every change. */
+export class PlayerRemaps {
+  private readonly host: InputHost;
+  private saved: InputOverrides;
+
+  constructor(host: InputHost) {
+    this.host = host;
+    this.saved = host.loadOverrides() ?? {};
+  }
+
+  /** The overrides as they stand. */
+  get overrides(): InputOverrides {
+    return this.saved;
+  }
+
+  /** A declared input with the player's rebind applied. */
+  withBinding(name: string, declared: InputDef): InputDef {
+    return { ...declared, ...this.saved.bindings?.[name] };
+  }
+
+  /** Rebind an input. */
+  rebind(inputName: string, patch: Partial<InputDef>): void {
+    const bindings = this.saved.bindings ?? {};
+    bindings[inputName] = { ...bindings[inputName], ...patch };
+    this.saved.bindings = bindings;
+    this.persist();
+  }
+
+  /** Move or restyle an on-screen control. */
+  customiseControl(id: string, patch: VirtualOverride): void {
+    const virtual = this.saved.virtual ?? {};
+    virtual[id] = { ...virtual[id], ...patch };
+    this.saved.virtual = virtual;
+    this.persist();
+  }
+
+  /** Record the player's show/hide choice. */
+  setShowVirtual(isVisible: boolean): void {
+    this.saved.showVirtual = isVisible;
+    this.persist();
+  }
+
+  /** Forget everything. */
+  reset(): void {
+    this.saved = {};
+    this.persist();
+  }
+
+  private persist(): void {
+    try {
+      this.host.saveOverrides(this.saved);
+    } catch {
+      // Storage can be full or blocked; remaps still apply for this visit.
+    }
+  }
+}

package/src/input/source-values.ts

@@ -0,0 +1,116 @@
+/**
+ * An input's raw 0..1 value from the device state: the strongest of its
+ * sources. Keyboard and touch always count; mouse and gamepad only while
+ * they are the active pointer.
+ */
+import type { DeviceState } from './device-state';
+import { AXIS_DEADZONE } from './gamepad';
+import type { AxisSide, GamepadMapping, InputDef, InputSource, MouseMapping, TouchMapping } from './types';
+
+/** Clamp to 0..1. */
+export function clampUnit(amount: number): number {
+  return Math.min(1, Math.max(0, amount));
+}
+
+/** The pointer's position from screen centre on an axis, as 0..1 on one side. */
+function centreValue(state: DeviceState, axis: 'x' | 'y', side: AxisSide | undefined): number {
+  const fraction = axis === 'x' ? state.pointerX / window.innerWidth : state.pointerY / window.innerHeight;
+  const signed = (fraction - 0.5) * 2;
+  return clampUnit(side === '-' ? -signed : signed);
+}
+
+/** A signed amount read on one side. */
+function onSide(amount: number, side: AxisSide | undefined): number {
+  return side === '-' ? -amount : amount;
+}
+
+function mouseValue(state: DeviceState, mapping: MouseMapping): number {
+  let strongest = 0;
+  if (mapping.button !== undefined && state.heldMouseButtons.has(mapping.button)) {
+    strongest = 1;
+  }
+  if (mapping.dblclick === true && state.isPulseActive('mouse:dbl')) {
+    strongest = 1;
+  }
+  if (mapping.centerAxis !== undefined) {
+    strongest = Math.max(strongest, centreValue(state, mapping.centerAxis, mapping.centerSide));
+  }
+  if (mapping.moveAxis !== undefined) {
+    const moved = mapping.moveAxis === 'x' ? state.movement.dx : state.movement.dy;
+    strongest = Math.max(strongest, clampUnit(onSide(moved, mapping.moveSign) * (mapping.moveScale ?? 0.1)));
+  }
+  if (mapping.wheel !== undefined) {
+    strongest = Math.max(strongest, clampUnit(onSide(state.wheel.dy, mapping.wheel)));
+  }
+  return strongest;
+}
+
+function gamepadValue(state: DeviceState, mapping: GamepadMapping): number {
+  let strongest = 0;
+  for (const pad of state.gamepads) {
+    if (mapping.button !== undefined) {
+      const button = pad.buttons[mapping.button];
+      if (button !== undefined) {
+        strongest = Math.max(strongest, button.value > 0 ? button.value : Number(button.pressed));
+      }
+    }
+    if (mapping.axis !== undefined) {
+      const [axisIndex, half] = mapping.axis;
+      const deflection = pad.axes[axisIndex] ?? 0;
+      const reading = half === '±' ? Math.abs(deflection) : Math.max(0, half === '+' ? deflection : -deflection);
+      if (Math.abs(deflection) > AXIS_DEADZONE) {
+        strongest = Math.max(strongest, clampUnit(reading));
+      }
+    }
+  }
+  return strongest;
+}
+
+function stickValue(state: DeviceState, mapping: TouchMapping): number {
+  const stick = mapping.stick === undefined ? undefined : state.sticks.get(mapping.stick);
+  if (stick === undefined) {
+    return 0;
+  }
+  const readings: Record<NonNullable<TouchMapping['axis']>, number> = {
+    'x+': Math.max(0, stick.outX),
+    'x-': Math.max(0, -stick.outX),
+    'y+': Math.max(0, stick.outY),
+    'y-': Math.max(0, -stick.outY),
+    x: Math.abs(stick.outX),
+    y: Math.abs(stick.outY),
+  };
+  return mapping.axis === undefined ? 0 : readings[mapping.axis];
+}
+
+function touchValue(state: DeviceState, mapping: TouchMapping): number {
+  let strongest = clampUnit(stickValue(state, mapping));
+  if (mapping.button !== undefined && state.pressedVirtualButtons.has(mapping.button)) {
+    strongest = 1;
+  }
+  if (mapping.tap === true && state.isPulseActive('tap')) {
+    strongest = 1;
+  }
+  if (mapping.centerAxis !== undefined) {
+    // The last touch position (touch moves the pointer too).
+    strongest = Math.max(strongest, centreValue(state, mapping.centerAxis, mapping.centerSide));
+  }
+  return strongest;
+}
+
+/** An input's raw value now, given the active pointer. */
+export function readRawValue(state: DeviceState, definition: InputDef, activeSource: InputSource): number {
+  let strongest = 0;
+  if (definition.keys?.some((key) => state.heldKeys.has(key.toLowerCase())) === true) {
+    strongest = 1;
+  }
+  if (definition.mouse !== undefined && activeSource === 'mouse') {
+    strongest = Math.max(strongest, mouseValue(state, definition.mouse));
+  }
+  if (definition.gamepad !== undefined && activeSource === 'gamepad') {
+    strongest = Math.max(strongest, gamepadValue(state, definition.gamepad));
+  }
+  if (definition.touch !== undefined) {
+    strongest = Math.max(strongest, touchValue(state, definition.touch));
+  }
+  return clampUnit(strongest);
+}

package/src/input/spatial.ts

@@ -0,0 +1,47 @@
+/**
+ * Spatial navigation: from one rectangle, the nearest one strictly in a
+ * direction. Shared by navigable groups, the hub menu, the catalog launcher
+ * and the on-screen keyboard.
+ */
+import type { Direction } from './gamepad';
+import type { Rect } from './types';
+
+/** Centres closer than this on the travel axis don't count as "in that direction". */
+const MIN_TRAVEL_PX = 4;
+
+/** The rectangle of a DOM element. */
+export function rectOf(element: Element): Rect {
+  const bounds = element.getBoundingClientRect();
+  return { x: bounds.left, y: bounds.top, width: bounds.width, height: bounds.height };
+}
+
+/** Index of the rectangle nearest `rects[fromIndex]` strictly in `direction`, or -1. Off-axis distance counts double. */
+export function findNearestInDirection(rects: readonly Rect[], fromIndex: number, direction: Direction): number {
+  const from = rects[fromIndex];
+  if (from === undefined) {
+    return -1;
+  }
+  const fromCentreX = from.x + from.width / 2;
+  const fromCentreY = from.y + from.height / 2;
+  const isVertical = direction === 'up' || direction === 'down';
+  let bestIndex = -1;
+  let bestScore = Infinity;
+  rects.forEach((rect, index) => {
+    if (index === fromIndex) {
+      return;
+    }
+    const dx = rect.x + rect.width / 2 - fromCentreX;
+    const dy = rect.y + rect.height / 2 - fromCentreY;
+    const travel = { up: -dy, down: dy, left: -dx, right: dx }[direction];
+    if (travel <= MIN_TRAVEL_PX) {
+      return;
+    }
+    const across = isVertical ? Math.abs(dx) : Math.abs(dy);
+    const score = travel + across * 2;
+    if (score < bestScore) {
+      bestScore = score;
+      bestIndex = index;
+    }
+  });
+  return bestIndex;
+}