@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/overlay/overlay.ts

@@ -1,208 +1,234 @@
-/**
- * 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) };
-  }
-}
+/**
+ * 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 { trackInputModality } from '../input/modality';
+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. Also published on the page as
+   * `--hub-inset-top` (and right, bottom, left), so the hub's toasts sit
+   * below a top HUD too.
+   */
+  setInsets(insets: Partial<Insets>): void {
+    this.gameInsets = { ...this.gameInsets, ...insets };
+    publishInsets(this.gameInsets);
+    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, for keyboard and gamepad players only (never after a tap or click). */
+  showHighlight(bounds: Rect, radius: string): void {
+    this.ring.hidden = !trackInputModality().showsFocus;
+    this.ring.style.borderRadius = radius;
+    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) };
+  }
+}
+
+/** Every inset side. */
+const INSET_SIDES: readonly (keyof Insets)[] = ['top', 'right', 'bottom', 'left'];
+
+/** The page-wide CSS variables other hub UI (the runtime's toasts) keeps clear of. */
+function publishInsets(insets: Partial<Insets>): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  for (const side of INSET_SIDES) {
+    const px = insets[side];
+    if (px === undefined) {
+      document.documentElement.style.removeProperty(`--hub-inset-${side}`);
+    } else {
+      document.documentElement.style.setProperty(`--hub-inset-${side}`, `${String(Math.max(0, Math.round(px)))}px`);
+    }
+  }
+}

package/src/overlay/styles.ts

@@ -1,11 +1,12 @@
-/**
- * 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. */
+/**
+ * The overlay's styles (inside its shadow root, so games can't restyle it).
+ */
+import { FOCUS_RING_SHADOW } from '../input/focus-ring';
+
+/** 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; }
@@ -28,8 +29,8 @@ export const OVERLAY_CSS = `
 :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 { position: fixed; pointer-events: none; z-index: 2147483200; box-shadow: ${FOCUS_RING_SHADOW};
+        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; }
@@ -38,7 +39,7 @@ export const OVERLAY_CSS = `
 .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}; }
+.kb .k.kfocus { box-shadow: ${FOCUS_RING_SHADOW}; }
 .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;
@@ -51,4 +52,4 @@ export const OVERLAY_CSS = `
 .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; }
-`;
+`;