# 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`