@driftengine/core 3.61.0

package/src/core/messageQueue.ts

@@ -0,0 +1,145 @@
+/**
+ * One transient message at a time, in priority order.
+ *
+ * Games fire events in bursts — finishing a run can produce three at once — and
+ * three notifications stacked on top of each other is worse than one, because
+ * the player reads none of them. This holds the backlog and hands back a single
+ * current message, so the presentation layer never has to decide what to drop.
+ *
+ * Pure state and no DOM: what a notification *looks* like is the game's, and
+ * the part with rules worth pinning down is which one is on screen.
+ */
+export interface QueuedMessage {
+  /** Identity, used to collapse a repeat of the same event. */
+  readonly id: string;
+  /** Higher wins, both for ordering and for interrupting. */
+  readonly priority: number;
+  /** How long it holds the screen once current. */
+  readonly durationMs: number;
+}
+
+export interface MessageQueueOptions {
+  /**
+   * How long the same id is ignored after being shown.
+   *
+   * The realistic source of duplicates is a caller pushing from a per-frame
+   * check rather than an edge — sixty identical toasts a second, a bug that
+   * presents as the interface freezing on one message.
+   */
+  readonly dedupeWindowMs?: number;
+  /**
+   * Backlog ceiling. Without one, a caller pushing in a loop grows the queue
+   * forever and the player spends the next minute watching notifications from
+   * something that happened once.
+   */
+  readonly maxPending?: number;
+}
+
+export class MessageQueue<T extends QueuedMessage = QueuedMessage> {
+  private readonly pending: T[] = [];
+  private readonly lastShown = new Map<string, number>();
+  private readonly dedupeWindowMs: number;
+  private readonly maxPending: number;
+
+  private showing: T | null = null;
+  private showingUntil = 0;
+
+  constructor(options: MessageQueueOptions = {}) {
+    this.dedupeWindowMs = options.dedupeWindowMs ?? 900;
+    this.maxPending = options.maxPending ?? 6;
+  }
+
+  get current(): T | null {
+    return this.showing;
+  }
+
+  push(message: T): void {
+    this.pending.push(message);
+    if (this.pending.length <= this.maxPending) return;
+    // Drop the least important rather than the oldest: a backlog that has
+    // overflowed is exactly when the one thing that mattered must survive.
+    let worst = 0;
+    for (let i = 1; i < this.pending.length; i++) {
+      const candidate = this.pending[i];
+      const incumbent = this.pending[worst];
+      if (candidate === undefined || incumbent === undefined) continue;
+      if (candidate.priority < incumbent.priority) worst = i;
+    }
+    this.pending.splice(worst, 1);
+  }
+
+  /**
+   * Advance. Returns a message only on the frame it becomes current, so the
+   * caller can render it once rather than diffing against what it drew last.
+   */
+  update(nowMs: number): T | null {
+    if (this.showing !== null) {
+      /*
+       * Peeked, not taken. Removing the challenger and pushing it back when it
+       * loses reordered the backlog on every single frame, so two equally
+       * important messages arrived in whichever order the frame boundary
+       * happened to fall — which is not an order at all.
+       */
+      const challenger = this.pending[this.bestIndex(nowMs)];
+      // Something more important interrupts; anything else waits its turn. A
+      // personal best arriving during a minor toast is the moment of the run,
+      // and making it queue behind one buries it.
+      if (challenger !== undefined && challenger.priority > this.showing.priority) {
+        const taken = this.takeBest(nowMs);
+        if (taken !== null) {
+          this.pending.push(this.showing);
+          return this.show(taken, nowMs);
+        }
+      }
+      if (nowMs < this.showingUntil) return null;
+      this.showing = null;
+    }
+
+    const next = this.takeBest(nowMs);
+    return next === null ? null : this.show(next, nowMs);
+  }
+
+  /** Drop everything, including what is on screen — as a restart must. */
+  clear(): void {
+    this.pending.length = 0;
+    this.lastShown.clear();
+    this.showing = null;
+    this.showingUntil = 0;
+  }
+
+  private show(message: T, nowMs: number): T {
+    this.showing = message;
+    this.showingUntil = nowMs + message.durationMs;
+    this.lastShown.set(message.id, nowMs);
+    return message;
+  }
+
+  private takeBest(nowMs: number): T | null {
+    const index = this.bestIndex(nowMs);
+    if (index < 0) return null;
+    return this.pending.splice(index, 1)[0] ?? null;
+  }
+
+  /**
+   * Index of the highest-priority pending message, dropping recent repeats on
+   * the way past. Ties go to the earliest, so equally important events arrive
+   * in the order they actually happened.
+   */
+  private bestIndex(nowMs: number): number {
+    let best = -1;
+    for (let i = 0; i < this.pending.length; i++) {
+      const candidate = this.pending[i];
+      if (candidate === undefined) continue;
+
+      const shownAt = this.lastShown.get(candidate.id);
+      if (shownAt !== undefined && nowMs - shownAt < this.dedupeWindowMs) {
+        this.pending.splice(i, 1);
+        i--;
+        continue;
+      }
+      const incumbent = this.pending[best];
+      if (incumbent === undefined || candidate.priority > incumbent.priority) best = i;
+    }
+    return best;
+  }
+}

