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

package/src/overlay/layout.ts

@@ -0,0 +1,203 @@
+/**
+ * The automatic layout of the on-screen touch controls (pure: no DOM). It is
+ * width-aware and collision-free, and keeps player-dragged spots across
+ * resizes.
+ */
+import type { Anchor, VirtualDef } from '../input/types';
+import { clusterBesideSticks, rowsBeyondSticks } from './layout-clusters';
+import type { ClusterContext, StickSpan } from './layout-clusters';
+import { anchorSides, boxesTouch, clampBetween, clampBox, isInside, isStickType, nearestFreeBox, unionBox } from './layout-geometry';
+import type { Area, Insets, LayoutBox, LayoutItem } from './layout-geometry';
+
+export type { LayoutItem } from './layout-geometry';
+
+/** Layout options. */
+export interface LayoutOptions {
+  /** Game insets (a HUD bar…): auto-placed controls keep clear of them. */
+  insets?: Partial<Insets>;
+  /** Device safe area (notch, home bar): every control stays inside it. */
+  safe?: Partial<Insets>;
+  /** Distance from the edges for auto-placed controls (default 22). */
+  margin?: number;
+  /** Space between auto-placed controls (default 14). */
+  gap?: number;
+}
+
+/** Controls that aren't sticks must not touch each other (px). */
+const TOUCH_PADDING = 6;
+const NO_INSETS: Insets = { top: 0, right: 0, bottom: 0, left: 0 };
+
+/** The placement state of one layout run. */
+class LayoutPass {
+  readonly boxes: Record<string, LayoutBox> = {};
+  /** Obstacles (tap regions don't count). */
+  private readonly placed: LayoutBox[] = [];
+  private readonly stickBoxes = new Set<LayoutBox>();
+  private readonly gap: number;
+
+  constructor(gap: number) {
+    this.gap = gap;
+  }
+
+  commit(item: LayoutItem, box: LayoutBox): void {
+    this.boxes[item.id] = box;
+    if (item.type === 'tap') {
+      return;
+    }
+    this.placed.push(box);
+    if (isStickType(item.type)) {
+      this.stickBoxes.add(box);
+    }
+  }
+
+  /**
+   * Whether `box` is clear of `others`. A stick's whole box is its touch
+   * area, so everything keeps a full gap from it (a thumb on the rim must not
+   * catch a button); other controls just must not touch.
+   */
+  isFree(box: LayoutBox, others: readonly LayoutBox[] = this.placed): boolean {
+    return !others.some((other) => boxesTouch(box, other, this.stickBoxes.has(other) ? this.gap : TOUCH_PADDING));
+  }
+}
+
+/**
+ * Place every control for a `viewportWidth` × `viewportHeight` viewport and
+ * return each control's box.
+ *
+ * 1. A game `pos` is honoured as given. A player-dragged control keeps its
+ *    spot (as % of the viewport, re-clamped inside the safe area), nudged to
+ *    the nearest free spot if it would land on (or within `gap` of) a stick.
+ * 2. Sticks sit in their anchor's corner, side by side inward.
+ * 3. Buttons cluster beside their corner's sticks, stacked in columns. If any
+ *    cluster doesn't fit, every corner cluster that has sticks moves into rows
+ *    above (below, for top corners) its sticks, first-declared button
+ *    innermost. Any button that still collides moves to the nearest free spot.
+ */
+export function layoutControls(items: readonly LayoutItem[], viewportWidth: number, viewportHeight: number, options: LayoutOptions = {}): Record<string, LayoutBox> {
+  const margin = options.margin ?? 22;
+  const gap = options.gap ?? 14;
+  const safe: Insets = { ...NO_INSETS, ...options.safe };
+  const insets: Insets = { ...NO_INSETS, ...options.insets };
+  const area: Area = {
+    left: safe.left + insets.left + margin,
+    top: safe.top + insets.top + margin,
+    right: viewportWidth - safe.right - insets.right - margin,
+    bottom: viewportHeight - safe.bottom - insets.bottom - margin,
+  };
+  const safeArea: Area = { left: safe.left, top: safe.top, right: viewportWidth - safe.right, bottom: viewportHeight - safe.bottom };
+  const context: ClusterContext = { area, gap, viewportWidth, viewportHeight };
+  const pass = new LayoutPass(gap);
+
+  // 1. Fixed spots. Player-dragged ones wait until the sticks are down.
+  const autoItems: LayoutItem[] = [];
+  const dragged: Array<{ item: LayoutItem; wanted: LayoutBox }> = [];
+  for (const item of items) {
+    if (item.override !== undefined) {
+      dragged.push({ item, wanted: {
+        x: clampBetween((item.override.x / 100) * viewportWidth, safe.left, viewportWidth - safe.right - item.w),
+        y: clampBetween((item.override.y / 100) * viewportHeight, safe.top, viewportHeight - safe.bottom - item.h),
+        w: item.w,
+        h: item.h,
+      } });
+    } else if (item.pos !== undefined) {
+      pass.commit(item, pinnedBox(item, item.pos, context));
+    } else {
+      autoItems.push(item);
+    }
+  }
+
+  const byAnchor = new Map<Anchor, LayoutItem[]>();
+  for (const item of autoItems) {
+    const list = byAnchor.get(item.place) ?? [];
+    list.push(item);
+    byAnchor.set(item.place, list);
+  }
+
+  // 2. Sticks in their corner, side by side inward.
+  const sticksByAnchor = new Map<Anchor, StickSpan>();
+  for (const [anchor, list] of byAnchor) {
+    sticksByAnchor.set(anchor, placeSticks(list, anchor, context, pass));
+  }
+  // A dragged control keeps its spot unless that now lands on a stick or a fixed control.
+  for (const { item, wanted } of dragged) {
+    const isClear = item.type === 'tap' || pass.isFree(wanted);
+    pass.commit(item, isClear ? wanted : nearestFreeBox(wanted, safeArea, (box) => pass.isFree(box)) ?? wanted);
+  }
+
+  // 3a. The classic cluster for every anchor's buttons.
+  const classic = new Map<string, LayoutBox>();
+  for (const [anchor, list] of byAnchor) {
+    const buttons = list.filter((item) => !isStickType(item.type));
+    if (buttons.length > 0) {
+      clusterBesideSticks(buttons, anchorSides(anchor), sticksByAnchor.get(anchor) ?? EMPTY_SPAN, context, classic);
+    }
+  }
+  // Does every cluster fit (inside the area, clear of sticks, fixed controls and the other buttons)?
+  const solidButtons = autoItems.filter((item) => !isStickType(item.type) && item.type !== 'tap');
+  const classicBoxes = solidButtons.flatMap((item) => classic.get(item.id) ?? []);
+  const isCompact = classicBoxes.some((box) => !isInside(box, area) || !pass.isFree(box) || !pass.isFree(box, classicBoxes.filter((other) => other !== box)));
+
+  // 3b. Commit: classic spots, or rows over the sticks in compact mode. Taps keep their spot (they're meant to overlap).
+  const lost: Array<{ item: LayoutItem; wanted: LayoutBox }> = [];
+  for (const [anchor, list] of byAnchor) {
+    const buttons = list.filter((item) => !isStickType(item.type));
+    const sides = anchorSides(anchor);
+    const span = sticksByAnchor.get(anchor)?.span ?? null;
+    const rows = isCompact && span !== null && sides.horizontal !== 'mid' && sides.vertical !== 'mid'
+      ? rowsBeyondSticks(buttons.filter((item) => item.type !== 'tap'), sides, span, context)
+      : null;
+    for (const item of buttons) {
+      const wanted = rows?.get(item.id) ?? classic.get(item.id);
+      if (wanted === undefined) {
+        continue;
+      }
+      if (item.type === 'tap' || (isInside(wanted, area) && pass.isFree(wanted))) {
+        pass.commit(item, wanted);
+      } else {
+        lost.push({ item, wanted });
+      }
+    }
+  }
+  // 3c. Anything still colliding goes to the nearest free spot.
+  for (const { item, wanted } of lost) {
+    pass.commit(item, nearestFreeBox(wanted, area, (box) => pass.isFree(box)) ?? clampBox(wanted, area));
+  }
+  return pass.boxes;
+}
+
+const EMPTY_SPAN: StickSpan = { span: null, reserve: 0 };
+
+/** A control pinned by `pos` (anchor sides fill in a missing axis). */
+function pinnedBox(item: LayoutItem, pos: NonNullable<VirtualDef['pos']>, context: ClusterContext): LayoutBox {
+  const { area, viewportWidth, viewportHeight } = context;
+  const sides = anchorSides(item.place);
+  const anchoredLeft = sides.horizontal === 'left' ? area.left : sides.horizontal === 'right' ? area.right - item.w : (viewportWidth - item.w) / 2;
+  const anchoredTop = sides.vertical === 'top' ? area.top : sides.vertical === 'bottom' ? area.bottom - item.h : (viewportHeight - item.h) / 2;
+  const left = pos.left ?? (pos.right === undefined ? anchoredLeft : viewportWidth - pos.right - item.w);
+  const top = pos.top ?? (pos.bottom === undefined ? anchoredTop : viewportHeight - pos.bottom - item.h);
+  return { x: clampBetween(left, 0, viewportWidth - item.w), y: clampBetween(top, 0, viewportHeight - item.h), w: item.w, h: item.h };
+}
+
+/** Place an anchor's sticks side by side from its corner; returns their span and the width they reserve. */
+function placeSticks(list: readonly LayoutItem[], anchor: Anchor, context: ClusterContext, pass: LayoutPass): StickSpan {
+  const { area, gap, viewportWidth, viewportHeight } = context;
+  const sides = anchorSides(anchor);
+  let reserve = 0;
+  let span: LayoutBox | null = null;
+  for (const item of list) {
+    if (!isStickType(item.type)) {
+      continue;
+    }
+    const nudgeX = item.offset?.x ?? 0;
+    const nudgeY = item.offset?.y ?? 0;
+    const left = sides.horizontal === 'left' ? area.left + reserve + nudgeX
+      : sides.horizontal === 'right' ? area.right - reserve - item.w - nudgeX : (viewportWidth - item.w) / 2 + nudgeX;
+    const top = sides.vertical === 'top' ? area.top + nudgeY
+      : sides.vertical === 'bottom' ? area.bottom - item.h - nudgeY : (viewportHeight - item.h) / 2 + nudgeY;
+    const box = { x: left, y: top, w: item.w, h: item.h };
+    pass.commit(item, box);
+    span = span === null ? { ...box } : unionBox(span, box);
+    reserve += item.w + gap;
+  }
+  return { span, reserve };
+}

