Dune/game/card-presentation.ts

import type { Card } from './cards';
import { BATTLE_CARD_HELP, battleCardLabel } from './battle-cards';
import { RULE_TOPICS, type RuleTopic } from './reference';
import { ecazTreacheryDefinition } from './ecaz-cards';
import { richeseCardDefinition } from './richese-cards';
import { printedCardCategory } from './card-category';

/** Presentation uses only a card the caller has already been authorized to see. */
export type VisibleCard = Readonly<
  Pick<Card, 'id' | 'name' | 'kind' | 'effect'>
>;
export type CardPresentation = {
  category: string;
  role: 'weapon' | 'defense' | 'leader' | 'utility';
  guidance: string;
  /** Complete player-facing rules for a canonical component, separate from audit metadata. */
  gameplay?: readonly string[];
  /** A bounded component may be inspectable before its actions are implemented. */
  availability?: string;
  topics: readonly RuleTopic[];
};

/** UI eligibility only; exact identity avoids disabling unrelated special cards. */
export function richeseCardActionBlock(card: VisibleCard): string | null {
  const definition = richeseCardDefinition(card);
  if (definition?.card.effect === 'stoneBurner')
    return 'Choose Stone Burner in your battle weapon slot, then choose its leader effect after both plans are revealed.';
  if (definition?.card.effect === 'mirrorWeapon')
    return 'Choose Mirror Weapon in your battle weapon slot. It copies the opposing revealed weapon attack, with your own first post-reveal choice if needed.';
  if (definition?.card.effect === 'portableSnooper')
    return 'Choose Portable Snooper as your battle defense, or use its late-defense panel after reveal before submitting your traitor decision.';
  if (definition?.card.effect === 'residualPoison')
    return 'Use the Residual Poison panel before either combatant commits a leader.';
  if (definition?.card.effect === 'ornithopter')
    return 'Use the Ornithopter movement controls with your selected force group.';
  if (definition?.card.effect === 'nullentropyBox')
    return 'Use the Nullentropy Box panel to pay for a private search.';
  if (definition?.card.effect === 'juiceOfSapho')
    return 'Use the Juice of Sapho panel to choose an available order change or become battle aggressor before plans.';
  if (definition?.card.effect === 'distrans')
    return 'Choose a recipient and card in the Distrans transfer panel.';
  if (definition?.card.effect === 'semutaDrug')
    return 'Use the neutral fresh-discard response in the Semuta development preview. Clean ordinary-card, paid Box, retired Ornithopter (before native Intrusion), Distrans, Truthtrance, four Sapho scopes, unready pre-leader Residual Poison, printed Karama canceling CHOAM Charity, Inflation or Bene Gesserit Charity, battle-card and Ix-deck Thumper/Amal discards are connected, as are private normal-auction and Black Market Ixian allied replacements. Battle discards may pause before original Tech award, native Advanced capture, Face Dance, quoted CHOAM income or Auditor; original cleanup and the same opportunity resume once, using the current audited hand when relevant. Tech requires a supported fresh 3–6-seat CHOAM/optional-Ix profile. Native Ixian casualty substitution keeps its original before-Tooth order. Native Basic Moritani cleanup offers only unkept played cards after its original choice and Karama response. A Basic Richese/Moritani CHOAM/Ecaz profile also reacts to private Sabotage and Robbery overflow after clean shipment/movement arrivals. Clean reactive Baliset and La La La pause after cost without completing the stopped move or free revival. Proactive/final-Mentat Trip to Gamont preserves the exact ordinary/elite return or native No-Field reveal and capped recall, restoring its final owner window when applicable. The approved full-hand exchange spends Semuta without increasing the completed hand. Other pending rewards, producers and nested responses remain unfinished.';
  return definition && definition.card.effect !== 'karama'
    ? 'This Richese card’s effect is not implemented yet. You can inspect its rules.'
    : null;
}