package/src/core/onceSet.ts

@@ -0,0 +1,65 @@
+import { defaultStore } from './storage.ts';
+import type { KeyValueStore } from './storage.ts';
+
+/**
+ * A persisted set of one-time flags: tutorial prompts, first-run hints,
+ * "you have seen this" markers.
+ *
+ * One key holding a set rather than a key per flag, because a game accumulates
+ * dozens of these and a key each turns a player's save into a junk drawer that
+ * cannot be cleared in one action.
+ *
+ * Where it persists is the store's problem. When the store cannot keep
+ * anything, flags last the session — showing a tutorial once per visit is mildly
+ * annoying, while never showing it strands a player who arrived from a link
+ * with no idea what the controls are.
+ */
+export class OnceSet {
+  private readonly seen: Set<string>;
+
+  constructor(
+    private readonly key: string,
+    private readonly store: KeyValueStore = defaultStore(),
+  ) {
+    this.seen = new Set(readIds(store, key));
+  }
+
+  has(id: string): boolean {
+    return this.seen.has(id);
+  }
+
+  /** True the first time only. Marks the flag as a side effect. */
+  claim(id: string): boolean {
+    if (this.seen.has(id)) return false;
+    this.mark(id);
+    return true;
+  }
+
+  mark(id: string): void {
+    if (this.seen.has(id)) return;
+    this.seen.add(id);
+    this.persist();
+  }
+
+  /** Forget everything — "show me the tutorial again". */
+  clear(): void {
+    this.seen.clear();
+    this.persist();
+  }
+
+  private persist(): void {
+    this.store.write(this.key, JSON.stringify([...this.seen]));
+  }
+}
+
+function readIds(store: KeyValueStore, key: string): string[] {
+  const raw = store.read(key);
+  if (raw === null) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((id): id is string => typeof id === 'string');
+  } catch {
+    return [];
+  }
+}

package/src/core/preferences.ts

