From 2fabb5e98f05bb944b36317cb2db2c4eb32fedd3 Mon Sep 17 00:00:00 2001
From: Kaysser Kayyali <kaykayyali@gmail.com>
Date: Sat, 20 Jun 2026 22:49:32 -0400
Subject: [PATCH] v0.4.1: drop renderChatMessage, register
 renderChatMessageHTML
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Foundry v13 deprecated renderChatMessage in favor of
renderChatMessageHTML (which passes an HTMLElement, not a jQuery
wrapper). Subscribing to the deprecated hook re-emits Foundry's
compatibility warning on every chat render in worlds still running
v13.351 (the foundry-hooks-lib module's tests run against such a
world).

v0.3.0 already narrowed scope to Foundry v14 only (HOOK_CONTRACT.md
section 9), but the registered hook set still included
renderChatMessage as a legacy fallback. There is no Foundry v14
hook by that name, so the entry was dead weight — and worse, any
v13.351 world running the v14-only library would still see the
deprecation warning every chat render.

Changes:
- registered-hooks.js: replace renderChatMessage entry with
  renderChatMessageHTML. Update arg shape (HTML passes HTMLElement,
  not jQuery). Add comment explaining the deprecation.
- README.md / HOOK_CONTRACT.md section 6: list renderChatMessageHTML
  instead of renderChatMessage.
- tests/verify-hooks-lib.mjs: update stub arg shape from
  [{id}, {}, {}] to [{id}, {}] (v14 signature).

Verification:
- node tests/verify-hooks-lib.mjs: 546/546 (unchanged)
- node tests/perf.mjs: 6/6, median 0.0003ms/fire (well under
  the 0.1ms budget in HOOK_CONTRACT.md section 7)
- node --check on all scripts + tests: clean

Push: Gitea only.

Note: battle-focus's own main.js line 144 still has a
Hooks.on('renderChatMessage', ...) listener for its 'Open in
Journal' button wiring. That listener fires the deprecation warning
on the user's console. Fixing it is a battle-focus change, out of
scope for this turn (hooks-lib only).
---
 README.md                            | 2 +-
 docs/HOOK_CONTRACT.md                | 2 +-
 scripts/internal/registered-hooks.js | 9 ++++++++-
 tests/verify-hooks-lib.mjs           | 2 +-
 4 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index a0709b9..7ffc99f 100644
--- a/README.md
+++ b/README.md
@@ -131,7 +131,7 @@ Lifecycle, document CRUD (Actor/Token/Item/Scene/JournalEntry/
 ActiveEffect/Combat/Combatant), combat lifecycle, chat & rolls (incl.
 dnd5e v2 roll hooks), canvas/scene/UI (canvasInit/Ready/Pan, controlToken,
 hoverToken, targetToken, lighting/sightRefresh, collapseSidebar,
-changeSidebarTab, getSceneControlButtons, renderChatMessage,
+changeSidebarTab, getSceneControlButtons, renderChatMessageHTML,
 renderChatInput, renderJournalPageSheet, rtcSettingsChanged), and more.
 Full list: `scripts/internal/registered-hooks.js`.
 
diff --git a/docs/HOOK_CONTRACT.md b/docs/HOOK_CONTRACT.md
index 6e42caa..74b80f6 100644
--- a/docs/HOOK_CONTRACT.md
+++ b/docs/HOOK_CONTRACT.md
@@ -299,7 +299,7 @@ hooks. Each registration uses the wrapper from §2 to produce envelopes.
 - `lightingRefresh`, `sightRefresh`
 - `collapseSidebar`, `changeSidebarTab`, `getSceneControlButtons`
 - `collapseSceneNavigation`
-- `renderChatMessage`, `renderChatInput`, `renderJournalPageSheet`
+- `renderChatMessageHTML`, `renderChatInput`, `renderJournalPageSheet`
 - `initializePointSourceShaders`
 - `rtcSettingsChanged`
 
diff --git a/scripts/internal/registered-hooks.js b/scripts/internal/registered-hooks.js
index 94e0234..c2014fa 100644
--- a/scripts/internal/registered-hooks.js
+++ b/scripts/internal/registered-hooks.js
@@ -93,8 +93,15 @@ export const HOOK_REGISTRY = [
   { envelope: "combatInactive",      mode: "sync",  raw: ["updateCombat"], synthesized: true },
 
   // --- Chat & rolls ---
+  // Note: renderChatMessage (the v13 jQuery-wrapper hook) is
+  // intentionally NOT registered. Foundry v13 deprecated it in favor
+  // of renderChatMessageHTML (HTMLElement). Consumers wanting chat
+  // message rendering events should subscribe to renderChatMessageHTML
+  // (or renderJournalPageSheet for journal pages). Subscribing to the
+  // deprecated hook here would re-emit Foundry's compatibility warning
+  // on every chat render in worlds still running v13.351.
   { envelope: "createChatMessage",   mode: "async", raw: ["createChatMessage"] },
-  { envelope: "renderChatMessage",   mode: "sync",  raw: ["renderChatMessage"] },
+  { envelope: "renderChatMessageHTML", mode: "sync", raw: ["renderChatMessageHTML"] },
   { envelope: "renderChatInput",     mode: "sync",  raw: ["renderChatInput"] },
   { envelope: "dnd5e.rollAttackV2",  mode: "async", raw: ["dnd5e.rollAttackV2"] },
   { envelope: "dnd5e.rollDamageV2",  mode: "async", raw: ["dnd5e.rollDamageV2"] },
diff --git a/tests/verify-hooks-lib.mjs b/tests/verify-hooks-lib.mjs
index a01d418..cb79455 100644
--- a/tests/verify-hooks-lib.mjs
+++ b/tests/verify-hooks-lib.mjs
@@ -516,7 +516,7 @@ function syntheticArgsFor(rawName) {
   if (rawName === "collapseSidebar" || rawName === "collapseSceneNavigation") return [{}, true];
   if (rawName === "changeSidebarTab") return [{}];
   if (rawName === "getSceneControlButtons") return [[]];
-  if (rawName === "renderChatMessage") return [{ id: "m1" }, {}, {}];
+  if (rawName === "renderChatMessageHTML") return [{ id: "m1" }, {}];
   if (rawName === "renderChatInput") return [{}, {}, {}];
   if (rawName === "renderJournalPageSheet") return [{}, {}, {}];
   if (rawName === "initializePointSourceShaders") return [{}];