@pretty-chitty/core 1.1.1

package/src/library/game/serverTransport/ServerTime.ts

@@ -0,0 +1,74 @@
+import { Connection } from "../Connection";
+import { ConnectionObject } from "../ConnectionObject";
+import { Match } from "../Match";
+import { PlayerChit } from "../PlayerChit";
+import { RootChit } from "../RootChit";
+import { ClientTime } from "../clientTransport/ClientTime";
+import { Chit } from "../Chit";
+
+export class ServerTime<P extends PlayerChit, R extends RootChit<P>> extends ConnectionObject {
+  private clientTime: ClientTime;
+  private hasSentLastActionTime = false;
+  constructor(
+    private match: Match<P, R>,
+    private playerId: string,
+    private connection: Connection,
+  ) {
+    super();
+
+    this.clientTime = connection.get<ClientTime>("ClientTime");
+    this.register(
+      match.onChange(() => {
+        if (match.turn.value) {
+          this.clientTime.newMaxClock(match.turn.value.clockDetails(this.playerId));
+        }
+
+        if (!this.hasSentLastActionTime) {
+          this.hasSentLastActionTime = true;
+
+          const player = match.turn.value?.rootChit.players.find((p) => p.id === playerId);
+          if (player) {
+            this.clientTime.setStartTime(player.promptStatus.latestPromptResponseTime);
+          }
+        }
+      }),
+    );
+  }
+
+  private stateCounter = 0;
+  private stateLookups: { [chitId: string]: number } = {};
+  async serializeDelta(to: number) {
+    if (this.match.turn.value) {
+      const result = this.match.turn.value.serialize(this.playerId, to);
+
+      const newStates: { [stateId: number]: string } = {};
+      const chitIdToStateCounter: { [chitId: string]: number } = {};
+      Object.entries(result.chits).forEach(([key, value]: [string, string]) => {
+        let state = this.stateLookups[value];
+        if (state === undefined) {
+          state = this.stateLookups[key] = ++this.stateCounter;
+          newStates[this.stateCounter] = Chit.fixVisibility(value, this.playerId);
+        }
+        chitIdToStateCounter[key] = state;
+      });
+
+      return {
+        clockDetails: result.clockDetails,
+        newStates,
+        chits: chitIdToStateCounter,
+        log: result.log,
+      };
+    }
+    throw new Error("No match or match hasn't started");
+  }
+
+  async chitHistory(ids: string[]) {
+    return this.match.turn.value!.chitsHistory(this.playerId, ids);
+  }
+
+  async gameLog() {
+    if (this.match.turn.value) {
+      return this.match.turn.value.gameLog(this.playerId);
+    }
+  }
+}