package/src/overlay/listener-scope.ts

@@ -0,0 +1,23 @@
+/**
+ * A group of window listeners removed together, so rebuilding the on-screen
+ * controls doesn't leave window listeners behind for removed elements.
+ * (Listeners on the controls themselves go away with the elements.)
+ */
+export class ListenerScope {
+  private readonly removers: Array<() => void> = [];
+
+  /** Listen on `window` until {@link ListenerScope.dispose}. */
+  listenWindow<Name extends keyof WindowEventMap>(type: Name, listener: (event: WindowEventMap[Name]) => void, options?: AddEventListenerOptions): void {
+    window.addEventListener(type, listener, options);
+    this.removers.push(() => {
+      window.removeEventListener(type, listener);
+    });
+  }
+
+  /** Remove every listener added through this scope. */
+  dispose(): void {
+    for (const remove of this.removers.splice(0)) {
+      remove();
+    }
+  }
+}

package/src/overlay/on-screen-keyboard.ts

@@ -0,0 +1,137 @@
+/**
+ * The on-screen keyboard for text fields, usable by touch, mouse or gamepad
+ * (the stick or d-pad moves between keys, A presses, B or Start closes).
+ */
+import { RepeatingEdges, RisingEdges } from '../input/edges';
+import { isAnyPadButtonPressed, PAD_BUTTON, readGamepads } from '../input/gamepad';
+import type { Direction } from '../input/gamepad';
+import { findNearestInDirection, rectOf } from '../input/spatial';
+import { findElements } from './dom';
+
+const LETTER_ROWS = ['1234567890', 'qwertyuiop', 'asdfghjkl', 'zxcvbnm'];
+const STICK_THRESHOLD = 0.5;
+
+/** One key's markup. */
+function keyHtml(label: string, key: string, extraClass = ''): string {
+  return `<button class="k ${extraClass}" data-k="${key}">${label}</button>`;
+}
+
+const KEYBOARD_HTML = `<div class="kb-rows">${LETTER_ROWS.map((row) => `<div class="kb-row">${Array.from(row).map((character) => keyHtml(character, character)).join('')}</div>`).join('')}`
+  + `<div class="kb-row">${keyHtml('⇧', 'shift', 'wide')}${keyHtml('space', ' ', 'space')}${keyHtml('⌫', 'back', 'wide')}${keyHtml('↵', 'enter', 'wide')}${keyHtml('✕', 'close', 'wide')}</div></div>`;
+
+/** The direction the pads point, from the summed stick and d-pad. */
+function heldDirection(pads: readonly Gamepad[]): Direction | null {
+  let horizontal = 0;
+  let vertical = 0;
+  for (const pad of pads) {
+    horizontal += (pad.axes[0] ?? 0) - Number(pad.buttons[PAD_BUTTON.LEFT]?.pressed === true) + Number(pad.buttons[PAD_BUTTON.RIGHT]?.pressed === true);
+    vertical += (pad.axes[1] ?? 0) - Number(pad.buttons[PAD_BUTTON.UP]?.pressed === true) + Number(pad.buttons[PAD_BUTTON.DOWN]?.pressed === true);
+  }
+  if (Math.abs(horizontal) <= STICK_THRESHOLD && Math.abs(vertical) <= STICK_THRESHOLD) {
+    return null;
+  }
+  if (Math.abs(horizontal) > Math.abs(vertical)) {
+    return horizontal > 0 ? 'right' : 'left';
+  }
+  return vertical > 0 ? 'down' : 'up';
+}
+
+/** The on-screen keyboard (one at a time, inside the overlay's shadow root). */
+export class OnScreenKeyboard {
+  private readonly root: ShadowRoot;
+  private panel: HTMLDivElement | null = null;
+  private target: HTMLInputElement | HTMLTextAreaElement | null = null;
+  private keys: HTMLElement[] = [];
+  private focusedIndex = 0;
+  private isShifted = false;
+  private readonly repeats = new RepeatingEdges();
+  private readonly presses = new RisingEdges();
+
+  constructor(root: ShadowRoot) {
+    this.root = root;
+  }
+
+  /** Whether the keyboard is showing. */
+  get isOpen(): boolean {
+    return this.panel !== null;
+  }
+
+  /** Open it for `target` (replacing any open keyboard). */
+  open(target: HTMLInputElement | HTMLTextAreaElement | null): void {
+    this.close();
+    this.target = target;
+    this.isShifted = false;
+    this.focusedIndex = 0;
+    const panel = document.createElement('div');
+    panel.className = 'kb';
+    panel.innerHTML = KEYBOARD_HTML;
+    this.root.appendChild(panel);
+    this.panel = panel;
+    this.keys = findElements(panel, '.k', HTMLElement);
+    for (const key of this.keys) {
+      const press = (event: Event): void => {
+        event.preventDefault();
+        this.press(key.dataset['k'] ?? '');
+      };
+      key.addEventListener('mousedown', press);
+      key.addEventListener('touchstart', press, { passive: false });
+    }
+    this.highlightFocusedKey();
+  }
+
+  /** Close it. */
+  close(): void {
+    this.panel?.remove();
+    this.panel = null;
+    this.target = null;
+    this.keys = [];
+  }
+
+  /** Called every frame while open: gamepad navigation. */
+  pollGamepads(): void {
+    if (this.panel === null) {
+      return;
+    }
+    const pads = readGamepads();
+    const direction = heldDirection(pads);
+    if (this.repeats.fires('move', direction !== null) && direction !== null) {
+      this.moveFocus(direction);
+    }
+    if (this.presses.rose('act', isAnyPadButtonPressed(pads, PAD_BUTTON.A))) {
+      this.press(this.keys[this.focusedIndex]?.dataset['k'] ?? '');
+    }
+    const isClosing = isAnyPadButtonPressed(pads, PAD_BUTTON.B) || isAnyPadButtonPressed(pads, PAD_BUTTON.START);
+    if (this.presses.rose('close', isClosing)) {
+      this.close();
+    }
+  }
+
+  private press(key: string): void {
+    if (key === 'close' || key === 'enter') {
+      this.close();
+      return;
+    }
+    if (key === 'shift') {
+      this.isShifted = !this.isShifted;
+      return;
+    }
+    const target = this.target;
+    if (target === null || key === '') {
+      return;
+    }
+    target.value = key === 'back' ? target.value.slice(0, -1) : target.value + (this.isShifted ? key.toUpperCase() : key);
+    target.dispatchEvent(new Event('input', { bubbles: true }));
+  }
+
+  private moveFocus(direction: Direction): void {
+    const next = findNearestInDirection(this.keys.map(rectOf), this.focusedIndex, direction);
+    if (next >= 0) {
+      this.focusedIndex = next;
+      this.highlightFocusedKey();
+    }
+  }
+
+  private highlightFocusedKey(): void {
+    this.keys.forEach((key, index) => key.classList.toggle('kfocus', index === this.focusedIndex));
+  }
+}

