Depend on libWrapper, socketlib, simple-timekeeping instead of hand-rolled infra

Per the module-library direction: use vetted community libraries as
prerequisites rather than recreating core infrastructure, and prefer
editing this module over injecting another layer.

- module.json hard-requires lib-wrapper, socketlib, and simple-timekeeping.
- measure-fuzz.mjs wraps the ruler classes' _getWaypointLabelContext via
  libWrapper (WRAPPER on CONFIG.*.rulerClass paths) so it composes with other
  ruler modules instead of subclass-clobbering.
- New socket.mjs centralizes socketlib registration with an import-time queue;
  map-items fog reload uses executeForEveryone, player-requests uses
  executeAsGM. Removes the hand-rolled game.socket channel and manual
  active-GM routing.
- simple-timekeeping owns the world clock and scene-darkness sync; dungeon
  turns already feed it through game.time.advance, and the module only reads
  scene darkness (never writes it), so they never conflict. Documented in
  DESIGN.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: NocTempre

docs/DESIGN.md

@@ -2,6 +2,14 @@
 
 Follows the conventions of `acks-influence` (ApplicationV2 + HandlebarsApplicationMixin, Foundry v13/v14, `acks` system).
 
+## Required libraries
+
+Rather than recreate core infrastructure, the module hard-requires three community libraries (`relationships.requires` in `module.json`):
+
+- **libWrapper** — wraps the ruler classes' `_getWaypointLabelContext` (`measure-fuzz.mjs`) so it composes with other ruler modules instead of clobbering the class.
+- **socketlib** — all cross-client messaging (`socket.mjs`): named handlers with GM routing for player action requests and fog reloads.
+- **simple-timekeeping** — owns the world clock, calendar, and scene-darkness sync. Dungeon turns feed it through the standard `game.time.advance` contract; the module only *reads* scene darkness (`isPartyInDark`), never writes it, so the two never fight over darkness.
+
 ## Files
 
 | File | Responsibility |
@@ -12,6 +20,7 @@ Follows the conventions of `acks-influence` (ApplicationV2 + HandlebarsApplicati
 | `scripts/formation-app.mjs` | The formation window (GM controls, player read-only). |
 | `scripts/encounter-zone.mjs` | `acks-formation.encounterZone` RegionBehavior subtype (table UUID + cadence overrides) and point-in-region lookup for the party token (core `testPoint` when available, manual shape math as a headless fallback). |
 | `scripts/scene-sync.mjs` | Mapper-gated fog (`scene.fog.exploration`, original value stashed in a scene flag) and party-token light emission mirroring lit sources. Reconciled by the primary GM after every formation change (idempotent, compare-before-write). |
+| `scripts/socket.mjs` | socketlib registration (`socketlib.ready`) and a queue so handlers can register at import time; exposes `getSocket`/`registerHandler`. |
 | `scripts/module.mjs` | Settings, hooks, scene-control button, `/formation` chat command, public API. |
 
 ## Data flow

module.json

@@ -2,7 +2,7 @@
   "id": "acks-formation",
   "title": "ACKS II — Exploration Formations",
   "description": "Condenses the party into exploration formations for cleaner dungeon delving. Members join a formation and are represented on the canvas by a single party token that moves at exploration speed. Movement automatically consumes dungeon turns (10 minutes), driving light-source burn, rest requirements, wandering-monster checks, spell-duration expiry, and ration tracking per the ACKS II dungeon delve sequence of play.",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "socket": true,
   "compatibility": {
     "minimum": "14",
@@ -76,6 +76,32 @@
           "minimum": "13"
         }
       }
+    ],
+    "requires": [
+      {
+        "id": "lib-wrapper",
+        "type": "module",
+        "reason": "Wraps ruler measurement labels safely alongside other ruler modules.",
+        "compatibility": {
+          "minimum": "1.12.0"
+        }
+      },
+      {
+        "id": "socketlib",
+        "type": "module",
+        "reason": "Routes player action requests and fog-reload messages between clients.",
+        "compatibility": {
+          "minimum": "1.1.0"
+        }
+      },
+      {
+        "id": "simple-timekeeping",
+        "type": "module",
+        "reason": "Shared world clock, calendar, and scene-darkness synchronisation for dungeon turns.",
+        "compatibility": {
+          "minimum": "2.0.0"
+        }
+      }
     ]
   },
   "url": "https://github.com/NocTempre/acks-formation",

scripts/map-items.mjs

@@ -7,6 +7,7 @@ import {
   mapperIsProficient,
   updateFormation,
 } from "./formation-model.mjs";
