docs: add death timer implementation plan

2026-04-12 01:05:36 -04:00 · 2026-04-12 01:05:36 -04:00 · 4c10fe80ac
commit 4c10fe80ac
parent 44b482e173
1 changed files with 960 additions and 0 deletions
--- a/docs/plans/2026-04-12-death-timer.md
+++ b/docs/plans/2026-04-12-death-timer.md
@ -0,0 +1,960 @@
 # Death Timer Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Implement Shadowdark's dying mechanic — HP→0 starts a dying countdown (1d4+CON rounds), party turns tick the timer, DM can roll d20 each turn for recovery (18+ = stand at 1 HP), timer expiry marks permanent death with a DM-only Revive button.
 **Architecture:** Dying state lives in `character_conditions` (existing table) as a "Dying" row with `rounds_remaining`. Permanent death is a new `is_dead BOOLEAN` column on `characters` (migration 004). Server drives all state: HP PATCH triggers dying start/clear, `initiative:next` ticks the timer, `death:recovery-roll` handles recovery rolls. `character:updated` broadcasts include a `conditions` array so clients always have current state.
 **Tech Stack:** Express REST (PATCH `/characters/:id`), Socket.IO (`death:recovery-roll`), MariaDB, React + CSS Modules
 ---
 ## File Map
 | File | Change |
 |---|---|
 | `server/migrations/004_death_timer.sql` | New — adds `is_dead` column |
 | `server/src/routes/characters.ts` | `enrichCharacters` includes conditions; PATCH adds conditions to response, dying logic, `is_dead` in allowedFields |
 | `server/src/routes/initiative.ts` | `initiative:next` ticks Dying timers when flipping to party |
 | `server/src/socket.ts` | New `death:recovery-roll` handler |
 | `client/src/types.ts` | Add `is_dead` and `conditions` to `Character` |
 | `client/src/components/CharacterCard.tsx` | Dying border + 💀N countdown; dead state; Revive button (DM only) |
 | `client/src/components/CharacterCard.module.css` | Dying pulse animation; dead mute; dying label; revive button styles |
 | `client/src/components/InitiativeTracker.tsx` | Dying label + Roll Recovery button in ActivePhase |
 ---
 ## Task 1: DB Migration — Add is_dead column
 **Files:**
 - Create: `server/migrations/004_death_timer.sql`
 - [ ] **Step 1: Write the migration**
 Create `server/migrations/004_death_timer.sql`:
 ```sql
 ALTER TABLE characters ADD COLUMN is_dead BOOLEAN NOT NULL DEFAULT FALSE;
 ```
 - [ ] **Step 2: Apply the migration**
 Restart the server (migrations run automatically on startup):
 ```bash
 cd server && npm run dev
 ```
 Expected: server logs `Running migration: 004_death_timer.sql` then `Migrations complete.`
 - [ ] **Step 3: Verify column exists**
 ```bash
 docker exec -it darkwatch-maria mariadb -u darkwatch -pdarkwatch darkwatch \
  -e "DESCRIBE characters;" | grep is_dead
 ```
 Expected output contains: `is_dead | tinyint(1) | NO | | 0 |`
 - [ ] **Step 4: Commit**
 ```bash
 git add server/migrations/004_death_timer.sql
 git commit -m "feat: add is_dead column to characters (death timer migration 004)"
 ```
 ---
 ## Task 2: Enrich characters with conditions + update client types
 **Files:**
 - Modify: `server/src/routes/characters.ts`
 - Modify: `client/src/types.ts`
 The `character:updated` socket event currently sends a flat character row (no stats/gear/talents). We extend it to also include `conditions` so the client always has up-to-date dying state. The existing merge pattern `{ ...c, ...data }` in `CampaignView.tsx:131` handles partial updates safely.
 - [ ] **Step 1: Add conditions to enrichCharacters in characters.ts**
 `enrichCharacters` (lines 51–75 of `server/src/routes/characters.ts`) — add a conditions fetch and include it in the return value:
 ```typescript
 async function enrichCharacters(characters: RowDataPacket[]) {
  return Promise.all(
    characters.map(async (char) => {
      const [stats] = await db.execute<RowDataPacket[]>(
        "SELECT stat_name, value FROM character_stats WHERE character_id = ?",
        [char.id]
      );
      const [gear] = await db.execute<RowDataPacket[]>(
        "SELECT * FROM character_gear WHERE character_id = ?",
        [char.id]
      );
      const [talents] = await db.execute<RowDataPacket[]>(
        "SELECT * FROM character_talents WHERE character_id = ?",
        [char.id]
      );
      const [conditions] = await db.execute<RowDataPacket[]>(
        "SELECT * FROM character_conditions WHERE character_id = ?",
        [char.id]
      );
      return {
        ...char,
        overrides: parseJson(char.overrides),
        stats,
        gear: parseGear(gear),
        talents: parseTalents(talents),
        conditions,
      };
    })
  );
 }
 ```
 - [ ] **Step 2: Add conditions to the PATCH handler response**
 The PATCH handler (lines 215–227 of `server/src/routes/characters.ts`) fetches `SELECT * FROM characters` then builds an enriched object. Replace that block to also fetch conditions:
 ```typescript
 const [rows] = await db.execute<RowDataPacket[]>(
  "SELECT * FROM characters WHERE id = ?",
  [id]
 );
 const [conditions] = await db.execute<RowDataPacket[]>(
  "SELECT * FROM character_conditions WHERE character_id = ?",
  [id]
 );
 const enriched = {
  ...rows[0],
  overrides: parseJson(rows[0].overrides),
  conditions,
 };
 const io: Server = req.app.get("io");
 broadcastToCampaign(io, Number(rows[0].campaign_id), "character:updated", enriched);
 res.json(enriched);
 ```
 - [ ] **Step 3: Update client types**
 In `client/src/types.ts`, add `is_dead` and `conditions` to the `Character` interface (after `torch_lit_at`):
 ```typescript
 export interface Character {
  id: number;
  campaign_id: number;
  user_id?: number | null;
  created_by: string;
  name: string;
  class: string;
  ancestry: string;
  level: number;
  xp: number;
  hp_current: number;
  hp_max: number;
  ac: number;
  alignment: string;
  title: string;
  notes: string;
  background: string;
  deity: string;
  languages: string;
  gp: number;
  sp: number;
  cp: number;
  gear_slots_max: number;
  overrides: Record<string, unknown>;
  color: string;
  luck_token: number;
  torch_lit_at: string | null;
  is_dead: boolean;
  stats: Stat[];
  gear: Gear[];
  talents: Talent[];
  conditions: Condition[];
 }
 ```
 - [ ] **Step 4: Verify TypeScript compiles**
 ```bash
 cd client && npx tsc --noEmit 2>&1 | head -30
 ```
 Expected: no new errors. (Pre-existing errors unrelated to this feature are OK.)
 ```bash
 cd server && npx tsc --noEmit 2>&1 | head -30
 ```
 Expected: no new errors.
 - [ ] **Step 5: Commit**
 ```bash
 git add server/src/routes/characters.ts client/src/types.ts
 git commit -m "feat: include conditions in character responses; add is_dead + conditions to Character type"
 ```
 ---
 ## Task 3: Auto-start/clear dying on HP change
 **Files:**
 - Modify: `server/src/routes/characters.ts`
 When the HP PATCH writes `hp_current <= 0` and the character isn't already dying or dead, insert a Dying condition (1d4 + CON modifier rounds, minimum 1). When HP goes above 0, delete any Dying condition.
 - [ ] **Step 1: Add rollDice import**
 At the top of `server/src/routes/characters.ts`, add:
 ```typescript
 import { rollDice } from "../dice.js";
 ```
 - [ ] **Step 2: Add is_dead to allowedFields in PATCH handler**
 In the `allowedFields` array (around line 185), add `"is_dead"`:
 ```typescript
 const allowedFields = [
  "name", "class", "ancestry", "level", "xp", "hp_current", "hp_max",
  "ac", "alignment", "title", "notes", "background", "deity", "languages",
  "gp", "sp", "cp", "gear_slots_max", "overrides", "color", "luck_token",
  "torch_lit_at", "is_dead",
 ];
 ```
 This allows the Revive button (Task 6) to send `{ is_dead: false, hp_current: 1 }` in a single PATCH.
 - [ ] **Step 3: Insert dying state management block**
 After the `if (updateResult.affectedRows === 0)` check (around line 213) and before the `SELECT * FROM characters` fetch, insert:
 ```typescript
 // Auto-start or clear Dying condition based on HP change
 if (req.body.hp_current !== undefined) {
  const newHp = Number(req.body.hp_current);
  if (newHp <= 0) {
    // Check if already dying or permanently dead
    const [dyingRows] = await db.execute<RowDataPacket[]>(
      "SELECT id FROM character_conditions WHERE character_id = ? AND name = 'Dying'",
      [id]
    );
    const [deadRows] = await db.execute<RowDataPacket[]>(
      "SELECT is_dead FROM characters WHERE id = ?",
      [id]
    );
    const isAlreadyDying = dyingRows.length > 0;
    const isAlreadyDead = Boolean(deadRows[0]?.is_dead);
    if (!isAlreadyDying && !isAlreadyDead) {
      // Roll 1d4, add CON modifier, clamp to minimum 1
      const d4 = rollDice("1d4");
      const [statRows] = await db.execute<RowDataPacket[]>(
        "SELECT value FROM character_stats WHERE character_id = ? AND stat_name = 'CON'",
        [id]
      );
      const conValue = (statRows[0]?.value as number) ?? 10;
      const conMod = Math.floor((conValue - 10) / 2);
      const roundsRemaining = Math.max(1, d4.total + conMod);
      await db.execute(
        "INSERT INTO character_conditions (character_id, name, description, rounds_remaining) VALUES (?, 'Dying', '', ?)",
        [id, roundsRemaining]
      );
    }
  } else {
    // HP above 0: remove any Dying condition (character was healed)
    await db.execute(
      "DELETE FROM character_conditions WHERE character_id = ? AND name = 'Dying'",
      [id]
    );
  }
 }
 ```
 - [ ] **Step 4: Verify TypeScript compiles**
 ```bash
 cd server && npx tsc --noEmit 2>&1 | head -20
 ```
 Expected: no errors.
 - [ ] **Step 5: Smoke-test manually**
 With server running: use the DM login, open a campaign, set a character's HP to 0 via the HP bar. Reload the page and verify a Dying condition with rounds_remaining exists in the DB:
 ```bash
 docker exec -it darkwatch-maria mariadb -u darkwatch -pdarkwatch darkwatch \
  -e "SELECT * FROM character_conditions WHERE name = 'Dying';"
 ```
 Set HP back to 1 — verify the row is gone.
 - [ ] **Step 6: Commit**
 ```bash
 git add server/src/routes/characters.ts
 git commit -m "feat: auto-start Dying condition when HP hits 0, clear when HP recovers"
 ```
 ---
 ## Task 4: Tick death timer on party turn
 **Files:**
 - Modify: `server/src/routes/initiative.ts`
 When `initiative:next` flips the side to "party", decrement all Dying conditions for characters in the campaign. Conditions at 0 mark the character dead.
 - [ ] **Step 1: Add tickDeathTimers helper**
 Add this function above `registerInitiativeHandlers` in `server/src/routes/initiative.ts`:
 ```typescript
 async function tickDeathTimers(io: Server, campaignId: number): Promise<void> {
  // Find all living characters in this campaign with a Dying condition
  const [charRows] = await db.execute<RowDataPacket[]>(
    "SELECT id FROM characters WHERE campaign_id = ? AND is_dead = FALSE",
    [campaignId]
  );
  if (charRows.length === 0) return;
  const charIds = (charRows as RowDataPacket[]).map((r) => r.id as number);
  const placeholders = charIds.map(() => "?").join(", ");
  const [dyingRows] = await db.execute<RowDataPacket[]>(
    `SELECT * FROM character_conditions WHERE name = 'Dying' AND character_id IN (${placeholders})`,
    charIds
  );
  if (dyingRows.length === 0) return;
  for (const condition of dyingRows) {
    const newRounds = (condition.rounds_remaining as number) - 1;
    if (newRounds <= 0) {
      // Timer expired — remove Dying condition and mark permanently dead
      await db.execute("DELETE FROM character_conditions WHERE id = ?", [condition.id]);
      await db.execute("UPDATE characters SET is_dead = TRUE WHERE id = ?", [condition.character_id]);
    } else {
      await db.execute(
        "UPDATE character_conditions SET rounds_remaining = ? WHERE id = ?",
        [newRounds, condition.id]
      );
    }
    // Broadcast updated character to the campaign room
    const [charRow] = await db.execute<RowDataPacket[]>(
      "SELECT * FROM characters WHERE id = ?",
      [condition.character_id]
    );
    const [updatedConditions] = await db.execute<RowDataPacket[]>(
      "SELECT * FROM character_conditions WHERE character_id = ?",
      [condition.character_id]
    );
    io.to(`campaign:${campaignId}`).emit("character:updated", {
      ...charRow[0],
      conditions: updatedConditions,
    });
  }
 }
 ```
 - [ ] **Step 2: Call tickDeathTimers in initiative:next handler**
 In the `initiative:next` handler (around line 292), after `broadcast(io, socket, data.campaignId, updated, true);` and before the `} catch`, add:
 ```typescript
 // Tick death timers when the party's turn begins
 const flippedCombat = updated.find((c) => c.id === data.combatId);
 if (flippedCombat && flippedCombat.current_side === "party") {
  await tickDeathTimers(io, data.campaignId);
 }
 ```
 - [ ] **Step 3: Verify TypeScript compiles**
 ```bash
 cd server && npx tsc --noEmit 2>&1 | head -20
 ```
 Expected: no errors.
 - [ ] **Step 4: Smoke-test manually**
 Set a character's HP to 0 (gains Dying condition). Start combat with that character. Advance turns until the enemy side ends and the party side begins. Check that `rounds_remaining` decremented in the DB:
 ```bash
 docker exec -it darkwatch-maria mariadb -u darkwatch -pdarkwatch darkwatch \
  -e "SELECT * FROM character_conditions WHERE name = 'Dying';"
 ```
 - [ ] **Step 5: Commit**
 ```bash
 git add server/src/routes/initiative.ts
 git commit -m "feat: tick Dying timer on party turn; mark is_dead when timer expires"
 ```
 ---
 ## Task 5: death:recovery-roll socket handler
 **Files:**
 - Modify: `server/src/socket.ts`
 New socket event emitted by the client when the DM clicks Roll Recovery. Verifies DM role, verifies character is Dying, rolls d20, logs it as a "Death Save" roll, and on 18+ heals to 1 HP and clears the Dying condition.
 - [ ] **Step 1: Add handler in socket.ts**
 Inside `io.on("connection", ...)`, add after the `atmosphere:update` handler (before `socket.on("disconnect", ...)`):
 ```typescript
 socket.on("death:recovery-roll", async (data: {
  campaignId: number;
  characterId: number;
 }) => {
  const userId = socket.data.user?.userId;
  // Verify caller is DM
  const [memberRows] = await db.execute<RowDataPacket[]>(
    "SELECT role FROM campaign_members WHERE campaign_id = ? AND user_id = ?",
    [data.campaignId, userId]
  );
  if (memberRows.length === 0 || memberRows[0].role !== "dm") return;
  // Verify character has a Dying condition
  const [dyingRows] = await db.execute<RowDataPacket[]>(
    "SELECT id FROM character_conditions WHERE character_id = ? AND name = 'Dying'",
    [data.characterId]
  );
  if (dyingRows.length === 0) return;
  // Get character info for roll log
  const [charRows] = await db.execute<RowDataPacket[]>(
    "SELECT name, color, campaign_id FROM characters WHERE id = ?",
    [data.characterId]
  );
  if (charRows.length === 0) return;
  const char = charRows[0];
  // Roll d20 server-side
  const result = rollDice("1d20");
  const roll = result.total;
  const nat20 = roll === 20;
  const success = roll >= 18;
  // Log to roll_log with "Death Save" label (success gets suffix)
  const label = success ? "Death Save \u2014 stands at 1 HP!" : "Death Save";
  const [insertResult] = await db.execute<import("mysql2").ResultSetHeader>(
    `INSERT INTO roll_log
       (campaign_id, character_id, character_name, character_color, type, label,
        dice_expression, rolls, modifier, total, advantage, disadvantage, nat20)
     VALUES (?, ?, ?, ?, 'custom', ?, '1d20', ?, 0, ?, 0, 0, ?)`,
    [
      data.campaignId,
      data.characterId,
      char.name,
      char.color,
      label,
      JSON.stringify(result.rolls),
      roll,
      nat20 ? 1 : 0,
    ]
  );
  const [savedRows] = await db.execute<RowDataPacket[]>(
    "SELECT * FROM roll_log WHERE id = ?",
    [insertResult.insertId]
  );
  io.to(`campaign:${data.campaignId}`).emit("roll:result", {
    ...savedRows[0],
    rolls: result.rolls,
    advantage: false,
    disadvantage: false,
    nat20,
  });
  // On 18+: heal to 1 HP and clear Dying condition
  if (success) {
    await db.execute("UPDATE characters SET hp_current = 1 WHERE id = ?", [data.characterId]);
    await db.execute(
      "DELETE FROM character_conditions WHERE character_id = ? AND name = 'Dying'",
      [data.characterId]
    );
    const [updatedChar] = await db.execute<RowDataPacket[]>(
      "SELECT * FROM characters WHERE id = ?",
      [data.characterId]
    );
    const [updatedConditions] = await db.execute<RowDataPacket[]>(
      "SELECT * FROM character_conditions WHERE character_id = ?",
      [data.characterId]
    );
    io.to(`campaign:${data.campaignId}`).emit("character:updated", {
      ...updatedChar[0],
      conditions: updatedConditions,
    });
  }
 });
 ```
 - [ ] **Step 2: Verify TypeScript compiles**
 ```bash
 cd server && npx tsc --noEmit 2>&1 | head -20
 ```
 Expected: no errors.
 - [ ] **Step 3: Commit**
 ```bash
 git add server/src/socket.ts
 git commit -m "feat: death:recovery-roll socket handler — d20 save, 18+ stands at 1 HP"
 ```
 ---
 ## Task 6: CharacterCard dying/dead UI
 **Files:**
 - Modify: `client/src/components/CharacterCard.tsx`
 - Modify: `client/src/components/CharacterCard.module.css`
 Dying state: pulsing red border + 💀N countdown in vitals row.
 Dead state: muted/greyed card, skull prefix on name, HP bar non-functional.
 Revive button: DM-only, appears when `is_dead === true`, sends PATCH `{ is_dead: false, hp_current: 1 }`.
 - [ ] **Step 1: Add CSS classes**
 Add to the end of `client/src/components/CharacterCard.module.css`:
 ```css
 .dying {
  border: 2px solid var(--danger) !important;
  animation: dyingPulse 1.5s ease-in-out infinite;
 }
@keyframes dyingPulse {
  0%, 100% { box-shadow: 0 0 6px rgba(var(--danger-rgb), 0.4); }
  50%       { box-shadow: 0 0 20px rgba(var(--danger-rgb), 0.85); }
 }
 .dead {
  opacity: 0.45;
  filter: grayscale(0.75);
 }
 .dyingLabel {
  font-size: 0.8rem;
  color: var(--danger);
  font-weight: 700;
  flex-shrink: 0;
  white-space: nowrap;
 }
 .reviveBtn {
  display: block;
  width: 100%;
  margin-top: 0.5rem;
  padding: 0.25rem 0.5rem;
  font-size: 0.75rem;
  background: transparent;
  border: 1px solid var(--gold);
  color: var(--gold);
  border-radius: 3px;
  cursor: pointer;
  font-family: "Cinzel", Georgia, serif;
  letter-spacing: 0.04em;
 }
 .reviveBtn:hover {
  background: rgba(var(--gold-rgb), 0.12);
 }
 ```
 - [ ] **Step 2: Update CharacterCard component**
 Replace the entire contents of `client/src/components/CharacterCard.tsx`:
 ```typescript
 import type { Character } from "../types.js";
 import HpBar from "./HpBar.js";
 import TorchTimer from "./TorchTimer.js";
 import styles from "./CharacterCard.module.css";
 import { calculateAC } from "../utils/derived-ac.js";
 import { getTalentHpBonus } from "../utils/talent-effects.js";
 import { getEffectiveStat } from "../utils/talent-effects.js";
 import { getModifier, formatModifier } from "../utils/modifiers.js";
 function getAvatarUrl(character: Character): string {
  const style = (character.overrides?.avatar_style as string) || "micah";
  const seed = encodeURIComponent(character.name || "hero");
  return `https://api.dicebear.com/9.x/${style}/svg?seed=${seed}`;
 }
 const STATS = ["STR", "DEX", "CON", "INT", "WIS", "CHA"];
 interface CharacterCardProps {
  character: Character;
  onHpChange: (characterId: number, hp: number) => void;
  onUpdate: (characterId: number, data: Partial<Character>) => void;
  onClick: (characterId: number) => void;
  canEdit?: boolean;
  focusSpell?: string;
  isDM?: boolean;
 }
 export default function CharacterCard({
  character,
  onHpChange,
  onUpdate,
  onClick,
  canEdit = true,
  focusSpell,
  isDM = false,
 }: CharacterCardProps) {
  const dyingCondition = character.conditions?.find((c) => c.name === "Dying");
  const isDying = !!dyingCondition;
  const isDead = !!character.is_dead;
  const cardClass = [
    styles.card,
    isDying ? styles.dying : "",
    isDead ? styles.dead : "",
  ]
    .filter(Boolean)
    .join(" ");
  // When dying/dead the left-color border is replaced by the dying/dead CSS
  const cardStyle = isDying || isDead
    ? {}
    : { borderLeftColor: character.color, borderLeftWidth: "3px" };
  return (
    <div className={cardClass} onClick={() => onClick(character.id)} style={cardStyle}>
      <div className={styles.cardHeader}>
        <img className={styles.avatar} src={getAvatarUrl(character)} alt="" />
        <div className={styles.nameRow}>
          <span className={styles.name}>
            {isDead ? "\u{1F480} " : ""}{character.name}
            {character.title ? ` ${character.title}` : ""}
          </span>
          <span className={styles.level}>Lvl {character.level}</span>
        </div>
      </div>
      <div className={styles.meta}>
        {character.ancestry} {character.class}
      </div>
      {focusSpell && (
        <div className={styles.focusIndicator}>
          &#9679; Focusing: {focusSpell}
        </div>
      )}
      <div className={styles.vitalsRow} onClick={(e) => e.stopPropagation()}>
        <HpBar
          current={character.hp_current}
          max={character.hp_max + getTalentHpBonus(character)}
          onChange={isDead ? () => {} : (hp) => onHpChange(character.id, hp)}
        />
        {isDying && dyingCondition && (
          <span className={styles.dyingLabel} title="Dying">
            {"\u{1F480}"} {dyingCondition.rounds_remaining}
          </span>
        )}
        <div className={styles.ac}>
          <span className={styles.acLabel}>AC</span>
          <span className={styles.acValue}>{calculateAC(character).effective}</span>
        </div>
        <span
          className={styles.luck}
          title={character.luck_token ? "Luck available" : "Luck spent"}
        >
          {character.luck_token ? "\u2605" : "\u2606"}
        </span>
        <TorchTimer
          torchLitAt={character.torch_lit_at}
          onToggle={() => {
            const isLit = character.torch_lit_at !== null;
            onUpdate(character.id, {
              torch_lit_at: isLit ? null : new Date().toISOString(),
            } as Partial<Character>);
          }}
        />
      </div>
      {isDead && isDM && (
        <button
          className={styles.reviveBtn}
          onClick={(e) => {
            e.stopPropagation();
            onUpdate(character.id, { is_dead: false, hp_current: 1 } as Partial<Character>);
          }}
        >
          Revive
        </button>
      )}
      <div className={styles.modRow}>
        {STATS.map((stat) => {
          const value = getEffectiveStat(character, stat);
          const mod = getModifier(value);
          return (
            <span key={stat} className={styles.mod}>
              <span className={styles.modLabel}>{stat}</span>
              <span className={styles.modValue}>{formatModifier(mod)}</span>
            </span>
          );
        })}
      </div>
      <div className={styles.xp}>
        XP {character.xp} / {character.level * 10}
      </div>
    </div>
  );
 }
 ```
 Note: The original imports use no `.js` extension on the type import (`from "../types"`) and no extension on some component imports. The existing codebase uses `.js` for some and none for others in the same file — keep whatever the original had for the imports that existed before, and use `.js` on any new ones. The existing file used no extensions — keep that pattern.
 Actually, looking at the original file:
 ```typescript
 import type { Character } from "../types";
 import HpBar from "./HpBar";
 import TorchTimer from "./TorchTimer";
 import styles from "./CharacterCard.module.css";
 import { calculateAC } from "../utils/derived-ac";
 ...
 ```
 Use the same no-extension pattern to match existing code in this file:
 ```typescript
 import type { Character } from "../types";
 import HpBar from "./HpBar";
 import TorchTimer from "./TorchTimer";
 import styles from "./CharacterCard.module.css";
 import { calculateAC } from "../utils/derived-ac";
 import { getTalentHpBonus } from "../utils/talent-effects";
 import { getEffectiveStat } from "../utils/talent-effects";
 import { getModifier, formatModifier } from "../utils/modifiers";
 ```
 Use those exact import paths (no `.js`) in the replacement.
 - [ ] **Step 3: Verify CharacterCard callers still compile**
 Search for all places that render `<CharacterCard` to confirm the new optional `isDM` prop doesn't break anything:
 ```bash
 grep -rn "CharacterCard" /Users/aaron.wood/workspace/shadowdark/client/src/
 ```
 All existing call sites are compatible — `isDM` is optional and defaults to `false`.
 Now find where the DM view renders cards and pass `isDM`:
 ```bash
 grep -rn "onHpChange\|CharacterCard" /Users/aaron.wood/workspace/shadowdark/client/src/pages/
 ```
 In `CampaignView.tsx` (or wherever the DM renders character cards), add `isDM={role === "dm"}` or `isDM={isDM}` to the `<CharacterCard>` calls.
 - [ ] **Step 4: Verify TypeScript compiles**
 ```bash
 cd client && npx tsc --noEmit 2>&1 | head -30
 ```
 Expected: no errors.
 - [ ] **Step 5: Commit**
 ```bash
 git add client/src/components/CharacterCard.tsx client/src/components/CharacterCard.module.css
 git commit -m "feat: CharacterCard dying pulse border + countdown; dead state; DM Revive button"
 ```
 ---
 ## Task 7: InitiativeTracker Roll Recovery button
 **Files:**
 - Modify: `client/src/components/InitiativeTracker.tsx`
 In the active combat view, for each party combatant with a Dying condition, show a "💀 Dying (N rounds)" label and a DM-only "Roll Recovery" button that emits `death:recovery-roll`.
 - [ ] **Step 1: Add emitRecoveryRoll in InitiativeTracker**
 In `InitiativeTracker` (the main component, around line 50), add:
 ```typescript
 function emitRecoveryRoll(characterId: number) {
  socket.emit("death:recovery-roll", { campaignId, characterId });
 }
 ```
 - [ ] **Step 2: Pass onRecoveryRoll to ActivePhase**
 Update the `<ActivePhase>` call (around line 107) to pass the new callback:
 ```tsx
 <ActivePhase
  combat={combat}
  partyChars={partyChars}
  isDM={isDM}
  showAddEnemy={showAddEnemy}
  addEnemyName={addEnemyName}
  addEnemyHp={addEnemyHp}
  onSetShowAddEnemy={setShowAddEnemy}
  onSetAddEnemyName={setAddEnemyName}
  onSetAddEnemyHp={setAddEnemyHp}
  onUpdateEnemyHp={emitUpdateEnemyHp}
  onRemoveEnemy={emitRemoveEnemy}
  onAddEnemy={emitAddEnemy}
  onNext={emitNext}
  onEnd={emitEnd}
  onRecoveryRoll={emitRecoveryRoll}
 />
 ```
 - [ ] **Step 3: Update ActivePhaseProps interface**
 In the `ActivePhaseProps` interface (around line 220), add:
 ```typescript
 onRecoveryRoll: (characterId: number) => void;
 ```
 - [ ] **Step 4: Update ActivePhase destructuring**
 In the `ActivePhase` function signature, add `onRecoveryRoll` to the destructuring.
 - [ ] **Step 5: Add dying indicator and Roll Recovery button in party list**
 In `ActivePhase`, replace the party combatant render (the `partyChars.map` block around line 266) with:
 ```tsx
 {partyChars.map((c) => {
  const dyingCondition = c.conditions?.find((cond) => cond.name === "Dying");
  return (
    <div key={c.id} className={styles.combatantRow}>
      <span className={styles.dot} style={{ background: c.color }} />
      <span className={partyActive ? styles.activeName : styles.rollName}>
        {c.is_dead ? "\u{1F480} " : ""}{c.name}
      </span>
      {dyingCondition && (
        <span className={styles.dyingTag}>
          {"\u{1F480}"} Dying ({dyingCondition.rounds_remaining}r)
        </span>
      )}
      {isDM && dyingCondition && !c.is_dead && (
        <button
          className={styles.recoveryBtn}
          onClick={() => onRecoveryRoll(c.id)}
        >
          Roll Recovery
        </button>
      )}
    </div>
  );
 })}
 ```
 - [ ] **Step 6: Add CSS for dying tag and recovery button**
 Open `client/src/components/InitiativeTracker.module.css` and add:
 ```css
 .dyingTag {
  font-size: 0.72rem;
  color: var(--danger);
  font-weight: 600;
  margin-left: auto;
  white-space: nowrap;
 }
 .recoveryBtn {
  font-size: 0.7rem;
  padding: 0.15rem 0.4rem;
  background: transparent;
  border: 1px solid var(--danger);
  color: var(--danger);
  border-radius: 3px;
  cursor: pointer;
  white-space: nowrap;
  flex-shrink: 0;
 }
 .recoveryBtn:hover {
  background: rgba(var(--danger-rgb), 0.12);
 }
 ```
 - [ ] **Step 7: Verify TypeScript compiles**
 ```bash
 cd client && npx tsc --noEmit 2>&1 | head -30
 ```
 Expected: no errors.
 - [ ] **Step 8: End-to-end smoke test**
 1. Start server and client
 2. Log in as DM, open a campaign with a character in active combat
 3. Set character HP to 0 → card gains red pulsing border with 💀N
 4. Advance turn (enemy → party) → rounds_remaining decrements
 5. Click Roll Recovery in initiative tracker → roll appears in roll log
 6. On a 18+ roll → character HP returns to 1, dying border disappears
 7. Let timer expire → character marked dead → card greyed with skull, HP non-functional
 8. Click Revive → character returns to 1 HP, dead state clears
 - [ ] **Step 9: Commit**
 ```bash
 git add client/src/components/InitiativeTracker.tsx client/src/components/InitiativeTracker.module.css
 git commit -m "feat: dying label and Roll Recovery button in InitiativeTracker active phase"
 ```
 ---
 ## Self-Review Checklist
 **Spec coverage:**
 - ✅ HP→0 auto-inserts Dying condition (Task 3)
 - ✅ HP>0 clears Dying condition (Task 3)
 - ✅ 1d4 + CON modifier, minimum 1 (Task 3)
 - ✅ `is_dead` column (Task 1)
 - ✅ Party turn ticks the timer (Task 4)
 - ✅ Timer expiry sets is_dead + deletes condition (Task 4)
 - ✅ `death:recovery-roll` event, DM only (Task 5)
 - ✅ d20 server-side, roll:result with "Death Save" label (Task 5)
 - ✅ 18+ heals to 1 HP, clears Dying (Task 5)
 - ✅ Pulsing red border + 💀N on dying card (Task 6)
 - ✅ Grey/muted dead card, HP non-functional (Task 6)
 - ✅ Revive button (DM only, Task 6)
 - ✅ Dying label + Roll Recovery button in InitiativeTracker (Task 7)
 - ✅ Roll log "Death Save" with success suffix (Task 5)
 - ✅ Already dying: no new condition (Task 3 — checks `isAlreadyDying`)
 - ✅ Negative CON mod: clamped to minimum 1 (Task 3 — `Math.max(1, ...)`)
 - ✅ Combat ends while dying: timer just stops ticking (tick only happens in initiative:next)
 - ✅ Multiple dying chars same round: loop handles all in tickDeathTimers (Task 4)
 **Scope check:** All changes are narrowly scoped to the death timer feature. No unrelated refactors.
 **Type consistency:**
 - `conditions: Condition[]` added to `Character` in `types.ts`
 - `is_dead: boolean` added to `Character` in `types.ts`
 - Both are included in `character:updated` broadcasts from all code paths
 - `Condition.rounds_remaining` is `number | null` in types — initiative handler casts to `number` after confirming `dyingRows.length > 0`