package/src/library/hooks/useChits.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react";
+import { Chit } from "../game/Chit";
+import { useTimeController } from "./useTimeController";
+
+export function useChits<C extends Chit>(ids: string[]) {
+  const time = useTimeController();
+  const [result, setResult] = useState<C[]>([]);
+
+  const idString = ids.join("___");
+
+  useEffect(() => {
+    const resultVersions = result.map((r) => r.version);
+    return time.currentClock.on(() => {
+      const chits = ids.map((id) => time.findChitUnsafe(id) as C).filter((c) => c);
+      if (
+        result.length !== chits.length ||
+        chits.find((el, i) => el !== result[i] || el.version !== resultVersions[i])
+      ) {
+        setResult(chits);
+      }
+    });
+
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [time, idString, result]);
+
+  return result;
+}
+
+export function useChit<C extends Chit>(id: string): C | undefined {
+  const chits = useChits<C>([id]);
+  return chits[0];
+}

package/src/library/hooks/useConnection.tsx

@@ -0,0 +1,16 @@
+import React, { useContext, createContext, ReactNode } from "react";
+import { Connection } from "../game/Connection";
+
+const ConnectionContext = createContext<Connection | undefined>(undefined);
+
+export function useConnection(): Connection {
+  const result = useContext(ConnectionContext);
+  if (!result) {
+    throw new Error("Connection is required");
+  }
+  return result;
+}
+
+export function ConnectionProvider({ connection, children }: { connection: Connection; children: ReactNode }) {
+  return <ConnectionContext.Provider value={connection}>{children}</ConnectionContext.Provider>;
+}

package/src/library/hooks/useEventChannelState.ts

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useState } from "react";
+import { EventChannel } from "../utilities/EventChannel";
+
+export function useEventChannelState<T>(e: EventChannel<T>): [T, (a: T) => void] {
+  const [v, setV] = useState<T>(e.value);
+
+  useEffect(() => {
+    // calling explicitly here saves a `nextTick` scheduling and fixes the problem where a value
+    // changes between when this is invoked and when useEffect is invoked.
+    setV(e.value);
+    e.on(setV, false);
+  }, [e]);
+
+  const setter = useCallback(
+    (newValue: T) => {
+      e.value = newValue;
+    },
+    [e],
+  );
+  return [v, setter];
+}
+
+export function useMultiEventChannelState<T, Z>(list: Z[], mapper: (arg: Z) => EventChannel<T>): T[] {
+  const eventChannels = list.map(mapper);
+  const [v, setV] = useState<T[]>(eventChannels.map((d) => d.value));
+
+  useEffect(() => {
+    const cbs = eventChannels.map((z) => z.on(() => setV(eventChannels.map((d) => d.value)), false));
+    return () => cbs.forEach((cb) => cb());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [...list, mapper]);
+  return v;
+}

package/src/library/hooks/useGame.tsx

@@ -0,0 +1,16 @@
+import React, { useContext, createContext, ReactNode } from "react";
+import { Game } from "../game/Game";
+
+const GameContext = createContext<Game<any, any> | undefined>(undefined);
+
+export function useGame(): Game<any, any> {
+  const result = useContext(GameContext);
+  if (!result) {
+    throw new Error("Game is required");
+  }
+  return result;
+}
+
+export function GameProvider({ game, children }: { game: Game<any, any>; children: ReactNode }) {
+  return <GameContext.Provider value={game}>{children}</GameContext.Provider>;
+}

package/src/library/hooks/useGameTheme.tsx

@@ -0,0 +1,12 @@
+import React, { useContext, createContext, ReactNode } from "react";
+import { GameTheme as Theme } from "../game/GameTheme";
+
+const ThemeContext = createContext<Theme>(new Theme());
+
+export function useGameTheme(): Theme {
+  return useContext(ThemeContext);
+}
+
+export function GameThemeProvider({ theme, children }: { theme: Theme; children: ReactNode }) {
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}

package/src/library/hooks/useModalState.tsx

@@ -0,0 +1,13 @@
+import React, { useContext, createContext, ReactNode } from "react";
+import { ModalState } from "../game/ModalState";
+
+const ModalContext = createContext<ModalState>(new ModalState());
+
+export function useModalState(): ModalState {
+  const result = useContext(ModalContext);
+  return result;
+}
+
+export function ModalProvider({ children }: { children: ReactNode }) {
+  return <ModalContext.Provider value={new ModalState()}>{children}</ModalContext.Provider>;
+}

package/src/library/hooks/usePanelPositioning.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext } from "react";
+
+export interface ViewerPosition {
+  chitId: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  paused: boolean;
+  refContainer: React.RefObject<HTMLElement> | null;
+  front: boolean;
+  panCallback?: (direction: "left" | "right") => void;
+  visible: boolean; // For MultiPanel sliding animations
+  transition?: string | null; // CSS transition for animated position changes
+}
+
+interface PanelPositioningContextValue {
+  positions: Map<string, ViewerPosition>;
+  registerPosition: (chitId: string, position: ViewerPosition) => void;
+  unregisterPosition: (chitId: string) => void;
+}
+
+export const PanelPositioningContext = createContext<PanelPositioningContextValue | null>(null);
+
+export function usePanelPositioning() {
+  const context = useContext(PanelPositioningContext);
+  if (!context) {
+    throw new Error("usePanelPositioning must be used within PanelPositioningContext.Provider");
+  }
+  return context;
+}

package/src/library/hooks/usePanelScale.tsx