+import { getSocket, registerHandler } from "./socket.mjs";
 
 /**
  * Maps as objects (FOG-DESIGN.md Phases 1–2).
@@ -34,7 +35,6 @@ import {
  */
 
 export const MAP_FLAG = "map";
-export const SOCKET_NAME = `module.${MODULE_ID}`;
 
 function loc(key, data = {}) {
   return game.i18n.format(`ACKS-FORMATION.${key}`, data);
@@ -360,8 +360,11 @@ export async function anchorMap(formation, itemUuid) {
   }
 
   await item.setFlag(MODULE_ID, MAP_FLAG, { ...map, anchored: true });
-  game.socket.emit(SOCKET_NAME, { action: "reloadFog", sceneId });
-  await reloadFog(sceneId);
+  // Reload fog on every client (executeForEveryone runs here too, so the
+  // guard inside reloadFog handles clients not viewing this scene).
+  const socket = getSocket();
+  if (socket) await socket.executeForEveryone("reloadFog", sceneId);
+  else await reloadFog(sceneId);
   await announce(formation, loc("map.anchored", { name: item.name }));
   if (map.quality === "distorted") {
     await announce(formation, loc("map.anchoredDistorted"), { whisper: true });
@@ -417,10 +420,7 @@ async function reloadFog(sceneId) {
   canvas.perception.initialize();
 }
 
+/** Register the fog-reload handler with socketlib. */
 export function registerMapSocket() {
-  game.socket.on(SOCKET_NAME, (data) => {
-    if (data?.action === "reloadFog") {
-      reloadFog(data.sceneId).catch((err) => console.error(`${MODULE_ID} | fog reload failed`, err));
-    }
-  });
+  registerHandler("reloadFog", reloadFog);
 }

scripts/measure-fuzz.mjs

@@ -1,4 +1,4 @@
-/* global game, canvas, CONFIG, Hooks */
+/* global game, canvas, CONFIG, libWrapper */
 import { MODULE_ID } from "./constants.mjs";
 
 /**
@@ -12,9 +12,9 @@ import { MODULE_ID } from "./constants.mjs";
  * - mode "unknown" (no working mapper): distances show as "?".
  *
  * GMs always see true values. Both the ruler tool (CONFIG.Canvas.rulerClass)
- * and token drag measurement (CONFIG.Token.rulerClass) are wrapped by
- * subclassing whatever class is configured at setup and overriding the
- * documented protected `_getWaypointLabelContext`.
+ * and token drag measurement (CONFIG.Token.rulerClass) have their documented
+ * protected `_getWaypointLabelContext` wrapped via **libWrapper** (WRAPPER
+ * type), so other ruler modules that touch the same method still compose.
  *
  * Honest limits: the canvas geometry itself stays exact — players can still
  * count grid squares. This is a deterrent and a mood-setter.
@@ -77,23 +77,26 @@ function applyFuzz(context, waypoint) {
 }
 
 /**
- * Wrap the configured ruler classes. Called once at "setup" so other modules'
- * init-time replacements are respected (we extend whatever is configured).
+ * Wrap the configured ruler classes' label builder. Called once at "setup" so
+ * other modules' init-time class replacements are already in place — libWrapper
+ * targets the live prototype method, letting every wrapper in the chain run.
  */
 export function registerFuzzyRulers() {
-  const RulerBase = CONFIG.Canvas.rulerClass;
-  CONFIG.Canvas.rulerClass = class FuzzyRuler extends RulerBase {
-    /** @override */
-    _getWaypointLabelContext(waypoint, state) {
-      return applyFuzz(super._getWaypointLabelContext(waypoint, state), waypoint);
-    }
+  const wrap = function (wrapped, waypoint, state) {
+    return applyFuzz(wrapped(waypoint, state), waypoint);
   };
-
-  const TokenRulerBase = CONFIG.Token.rulerClass;
-  CONFIG.Token.rulerClass = class FuzzyTokenRuler extends TokenRulerBase {
-    /** @override */
-    _getWaypointLabelContext(waypoint, state) {
-      return applyFuzz(super._getWaypointLabelContext(waypoint, state), waypoint);
+  // CONFIG paths are resolved by libWrapper from global scope, so we wrap
+  // whatever ruler class is live at setup without needing its name to be a
+  // global (v14 ruler classes live under foundry.canvas.*).
+  const targets = [
+    "CONFIG.Canvas.rulerClass.prototype._getWaypointLabelContext",
+    "CONFIG.Token.rulerClass.prototype._getWaypointLabelContext",
+  ];
+  for (const target of targets) {
+    try {
+      libWrapper.register(MODULE_ID, target, wrap, "WRAPPER");
+    } catch (err) {
+      console.error(`${MODULE_ID} | could not wrap ${target}`, err);
     }
-  };
+  }
 }

scripts/player-requests.mjs

@@ -1,7 +1,6 @@
 /* global game, foundry, ChatMessage, ui */
-import { MODULE_ID } from "./constants.mjs";
 import { getFormation } from "./formation-model.mjs";
-import { SOCKET_NAME } from "./map-items.mjs";
+import { getSocket, registerHandler } from "./socket.mjs";
 import { rollPartyCheck } from "./party-rolls.mjs";
 import { addLight, addSpell, advanceTurns } from "./turn-engine.mjs";
 
@@ -18,7 +17,7 @@ import { addLight, addSpell, advanceTurns } from "./turn-engine.mjs";
  * what; check results still go to the GM per the usual secrecy rules.
  */
 
-const REQUEST_ACTION = "partyRequest";
+const REQUEST_HANDLER = "partyRequest";
 
 function loc(key, data = {}) {
   return game.i18n.format(`ACKS-FORMATION.${key}`, data);
@@ -81,9 +80,17 @@ async function executeRequest(formation, user, type, payload) {
   }
 }
 
+/** socketlib handler: runs on the active GM with the declaring user's id. */
+async function handlePartyRequest(formationId, type, payload, userId) {
+  const formation = getFormation(formationId);
+  const user = game.users.get(userId);
+  if (!formation || !user) return;
+  await executeRequest(formation, user, type, payload ?? {});
+}
+
 /**
  * Declare a party action. GMs execute directly; players relay to the active
- * GM via the module socket.
+ * GM via socketlib (executeAsGM routes to exactly one GM client).
  */
 export async function requestPartyAction(formationId, type, payload = {}) {
   const formation = getFormation(formationId);
@@ -92,30 +99,16 @@ export async function requestPartyAction(formationId, type, payload = {}) {
     await executeRequest(formation, game.user, type, payload);
     return;
   }
-  if (!game.users.activeGM) {
+  const socket = getSocket();
+  if (!socket || !game.users.activeGM) {
     ui.notifications.warn(game.i18n.localize("ACKS-FORMATION.request.noGM"));
     return;
   }
-  game.socket.emit(SOCKET_NAME, {
-    action: REQUEST_ACTION,
-    formationId,
-    type,
-    payload,
-    userId: game.user.id,
-  });
+  await socket.executeAsGM(REQUEST_HANDLER, formationId, type, payload, game.user.id);
   ui.notifications.info(game.i18n.localize("ACKS-FORMATION.request.sent"));
 }
 
-/** GM-side socket listener (registered on every client; guards internally). */
+/** Register the GM-side request handler with socketlib. */
 export function registerRequestSocket() {
-  game.socket.on(SOCKET_NAME, (data) => {
-    if (data?.action !== REQUEST_ACTION) return;
-    if (!game.users.activeGM?.isSelf) return;
-    const formation = getFormation(data.formationId);
-    const user = game.users.get(data.userId);
-    if (!formation || !user) return;
-    executeRequest(formation, user, data.type, data.payload ?? {}).catch((err) =>
-      console.error(`${MODULE_ID} | player request failed`, err),
-    );
-  });
+  registerHandler(REQUEST_HANDLER, handlePartyRequest);
 }

scripts/socket.mjs

@@ -0,0 +1,34 @@
+/* global Hooks, socketlib */
+import { MODULE_ID } from "./constants.mjs";
+
+/**
+ * All cross-client messaging goes through **socketlib**: named handlers with
+ * GM routing, instead of a hand-rolled `game.socket` channel. Handlers are
+ * registered on the `socketlib.ready` hook (fires after init, before ready);
+ * the two consumers register their own functions via `onSocketReady`.
+ */
+
+let socket = null;
+const pending = [];
+
+/** The socketlib socket for this module, or null before socketlib.ready. */
+export function getSocket() {
+  return socket;
+}
+
+/**
+ * Register a socket handler function. Safe to call at import time: if the
+ * socket is not up yet the registration is queued until `socketlib.ready`.
+ * @param {string} name  Unique handler name.
+ * @param {Function} fn  Handler; its return value is delivered to callers.
+ */
+export function registerHandler(name, fn) {
+  if (socket) socket.register(name, fn);
+  else pending.push([name, fn]);
+}
+
+Hooks.once("socketlib.ready", () => {
+  socket = socketlib.registerModule(MODULE_ID);
+  for (const [name, fn] of pending) socket.register(name, fn);
+  pending.length = 0;
+});