package/src/overlay/overlay.ts

@@ -0,0 +1,208 @@
+/**
+ * The input system's DOM overlay: the on-screen touch controls, the
+ * navigation highlight ring, the on-screen keyboard and the Controls screen.
+ * Everything lives in one style-isolated shadow root layered over the game,
+ * so it works the same for canvas and HTML games.
+ */
+import type { NavHighlighter } from '../input/nav-state';
+import type { InputConfig, InputOverrides, Rect, VirtualDef } from '../input/types';
+import { readField } from '../realtime/cross-bundle';
+import { ControlsPanel } from './controls-panel';
+import type { ControlsPanelHost } from './controls-panel';
+import { pageBody, placeAt, requireElement } from './dom';
+import { layoutControls } from './layout';
+import { controlSize } from './layout-geometry';
+import type { Insets, LayoutItem } from './layout-geometry';
+import { ListenerScope } from './listener-scope';
+import { OnScreenKeyboard } from './on-screen-keyboard';
+import { OVERLAY_CSS } from './styles';
+import { createVirtualControl } from './virtual-controls';
+import type { VirtualControlCallbacks } from './virtual-controls';
+
+/** One built on-screen control. */
+interface BuiltControl {
+  readonly definition: VirtualDef;
+  readonly group: string;
+  readonly element: HTMLElement;
+}
+
+/** The window event the race HUD fires with the bands it covers. */
+const RACE_HUD_EVENT = 'hub:race-hud';
+/** Wait for the browser to settle after a rotation before re-laying out. */
+const ORIENTATION_SETTLE_MS = 200;
+
+/** A number field of an event detail, or 0. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a window event detail from another bundle (the race HUD)
+function numberField(detail: unknown, key: string): number {
+  const field = Number(readField(detail, key));
+  return Number.isFinite(field) ? field : 0;
+}
+
+/** The overlay (one per input system). */
+export class Overlay implements NavHighlighter {
+  private readonly shadowHost: HTMLDivElement;
+  private readonly root: ShadowRoot;
+  private readonly controlsLayer: HTMLDivElement;
+  private readonly ring: HTMLDivElement;
+  private readonly keyboard: OnScreenKeyboard;
+  private readonly controlsPanel: ControlsPanel;
+  private controls: BuiltControl[] = [];
+  private controlScope = new ListenerScope();
+  private overrides: InputOverrides = {};
+  private gameInsets: Partial<Insets> = {};
+  private raceHudBands = { top: 0, bottom: 0 };
+  private safeAreaProbe: HTMLDivElement | null = null;
+
+  constructor() {
+    this.shadowHost = document.createElement('div');
+    this.shadowHost.id = 'hub-input-root';
+    this.root = this.shadowHost.attachShadow({ mode: 'open' });
+    this.root.innerHTML = `<style>${OVERLAY_CSS}</style>
+      <div class="layer controls"></div>
+      <div class="ring" hidden></div>`;
+    this.controlsLayer = requireElement(this.root, '.controls', HTMLDivElement);
+    this.ring = requireElement(this.root, '.ring', HTMLDivElement);
+    this.keyboard = new OnScreenKeyboard(this.root);
+    this.controlsPanel = new ControlsPanel(this.root, this.shadowHost);
+    (pageBody() ?? document.documentElement).appendChild(this.shadowHost);
+    window.addEventListener('resize', () => {
+      this.layout();
+    });
+    window.addEventListener('orientationchange', () => {
+      setTimeout(() => {
+        this.layout();
+      }, ORIENTATION_SETTLE_MS);
+    });
+    // Keep top and bottom controls clear of the hub's race HUD while it shows.
+    window.addEventListener(RACE_HUD_EVENT, (event) => {
+      // eslint-disable-next-line no-restricted-syntax -- trust boundary: the race HUD's event detail, read field by field
+      const detail: unknown = event instanceof CustomEvent ? event.detail : null;
+      const isVisible = readField(detail, 'visible') === true;
+      const bands = { top: isVisible ? numberField(detail, 'top') : 0, bottom: isVisible ? numberField(detail, 'bottom') : 0 };
+      if (bands.top !== this.raceHudBands.top || bands.bottom !== this.raceHudBands.bottom) {
+        this.raceHudBands = bands;
+        this.layout();
+      }
+    });
+  }
+
+  /** (Re)build every on-screen control from the config and the player's overrides. */
+  build(config: InputConfig, overrides: InputOverrides, callbacks: VirtualControlCallbacks): void {
+    this.overrides = overrides;
+    this.controlScope.dispose();
+    this.controlScope = new ListenerScope();
+    this.controlsLayer.innerHTML = '';
+    this.controls = [];
+    const environment = { callbacks, scope: this.controlScope, isEditing: () => this.controlsPanel.isEditing };
+    for (const [group, groupDefinition] of Object.entries(config.groups)) {
+      for (const declared of groupDefinition.virtual ?? []) {
+        const definition: VirtualDef = { ...declared, ...overrides.virtual?.[declared.id] };
+        const element = createVirtualControl(definition, environment);
+        Reflect.set(element, '__group', group);
+        this.controlsLayer.appendChild(element);
+        this.controls.push({ definition, group, element });
+      }
+    }
+    this.layout();
+  }
+
+  /** Replace a button or tap control's content at runtime. Listeners live on the wrapper, so they survive. */
+  setControlHtml(id: string, html: string): void {
+    const control = this.controls.find((candidate) => candidate.definition.id === id);
+    if (control !== undefined && (control.definition.type === 'button' || control.definition.type === 'tap')) {
+      control.element.innerHTML = html;
+    }
+  }
+
+  /** Show controls of the enabled groups (or of every group, with `null`, while editing). */
+  setVirtualVisible(isVisible: boolean, enabledGroups: ReadonlySet<string> | null): void {
+    for (const control of this.controls) {
+      const isShown = isVisible && (enabledGroups === null || enabledGroups.has(control.group));
+      control.element.style.display = isShown ? '' : 'none';
+    }
+  }
+
+  /** Game insets (px) auto-placed controls keep clear of, e.g. a top HUD bar. Merged with earlier calls. */
+  setInsets(insets: Partial<Insets>): void {
+    this.gameInsets = { ...this.gameInsets, ...insets };
+    this.layout();
+  }
+
+  /** Re-place every control for the current viewport, keeping the player's dragged spots. */
+  layout(): void {
+    if (this.controls.length === 0) {
+      return;
+    }
+    const insets: Insets = {
+      top: (this.gameInsets.top ?? 0) + this.raceHudBands.top,
+      right: this.gameInsets.right ?? 0,
+      bottom: (this.gameInsets.bottom ?? 0) + this.raceHudBands.bottom,
+      left: this.gameInsets.left ?? 0,
+    };
+    const items: LayoutItem[] = this.controls.map(({ definition }) => {
+      const dragged = this.overrides.virtual?.[definition.id];
+      return {
+        id: definition.id,
+        type: definition.type,
+        place: definition.place,
+        ...controlSize(definition),
+        pos: definition.pos,
+        offset: definition.offset,
+        override: dragged?.x !== undefined && dragged.y !== undefined ? { x: dragged.x, y: dragged.y } : undefined,
+      };
+    });
+    const boxes = layoutControls(items, window.innerWidth, window.innerHeight, { insets, safe: this.readSafeArea() });
+    for (const control of this.controls) {
+      const box = boxes[control.definition.id];
+      if (box !== undefined) {
+        placeAt(control.element, box.x, box.y);
+      }
+    }
+  }
+
+  /** Ring the highlighted element. */
+  showHighlight(bounds: Rect): void {
+    this.ring.hidden = false;
+    this.ring.style.left = `${String(bounds.x)}px`;
+    this.ring.style.top = `${String(bounds.y)}px`;
+    this.ring.style.width = `${String(bounds.width)}px`;
+    this.ring.style.height = `${String(bounds.height)}px`;
+  }
+
+  /** Remove the ring. */
+  hideHighlight(): void {
+    this.ring.hidden = true;
+  }
+
+  /** Open the on-screen keyboard for a text field. */
+  openKeyboard(target: HTMLInputElement | HTMLTextAreaElement | null): void {
+    this.keyboard.open(target);
+  }
+
+  /** Whether the on-screen keyboard is showing. */
+  get isKeyboardOpen(): boolean {
+    return this.keyboard.isOpen;
+  }
+
+  /** Open (or close) the Controls screen. */
+  toggleControls(config: InputConfig | null, host: ControlsPanelHost): void {
+    this.controlsPanel.toggle(config, host);
+  }
+
+  /** Per-frame work: gamepad navigation of the keyboard. */
+  afterFrame(): void {
+    this.keyboard.pollGamepads();
+  }
+
+  /** The device safe-area insets (notch, home bar), via a probe element. */
+  private readSafeArea(): Insets {
+    if (this.safeAreaProbe === null) {
+      this.safeAreaProbe = document.createElement('div');
+      this.safeAreaProbe.className = 'safe-probe';
+      this.root.appendChild(this.safeAreaProbe);
+    }
+    const style = getComputedStyle(this.safeAreaProbe);
+    const pixels = (value: string): number => parseFloat(value) || 0;
+    return { top: pixels(style.paddingTop), right: pixels(style.paddingRight), bottom: pixels(style.paddingBottom), left: pixels(style.paddingLeft) };
+  }
+}