const BASIC_GUIDANCE: Partial<Record<Card['kind'], string>> = {
  projectile:
    'Play in the weapon slot of your battle plan. A projectile weapon kills an opposing leader who has no projectile defense.',
  poison:
    'Play in the weapon slot of your battle plan. A poison weapon kills an opposing leader who has no poison defense.',
  lasgun:
    'Play in the weapon slot. A lasgun kills the opposing leader. If either player uses a Shield or Shield Snooper, a lasgun explosion takes precedence over ordinary weapon effects; traitor resolution comes first.',
  shield:
    'Play in the defense slot to protect your leader from projectile weapons. A lasgun played against any shield causes an explosion unless traitor resolution overrides it.',
  snooper:
    'Play in the defense slot to protect your leader from ordinary poison weapons. A Snooper does not protect against an activated Poison Tooth.',
  worthless:
    'May occupy either the weapon or defense slot in a battle plan, but supplies no attack or protection. Some factions can spend Worthless cards for their own powers.',
  hero: 'Use instead of a leader in your battle plan. A Cheap Hero or Heroine has zero leader strength and is discarded after use.',
};

const BATTLE_TOPIC: Partial<Record<Card['kind'], string>> = {
  poisonTooth: 'card-poison-tooth',
  artillery: 'card-artillery',
  poisonBlade: 'ix-battle-cards',
  shieldSnooper: 'ix-battle-cards',
  weirdingWay: 'ix-battle-cards',
  chemistry: 'ix-battle-cards',
  hero: 'cheap-hero-traitor',
};

/** Canonical component guides and the internal reference supply original explanations.
 * Audit metadata never enters this presentation or its rendered rules text.
 */