@@ -0,0 +1,177 @@
+import { defaultStore } from './storage.ts';
+import type { KeyValueStore } from './storage.ts';
+
+/**
+ * Persisted player preferences: a validated record in a `KeyValueStore`.
+ *
+ * Generic on purpose. A game declares *which* preferences exist and what their
+ * legal values are; everything below — reading, validating field by field,
+ * clamping, writing and announcing changes — is the same work in any game.
+ *
+ * Where the bytes actually live is the store's problem, not this module's, so a
+ * game can persist to the browser, a server or nothing at all without any of
+ * this changing. See `storage.ts` for why that seam is synchronous.
+ */
+export interface PreferenceSchema<T extends object> {
+  /** Storage key. Namespace it — the store is shared with everything else. */
+  readonly key: string;
+  /** The complete set of fields, and the value each falls back to. */
+  readonly defaults: T;
+  /** Inclusive `[min, max]` for numeric fields. Values outside are clamped. */
+  readonly ranges?: Partial<Record<keyof T, readonly [number, number]>>;
+  /** Legal values for string fields. Anything else falls back to the default. */
+  readonly options?: Partial<Record<keyof T, readonly string[]>>;
+}
+
+/**
+ * The field types a preference record can hold. A default of any other shape is refused.
+ *
+ * **Refused loudly, and that is the whole point of this function.** `validate` below answers
+ * `undefined` for anything that is not one of these, and `undefined` means "the stored value was
+ * unusable, keep the default" — which is exactly right for *data* and exactly wrong for a
+ * *schema*. A field the schema declares as an array took that path and cost a consumer a
+ * afternoon: `loadPreferences` handed back the default every time, and `update` skipped the field
+ * without ever setting `changed`, so writing one was a no-op that persisted nothing, notified
+ * nobody and reported no error. It was found by a failing test rather than by anything here.
+ *
+ * **The two paths are deliberately not symmetrical.** A stored record always lags the code that
+ * reads it, so one field of the wrong shape is the normal case and is tolerated field by field.
+ * A schema is written by a developer and is wrong at compile time or never, so it fails at init,
+ * where the engine's rule says a fault belongs.
+ */
+const SUPPORTED = ['number', 'boolean', 'string'] as const;
+
+function assertSupportedSchema<T extends object>(schema: PreferenceSchema<T>): void {
+  for (const key of Object.keys(schema.defaults) as (keyof T)[]) {
+    const fallback = schema.defaults[key];
+    if ((SUPPORTED as readonly string[]).includes(typeof fallback)) continue;
+    const shape = Array.isArray(fallback) ? 'an array' : `a ${typeof fallback}`;
+    throw new Error(
+      `preferences: "${schema.key}.${String(key)}" defaults to ${shape}, and a preference field ` +
+        `may only be a number, a boolean or a string. Anything else is written to the store and ` +
+        `silently dropped on the way back, so it is refused here rather than at the next boot.`,
+    );
+  }
+}
+
+/** Coerce one field, returning undefined when the candidate is unusable. */
+function validate<T extends object>(
+  schema: PreferenceSchema<T>,
+  key: keyof T,
+  value: unknown,
+): T[keyof T] | undefined {
+  const fallback = schema.defaults[key];
+
+  if (typeof fallback === 'number') {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return undefined;
+    const range = schema.ranges?.[key];
+    if (range === undefined) return value as T[keyof T];
+    return Math.min(Math.max(value, range[0]), range[1]) as T[keyof T];
+  }
+  if (typeof fallback === 'boolean') {
+    return typeof value === 'boolean' ? (value as T[keyof T]) : undefined;
+  }
+  if (typeof fallback === 'string') {
+    if (typeof value !== 'string') return undefined;
+    const allowed = schema.options?.[key];
+    if (allowed !== undefined && !allowed.includes(value)) return undefined;
+    return value as T[keyof T];
+  }
+  return undefined;
+}
+
+export function loadPreferences<T extends object>(
+  schema: PreferenceSchema<T>,
+  store: KeyValueStore = defaultStore(),
+): T {
+  assertSupportedSchema(schema);
+  const result: T = { ...schema.defaults };
+
+  const raw = store.read(schema.key);
+  if (raw === null) return result;
+
+  let stored: unknown;
+  try {
+    stored = JSON.parse(raw);
+  } catch {
+    return result;
+  }
+  if (typeof stored !== 'object' || stored === null) return result;
+
+  /*
+   * Field by field rather than all or nothing. A stored record always lags the
+   * code that reads it, so one field of the wrong shape is the normal case —
+   * and discarding the record over it would wipe every other preference the
+   * player had ever set.
+   */
+  const source = stored as Record<string, unknown>;
+  for (const key of Object.keys(schema.defaults) as (keyof T)[]) {
+    const value = validate(schema, key, source[key as string]);
+    if (value !== undefined) result[key] = value;
+  }
+  return result;
+}
+
+export function savePreferences<T extends object>(
+  schema: PreferenceSchema<T>,
+  value: T,
+  store: KeyValueStore = defaultStore(),
+): void {
+  /* Checked here too: a caller that only ever saves would otherwise write a record that
+     nothing can read back, and find out one boot later in somebody else's session. */
+  assertSupportedSchema(schema);
+  store.write(schema.key, JSON.stringify(value));
+}
+
+/**
+ * A live preference record: the loaded value, validated updates, persistence
+ * and change notification for whatever applies them to running systems.
+ */
+export class PreferenceStore<T extends object> {
+  private current: T;
+  private readonly listeners = new Set<(value: Readonly<T>) => void>();
+
+  constructor(
+    private readonly schema: PreferenceSchema<T>,
+    private readonly store: KeyValueStore = defaultStore(),
+  ) {
+    this.current = loadPreferences(schema, store);
+  }
+
+  get value(): Readonly<T> {
+    return this.current;
+  }
+
+  /**
+   * Apply a partial change. Every field goes through the same validation as a
+   * stored one — a control that can produce an illegal value would otherwise
+   * write it, leaving the read path as the only thing catching it, one boot too
+   * late.
+   */
+  update(patch: Partial<T>): void {
+    let changed = false;
+    for (const key of Object.keys(patch) as (keyof T)[]) {
+      if (!(key in this.schema.defaults)) continue;
+      const next = validate(this.schema, key, patch[key]);
+      if (next === undefined || next === this.current[key]) continue;
+      this.current[key] = next;
+      changed = true;
+    }
+    // Silent when nothing moved: subscribers apply settings to live systems and
+    // some of those write back, which without this is a loop.
+    if (!changed) return;
+    savePreferences(this.schema, this.current, this.store);
+    for (const listener of this.listeners) listener(this.current);
+  }
+
+  /** Returns an unsubscribe function. */
+  subscribe(listener: (value: Readonly<T>) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Back to the declared defaults, persisted and announced like any change. */
+  reset(): void {
+    this.update({ ...this.schema.defaults });
+  }
+}