package/src/overlay/styles.ts

@@ -0,0 +1,54 @@
+/**
+ * The overlay's styles (inside its shadow root, so games can't restyle it).
+ */
+
+/** The hub accent colour. */
+export const ACCENT_COLOR = '#ff5f3b';
+
+/** The overlay stylesheet. */
+export const OVERLAY_CSS = `
+:host { all: initial; }
+.layer { position: fixed; inset: 0; pointer-events: none; z-index: 2147483000; font-family: 'Space Mono', ui-monospace, monospace; }
+.vc { position: fixed; pointer-events: auto; touch-action: none; user-select: none; -webkit-user-select: none;
+      display: grid; place-items: center; color: #fff; }
+.vc-button, .vc-tap { background: var(--vc-bg, rgba(20,22,30,.55)); border: 2px solid var(--vc-color);
+      font: 700 15px/1 monospace; box-shadow: 0 2px 10px rgba(0,0,0,.4); }
+.vc-button.pressed, .vc-tap.pressed { background: var(--vc-color); color: #0d0f14; }
+.vc-transparent { background: transparent; border-color: transparent; }
+.vc-joystick .base, .vc-dpad .base { position: absolute; inset: 0; background: var(--vc-bg, rgba(20,22,30,.4)); border: 2px solid var(--vc-color); }
+.vc-joystick .knob, .vc-dpad .knob { position: absolute; width: 44%; height: 44%; border-radius: 50%; background: var(--vc-color); opacity: .9; }
+:host(.editing) .vc { outline: 2px dashed #38d6ff; cursor: move; }
+/* While editing the layout the panel shrinks to a small bar at the top so the
+   controls underneath can be dragged. */
+.edit-bar { display: none; }
+:host(.editing) .panel { background: transparent; pointer-events: none; place-items: start center; }
+:host(.editing) .panel-card { pointer-events: auto; width: auto; margin-top: max(10px, env(safe-area-inset-top, 0px)); padding: 8px 10px; }
+:host(.editing) .panel-card > :not(.edit-bar) { display: none; }
+:host(.editing) .edit-bar { display: flex; align-items: center; gap: 10px; font-size: 13px; }
+:host(.editing) .edit-bar .btn { margin: 0; }
+.safe-probe { position: fixed; left: 0; top: 0; width: 0; height: 0; visibility: hidden; pointer-events: none;
+  padding: env(safe-area-inset-top, 0px) env(safe-area-inset-right, 0px) env(safe-area-inset-bottom, 0px) env(safe-area-inset-left, 0px); }
+.ring { position: fixed; pointer-events: none; z-index: 2147483200; border: 3px solid ${ACCENT_COLOR}; border-radius: 8px;
+        box-shadow: 0 0 0 2px rgba(0,0,0,.4); transition: left .08s, top .08s, width .08s, height .08s; }
+.ring[hidden] { display: none; }
+.kb { position: fixed; left: 0; right: 0; bottom: 0; z-index: 2147483400; background: #0d0f14ee; padding: 10px;
+      pointer-events: auto; border-top: 1px solid #2a3142; }
+.kb-rows { display: flex; flex-direction: column; gap: 6px; max-width: 760px; margin: 0 auto; }
+.kb-row { display: flex; gap: 6px; justify-content: center; }
+.kb .k { flex: 1; min-width: 0; max-width: 64px; height: 46px; border-radius: 8px; border: 1px solid #2a3142;
+         background: #11141c; color: #e8e6df; font: 16px monospace; cursor: pointer; }
+.kb .k.space { max-width: 280px; } .kb .k.wide { max-width: 90px; }
+.kb .k.kfocus { border-color: ${ACCENT_COLOR}; box-shadow: 0 0 0 2px ${ACCENT_COLOR}; }
+.panel { position: fixed; inset: 0; z-index: 2147483500; display: grid; place-items: center; background: rgba(0,0,0,.6); pointer-events: auto;
+         font-family: 'Space Mono', ui-monospace, monospace; }
+.panel-card { background: #0d0f14; color: #e8e6df; border: 1px solid #2a3142; border-radius: 12px; padding: 18px;
+         width: min(420px, 92vw); max-height: 86vh; overflow: auto; box-shadow: 0 12px 44px rgba(0,0,0,.6); }
+.panel-card h3 { margin: 0 0 12px; } .panel-card h4 { margin: 14px 0 6px; color: #6f7787; text-transform: uppercase; font-size: 11px; letter-spacing: .08em; }
+.cr { display: flex; align-items: center; gap: 8px; font-size: 13px; padding: 4px 0; border-bottom: 1px solid #1a1f2b; }
+.cr span { flex: 1; } .cr .bind { color: #4ade80; } .cr .rb { background: transparent; color: ${ACCENT_COLOR}; border: 1px solid #2a3142; border-radius: 6px; padding: 3px 8px; cursor: pointer; font: 11px monospace; }
+.chk { display: flex; gap: 8px; align-items: center; font-size: 13px; margin-bottom: 10px; }
+.btn { background: ${ACCENT_COLOR}; color: #0d0f14; border: 0; border-radius: 8px; padding: 8px 12px; font: 13px monospace; cursor: pointer; margin: 4px 4px 0 0; }
+.btn.editlayout, .btn.reset { background: transparent; color: #e8e6df; border: 1px solid #2a3142; }
+.panel-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 14px; }
+.hint { color: #38d6ff; font-size: 12px; min-height: 1em; }
+`;