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

package/src/overlay/layout.ts

@@ -1,203 +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 };
-}
+/**
+ * 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

@@ -1,23 +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();
-    }
-  }
-}
+/**
+ * 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();
+    }
+  }
+}