@@ -0,0 +1,23 @@
+import React, { useContext, createContext, ReactNode, useState } from "react";
+
+const PanelScaleContext = createContext<{ scale: number; setScale: (n: number) => void }>({
+  scale: 1,
+  setScale: () => {},
+});
+
+export function usePanelScale(): number {
+  return useContext(PanelScaleContext).scale;
+}
+export function usePanelSetScale(): (n: number) => void {
+  return useContext(PanelScaleContext).setScale;
+}
+
+export function PanelScaleProvider({ children }: { children: ReactNode }) {
+  const initialScale = parseFloat(localStorage["panelScale"] ?? "1") || 1; // should this be game specific?
+  const [scale, setScaleState] = useState<number>(initialScale);
+  const setScale = (n: number) => {
+    localStorage["panelScale"] = n;
+    setScaleState(n);
+  };
+  return <PanelScaleContext.Provider value={{ scale, setScale }}>{children}</PanelScaleContext.Provider>;
+}

package/src/library/hooks/usePanelStates.ts

@@ -0,0 +1,30 @@
+import { useEffect, useState } from "react";
+import { AnimationState, RootChitRenderInstance } from "../rendering/RootChitRenderInstance";
+
+type PanelState = {
+  panel?: RootChitRenderInstance;
+  paused?: boolean;
+  state?: AnimationState;
+};
+
+export function usePanelStates(rootChitInstances: (undefined | RootChitRenderInstance)[]): PanelState[] {
+  const [states, setStates] = useState<PanelState[]>([]);
+
+  useEffect(() => {
+    const updateStates = () => {
+      setStates(
+        rootChitInstances.map((panel) => ({
+          panel,
+          paused: panel?.paused,
+          state: panel?.animationState,
+        })),
+      );
+    };
+    updateStates();
+    const cbs = rootChitInstances.map((panel) => panel?.onPanelStatusChange(updateStates));
+    return () => cbs.forEach((cb) => cb && cb());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rootChitInstances.map((r) => r?.id).join("-")]);
+
+  return states;
+}

package/src/library/hooks/usePlayer.tsx

@@ -0,0 +1,15 @@
+import React, { useContext, createContext, ReactNode } from "react";
+
+const PlayerContext = createContext<string | undefined>(undefined);
+
+export function usePlayerId(): string {
+  const result = useContext(PlayerContext);
+  if (!result) {
+    throw new Error("Player is required");
+  }
+  return result;
+}
+
+export function PlayerProvider({ playerId, children }: { playerId: string; children: ReactNode }) {
+  return <PlayerContext.Provider value={playerId}>{children}</PlayerContext.Provider>;
+}

package/src/library/hooks/useSmartDebouncedState.ts

