hooks-lib/README.md

Foundry Hooks Lib (foundry-hooks-lib)

Foundry VTT module (id: foundry-hooks-lib) that turns Foundry's hook soup (dnd5e, combat, token updates, canvas/UI) into a clean, normalized event stream. Library-only — no UI, no settings, no chat output. Designed to be consumed by any module that wants Foundry events in a stable shape.

Part of the Foundry module split (battle-focus + its-achievable + this lib). Consumers today: battle-focus (encounter + journal + summary) and its-achievable (achievements, rewards, wall, HUD). System-specific knowledge (dnd5e rolls, PF2e, etc.) lives in separate adapter repos that declare Foundry + system version ranges they support.

v0.3.0 — module id renamed (hax-hooks-lib → foundry-hooks-lib)

v0.2.0 is a complete rewrite. v0.1.0 shipped as a curated-event catalog (a list of hand-written handlers for 18 specific Foundry events). v0.2.0 replaces that with a generic facade:

• Subscribes to every relevant Foundry hook (combat lifecycle, all document CRUD, canvas/UI, dnd5e v2 roll hooks, etc.).
• Emits a uniform envelope — {ts, hook, args} — with no domain interpretation.
• Consumers write queries against the envelope. "When bob takes damage" is a consumer-side query, not a hook name the library knows about.
• System-specific derived events (e.g. "dnd5e attack roll") live in separate adapter repos. Adapters register a manifest with Foundry + system version ranges; the library evaluates at ready and loads matching adapters.

Why this shape: Foundry's hook names and arities change between versions. The library absorbs that churn (§9 + §10 of the contract) so consumers don't have to rewrite every Foundry upgrade.

Status

v0.2.0 — generic facade per docs/HOOK_CONTRACT.md. Smoke test: 554/554 assertions. Perf test: median 0.0003ms/fire (333× under the 0.1ms budget).

Envelope shape

Every fire produces exactly one envelope:

{
  ts:   1719000000000,    // epoch ms when Foundry fired
  hook: "updateActor",    // the Foundry hook name (normalized; see §9)
  args: [doc, change, options, userId]  // positional args, verbatim
}

That's it. No kind, no normalized fields, no consumer metadata. Consumers that want {kind, actorId, delta} build that themselves from args. This is intentional: the library is the boundary that absorbs Foundry version churn.

Public API (on game.modules.get("foundry-hooks-lib").api)

import { subscribe, subscribeMany, subscribeAll } from
  game.modules.get("foundry-hooks-lib").api;

// Single hook:
const unsub = subscribe("updateActor", (envelope) => {
  const [actor, change] = envelope.args;
  // ...
});

// Batch subscribe (atomic):
subscribeMany({
  updateActor: handleActorUpdate,
  createToken: handleTokenCreate,
});

// Every hook (for audit logs):
subscribeAll((envelope) => log(envelope));

// One-shot cleanup:
unsub();   // or unsubscribeAll() to purge everything

System adapters

A system adapter is a separate Foundry module. At its init, it calls:

hooksLib.api.registerSystemAdapter({
  id: "foundry-hooks-dnd5e",
  moduleId: "foundry-hooks-dnd5e",
  system: { id: "dnd5e", versions: ">=5.2.0 <5.3.0" },
  foundryVersions: ">=13 <15",
  factory: () => [ /* derived-event registrations */ ],
});

The library evaluates the manifest against game.system.id + version and game.version at ready. Matching adapter factories are called once. Non-matching adapters log a warning naming the version mismatch (or silently skip for non-matching system).

Subscribed hook set (v0.2.0)

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, renderChatInput, renderJournalPageSheet, rtcSettingsChanged), and more. Full list: scripts/internal/registered-hooks.js.

Error containment

If a consumer callback throws, the library catches it, logs via console.error with the [foundry-hooks-lib] prefix and the hook name, and continues dispatching to subsequent callbacks. Errors never propagate to Foundry's hook chain.

Tests

npm test                # 554 assertions in <2s, no Foundry needed (smoke)
npm run test:foundry    # 30 assertions in <15s, Playwright + live Foundry
npm run test:perf       # median 0.0003ms/fire, heap delta check
npm run test:all        # all three

See tests/PLAN.md for what we test and what we don't. The test:foundry runner connects to FOUNDRY_URL (defaults to http://localhost:30000), signs in as Gamemaster, waits for the library's mod.api.isReady() === true, and exercises the live envelope dispatch chain end-to-end.

Architecture notes

• One envelope shape, one dispatcher. Adding a new Foundry hook is one entry in scripts/internal/registered-hooks.js. No new file.
• System adapters are repos, not files. Each system's derived knowledge is its own module with its own version cadence.
• Anti-corruption (§9-§10): library subscribes to BOTH v13 and v14 hook names where applicable; consumers see stable envelope names.
• Async dispatch (microtask) by default. pre-* + combat* + applyActiveEffect + get*Context dispatch sync because their return values matter.

Dependencies

None. Library-only; system adapters depend on this, not the other way around.

Maintained by Kaysser Taylor + Hermes