export function cardPresentation(card: VisibleCard): CardPresentation {
  const richese = richeseCardDefinition(card);
  if (richese)
    return {
      category: richese.printedType,
      role:
        richese.behavior.battleCategory === 'weapon'
          ? 'weapon'
          : richese.behavior.battleCategory === 'poison-defense'
            ? 'defense'
            : 'utility',
      guidance: richese.summary,
      gameplay: richese.gameplay,
      availability:
        richese.card.effect === 'juiceOfSapho'
          ? 'Richese effect integration and verification are incomplete. Supported controls cover Once Around first or last while your bid remains open, bounded movement and battle-choice ordering, and aggressor during the shared pre-plan opportunity. Earlier bids stay committed. Later aggressor intervention and other phase or auction modes remain unfinished; expansion starts remain disabled.'
          : richese.card.effect === 'semutaDrug'
            ? 'The explicit Semuta development preview offers neutral responses after clean public ordinary-card discards, paid Box disposal, retired Ornithopter movement (including a following Bene Gesserit Intrusion), Distrans, ordinary and queued definite Truthtrance answers, four Sapho scopes, unready pre-leader Residual Poison, printed Karama cancelling CHOAM Charity/Inflation/Bene Gesserit Charity or settling a normal-auction purchase or winning bid, a completed CHOAM sale, clean Kulon, proactive or reactive La La La/Baliset, proactive/final-Mentat Trip to Gamont with an ordinary/elite force or concealed No-Field, accepted Jubba Cloak before storm protection, Ix-deck Thumper/Amal, three battle discard stages (including before original Tech award, native Advanced capture, Face Dance, quoted CHOAM income or Auditor) and private normal-auction or Black Market Ixian ally replacements. Tech requires a supported fresh 3–6-seat CHOAM/optional-Ix profile. Native Ixian casualty substitution keeps its original before-Tooth order. Native Basic Moritani cleanup offers only unkept played cards after the original choice and Karama response, preserving its kept card and unchanged original retention pool. The Basic Richese/Moritani CHOAM/Ecaz entry also adds private Sabotage and Robbery overflow after clean shipment/movement arrivals, preserving the original victim/draw and arrival suffix. Commitment is owner-only; the approved full-hand exchange spends Semuta without increasing your completed hand. Other pending rewards, producers, nested responses and normal expansion starts remain unfinished.'
          : richese.card.effect === 'mirrorWeapon'
            ? 'Mirror Weapon works in bounded CHOAM/Richese-deck classic-faction battles; copied Tooth and Stone choices resolve separately, and a winning physical Mirror may be kept even after copying Tooth or Artillery. This winner-retention treatment is a user-selected interpretation, not an official clarification. Combined modes and full Richese starts remain gated.'
          : richese.card.effect === 'stoneBurner'
            ? 'Stone Burner has development battle controls. Combined allocation timing and Ix timing remain guarded; full expansion starts stay disabled.'
            : 'Richese effect integration and verification are incomplete. Karama, Distrans, Nullentropy Box, Ornithopter, Residual Poison, Portable Snooper, Stone Burner and Mirror Weapon have bounded card handlers; full expansion starts remain disabled.',
      topics: RULE_TOPICS.filter(
        (topic) =>
          topic.id ===
          (richese.card.effect === 'juiceOfSapho'
            ? 'juice-of-sapho'
            : richese.card.effect === 'stoneBurner'
              ? 'stone-burner'
              : richese.card.effect === 'portableSnooper'
                ? 'portable-snooper'
                : 'richese-cards'),
      ),
    };
  const ecaz = ecazTreacheryDefinition(card);
  if (ecaz && ecaz.card.name === card.name)
    return {
      category: 'Special treachery',
      role: 'utility',
      guidance: ecaz.summary,
      gameplay: ecaz.gameplay,
      availability: ecaz.card.effect === 'recruits'
        ? 'Recruits has development controls during Revival. Earlier paid revivals, pending transactions, later free-rate changes and repeated use this turn remain guarded pending their rulings.'
        : ecaz.card.effect === 'harassWithdraw'
          ? 'Harass & Withdraw has development controls in either battle-card slot, with physical allocation choices after reveal. Richese card combinations and additional optional modules remain guarded.'
          : 'Reinforcements has development controls in either battle-card slot, including the explicit Advanced Occupy card variant. It spends three of the card user’s own reserve forces and adds +2 battle score without extra spice support. Charging that cost on every revealed outcome is provisional; same-plan Harass & Withdraw, Stone Burner and other optional modules remain guarded.',
      topics: RULE_TOPICS.filter((topic) => topic.id === (ecaz.card.effect === 'harassWithdraw' ? 'card-harass-withdraw' : ecaz.card.effect === 'reinforcements' ? 'card-reinforcements' : 'card-recruits')),
    };
  const topicIds =
    card.kind === 'special'
      ? [`card-${card.effect ?? ''}`]
      : card.kind === 'worthless'
        ? [
            'battle-cards',
            'bg-charity-karama',
            ...(card.name === 'Trip to Gamont'
              ? ['choam-gamont']
              : card.name === 'Jubba Cloak'
                ? ['choam-jubba']
                : ['choam-worthless']),
          ]
        : [
            'battle-cards',
            ...(BATTLE_TOPIC[card.kind] ? [BATTLE_TOPIC[card.kind]!] : []),
          ];
  const topics = topicIds
    .map((id) => RULE_TOPICS.find((topic) => topic.id === id))
    .filter((topic): topic is RuleTopic => !!topic);
  const category = printedCardCategory(card);
  const role =
    category === 'hero'
      ? 'leader'
      : category === 'special' || category === 'worthless'
        ? 'utility'
        : category;
  return {
    category:
      card.kind === 'special'
        ? 'Special treachery'
        : battleCardLabel(card.kind),
    role,
    guidance:
      (card.kind === 'special' && card.effect === 'ghola'
        ? 'Play at any time to return one eligible dead leader, or up to five forces, for free. Forces return to your reserves. Discard this card after use.'
        : undefined) ??
      BATTLE_CARD_HELP[card.kind] ??
      BASIC_GUIDANCE[card.kind] ??
      topics[0]?.summary ??
      'Inspect the card’s available controls and the internal rules reference for its timing and permitted targets.',
    topics,
  };
}