@@ -0,0 +1,161 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+type Equality<T> = (a: T, b: T) => boolean;
+
+export interface UseSmartDebouncedStateOptions<T> {
+  /** Fixed cooldown after a commit; calls inside fire once at lastCommit + interval */
+  interval: number;
+  /** Mini debounce when idle; 0 => commit immediately */
+  immediate?: number;
+  /** Custom equality; defaults to Object.is */
+  isEqual?: Equality<T>;
+}
+
+export interface SmartDebouncedMeta {
+  flush: () => void;
+  cancel: () => void;
+  pending: boolean;
+  /** Epoch ms when the next commit is scheduled (or undefined if none) */
+  nextCommitAt?: number;
+}
+
+export interface SetOptions {
+  /**
+   * If true, this call starts (or refreshes) the immediate mini-window and
+   * LOCKS it so subsequent calls during that immediate window cannot reschedule/extend it.
+   * Later calls still coalesce the value, but the deadline stays fixed.
+   */
+  noImmediateInterrupt?: boolean;
+}
+
+type Mode = "immediate" | "cooldown" | null;
+
+export function useSmartDebouncedState<T>(
+  initial: T,
+  options: UseSmartDebouncedStateOptions<T>,
+): [T, (next: T, opts?: SetOptions) => void, SmartDebouncedMeta] {
+  const { interval, immediate = 0, isEqual = Object.is } = options;
+
+  const [value, setValue] = useState<T>(initial);
+
+  const lastCommitRef = useRef<number>(Number.NEGATIVE_INFINITY);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const modeRef = useRef<Mode>(null);
+  const pendingRef = useRef<T | undefined>(undefined);
+  const lastRequestedRef = useRef<T>(initial);
+  const nextCommitAtRef = useRef<number | undefined>(undefined);
+  const immediateLockUntilRef = useRef<number | undefined>(undefined); // <-- NEW
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    modeRef.current = null;
+    nextCommitAtRef.current = undefined;
+    immediateLockUntilRef.current = undefined; // clear lock on timer clear
+  }, []);
+
+  const commit = useCallback(
+    (next: T, at: number = Date.now()) => {
+      clearTimer();
+      pendingRef.current = undefined;
+      if (!isEqual(value, next)) setValue(next);
+      lastCommitRef.current = at;
+    },
+    [clearTimer, isEqual, value],
+  );
+
+  const scheduleAt = useCallback(
+    (deadlineMs: number, asMode: Mode) => {
+      clearTimer();
+      modeRef.current = asMode;
+      nextCommitAtRef.current = deadlineMs;
+      const delay = Math.max(0, deadlineMs - Date.now());
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        modeRef.current = null;
+        const pv = pendingRef.current;
+        nextCommitAtRef.current = undefined;
+        immediateLockUntilRef.current = undefined; // unlock at fire
+        if (pv !== undefined) commit(pv, deadlineMs);
+      }, delay);
+    },
+    [clearTimer, commit],
+  );
+
+  const set = useCallback(
+    (next: T, opts?: SetOptions) => {
+      // (5) No-op if same as previous *request* input
+      if (isEqual(next, value)) return;
+      lastRequestedRef.current = next;
+
+      const now = Date.now();
+      const cooldownDeadline = lastCommitRef.current + interval;
+      const idle = now >= cooldownDeadline;
+
+      // Always coalesce to the latest requested value
+      pendingRef.current = next;
+
+      if (idle) {
+        if (immediate <= 0) {
+          // No mini-window → commit immediately (unless same as state)
+          if (!isEqual(value, next)) commit(next, now);
+          else pendingRef.current = undefined;
+          return;
+        }
+
+        // Immediate mini-window path
+        const inImmediate = timerRef.current != null && modeRef.current === "immediate";
+        const lockActive =
+          inImmediate && immediateLockUntilRef.current !== undefined && now < immediateLockUntilRef.current;
+
+        if (inImmediate && lockActive) {
+          // A locked immediate window is running → DO NOT reschedule.
+          // We only update the pending value (already done above).
+          return;
+        }
+
+        const deadline = now + immediate;
+
+        // Start/refresh immediate. If this call requests a lock, set/refresh the lock to this deadline.
+        scheduleAt(deadline, "immediate");
+        if (opts?.noImmediateInterrupt) {
+          immediateLockUntilRef.current = deadline + (interval - immediate); // lock until end of cooldown after immediate
+        } else {
+          // If caller didn't request a lock, we clear any prior lock so future calls may reschedule
+          immediateLockUntilRef.current = undefined;
+        }
+      } else {
+        // Cooldown → fixed deadline (never extended)
+        scheduleAt(cooldownDeadline, "cooldown");
+        // Cooldown ignores immediate lock
+        immediateLockUntilRef.current = undefined;
+      }
+    },
+    [commit, immediate, interval, isEqual, scheduleAt, value],
+  );
+
+  const flush = useCallback(() => {
+    const pv = pendingRef.current;
+    if (pv !== undefined) commit(pv);
+  }, [commit]);
+
+  const cancel = useCallback(() => {
+    pendingRef.current = undefined;
+    clearTimer();
+  }, [clearTimer]);
+
+  useEffect(() => clearTimer, [clearTimer]);
+
+  return [
+    value,
+    set,
+    {
+      flush,
+      cancel,
+      pending: timerRef.current != null,
+      nextCommitAt: nextCommitAtRef.current,
+    },
+  ];
+}

package/src/library/hooks/useTimeController.tsx

