Epic: Phase 2 Extension Hooks and Plugin Boundary

[keepithandy]

Phase

Phase 2 — Extensibility

Goal

Design the first lightweight extension hook boundary for Depth Engine without turning the starter into a framework.

This issue should define where future systems can plug in and where the core should remain boring, readable, and generic.

Why this matters

Once people start using Depth Engine for different RPG ideas, they will want to add custom rewards, combat modifiers, UI panels, events, or content rules. Hooks can make that possible without people editing every engine file by hand.

Proposed work

• Identify safe hook points in the current engine loop.
• Candidate hook points: before fight, after fight, before reward, after reward, before save, after load, before render, after render.
• Define a small hook registration shape.
• Decide whether hooks are global functions, arrays, named events, or metadata-driven.
• Document what hook callbacks can and cannot mutate.
• Add smoke tests proving hooks are opt-in and do nothing by default.
• Add one tiny example hook fixture in smoke only, not live Rat Cellar gameplay.
• Keep the base engine readable for beginners.

Acceptance checks

• Hook design exists before broad implementation.
• Default behavior is unchanged when no hooks are registered.
• Rat Cellar remains playable.
• Hooks are generic and not Rat Cellar-specific.
• Smokes prove no-op default behavior.
• Mutating hooks are clearly separated from read-only hooks if both are allowed.

Guardrails

• Do not add npm packages.
• Do not create a plugin marketplace here.
• Do not let hooks silently mutate saves unless explicitly designed.
• Do not make combat harder/easier as part of the hook foundation.
• Do not add a bunch of live example plugins yet.

Suggested follow-up slices

• Hook boundary design doc.
• No-op hook registry helper.
• Smoke-only hook fixture.
• One safe read-only lifecycle hook.
• Later plugin example after the core contract is stable.