@@ -0,0 +1,108 @@
+import React, { useContext, createContext, ReactNode, useEffect, useState } from "react";
+import { ClockDetails } from "../game/ClockDetails";
+import { Chit } from "../game/Chit";
+import { useConnection } from "./useConnection";
+import { ClientTime } from "../game/clientTransport/ClientTime";
+import { ClientTimeState } from "../game/ClientTimeState";
+import { ClientPrompts } from "../game/clientTransport/ClientPrompts";
+import { usePlayerId } from "./usePlayer";
+import { ClientStatus } from "../game/clientTransport/ClientStatus";
+import { useGame } from "./useGame";
+import { useEventChannelState } from "./useEventChannelState";
+
+export class TimeState {
+  public targetClock: number = 1;
+  public currentClock: ClockDetails = { clock: 0, pass: -1 };
+  public maxClock: ClockDetails = { clock: 0, pass: -1 };
+  public rootChit: Chit = new Chit();
+}
+
+const TimeControllerContext = createContext<{
+  clientPrompts?: ClientPrompts<any, any>;
+  clientTimeState: ClientTimeState;
+  clientTime?: ClientTime;
+  clientStatus?: ClientStatus<any, any>;
+}>({ clientTimeState: new ClientTimeState() });
+
+export function useTimeController() {
+  const result = useContext(TimeControllerContext);
+  if (!result.clientTime) {
+    throw new Error("Connection is required");
+  }
+  return result.clientTime;
+}
+
+export function useTimeState() {
+  const result = useContext(TimeControllerContext);
+  return result.clientTimeState;
+}
+export function useClientPrompts() {
+  const result = useContext(TimeControllerContext);
+  if (!result.clientPrompts) {
+    throw new Error("Connection is required");
+  }
+  return result.clientPrompts;
+}
+export function useClientStatus() {
+  const result = useContext(TimeControllerContext);
+  if (!result.clientStatus) {
+    throw new Error("Connection is required");
+  }
+  return result.clientStatus;
+}
+export function useAnimationSpeedMultiplier() {
+  const result = useContext(TimeControllerContext);
+  const [speed] = useEventChannelState(result.clientTimeState.animationSpeedMultiplier);
+  const [override] = useEventChannelState(result.clientTimeState.animationSpeedOverrideMultiplier);
+  if (override) {
+    return override;
+  }
+  return speed;
+}
+
+export function TimeControllerProvider({ children }: { children: ReactNode }) {
+  const connection = useConnection();
+  const playerId = usePlayerId();
+  const game = useGame();
+  const [clientTimeState] = useState<ClientTimeState>(new ClientTimeState());
+  const [clientTime, setClientTime] = useState<ClientTime | null>(null);
+  const [clientPrompts, setClientPrompts] = useState<ClientPrompts<any, any> | undefined>(undefined);
+  const [clientStatus, setClientStatus] = useState<ClientStatus<any, any> | undefined>(undefined);
+
+  useEffect(() => {
+    if (!connection) {
+      return;
+    }
+
+    if (!clientTime || clientTime.connection !== connection) {
+      clientTime?.dispose();
+
+      const newClientTime = new ClientTime(connection, game, clientTimeState);
+      connection.register(newClientTime);
+
+      const cp = new ClientPrompts(playerId, connection, newClientTime);
+      connection.register(cp);
+      newClientTime.clientPrompt = cp; // circular reference.  ugly.
+
+      const cs = new ClientStatus(connection);
+      connection.register(cs);
+
+      if (clientTime) {
+        newClientTime.maxClock.value = clientTime.maxClock.value;
+      }
+
+      setClientTime(newClientTime);
+      setClientPrompts(cp);
+      setClientStatus(cs);
+    }
+  }, [connection, clientTime, game, clientTimeState, playerId]);
+
+  if (!clientTime) {
+    return null;
+  }
+  return (
+    <TimeControllerContext.Provider value={{ clientPrompts, clientTime, clientTimeState, clientStatus }}>
+      {children}
+    </TimeControllerContext.Provider>
+  );
+}

package/src/library/hooks/useTokenMap.ts

@@ -0,0 +1,20 @@
+import { useChit, useChits } from "../hooks/useChits";
+import { PlayerChit } from "../game/PlayerChit";
+import { RootChit } from "../game/RootChit";
+import { TokenDefinition } from "../components/TokenizedMessage";
+import { useGameTheme } from "./useGameTheme";
+import { useGame } from "./useGame";
+
+export function useTokenMap() {
+  const theme = useGameTheme();
+  const game = useGame();
+  const root = useChit<RootChit<PlayerChit>>("root");
+  const playerChits = useChits<PlayerChit>(root?.players.map((p) => p.id ?? "") ?? []);
+
+  const tokenMap: { [key: string]: TokenDefinition } = { ...(game.tokenMap ?? {}) };
+  playerChits?.forEach((p) => {
+    tokenMap[p.playerId] = { label: p.name ?? "??", color: p.color ?? theme.actionLogTextColor, image: p.imageUrl };
+  });
+  tokenMap["warning"] = { label: "⚠️" };
+  return tokenMap;
+}