canopy-game/plan.md

Canopy Refactor And Rules Expansion Plan

Goals

• Convert the game from JavaScript to TypeScript.
• Refactor the single-file implementation into small rules and UI modules.
• Fix the turn-order leverage problem with a public initiative seat draft.
• Add a public weather/effect card draft-ban phase to break symmetry.
• Add an alternate per-turn income mode with extra positional costs for balance.

Recommended Foundation

• Use plain TypeScript with typed domain models and pure rules modules.
• Do not migrate to a board-game framework during this feature pass.
• Keep rendering simple and browser-native for now.
• Treat the game as a deterministic rules engine with DOM rendering layered on top.

Why this approach:

• The game is turn-based and rules-heavy, not entity-heavy.
• ECS-style libraries are a poor fit for this problem.
• boardgame.io is the main browser board-game framework, but it would expand scope too much for this refactor.
• If formal phase handling becomes painful later, XState is the best follow-up addition.

Card System Goals

The weather/effect cards should:

• be readable from a TV screen
• be resolved with perfect information
• create asymmetric incentives each round
• be strong enough to disrupt mirror play
• avoid too much arithmetic or long text
• mostly modify incentives, not replace the core game

Card Market Structure

Recommended round flow:

1. Determine round initiative order.
2. Reveal playerCount + 2 public cards.
3. In initiative order, each player takes exactly one action:
   • draft one card for the round, or
   • ban one card from the row
4. Drafted cards become active global rules for the round.
5. Banned cards are removed.
6. Undrafted cards are discarded.

Recommended limits:

• Start with 8 to 14 total cards.
• Keep active cards per round low, ideally 1 to 3.
• Prefer cards with one sentence and one number.

Candidate Weather / Effect Cards

These are written to fit a large shared screen. The title should be the main thing players read; the rule text should stay short.

Economy / Position Cards

• Leaf Surge: Each leaf gains +1 energy.
• Branching Season: Each branch beyond your first gives +1 energy.
• West Light: Left third columns give +1 energy.
• East Light: Right third columns give +1 energy.
• High Noon: Center third columns give +1 energy.
• Sun Ladder: Straight-up growth costs -1 once per turn.
• Storehouse: Banking is enabled this round.
• Shade Cloth: Your covered nodes still count for 1 energy.

Conflict / Interaction Cards

• Sap Theft: When your branch crosses an opponent branch, gain +1 energy.
• Hedge Trimmer: Branches above the lowest player height are cut down before scoring.
• Disease Sweep: Before each turn, that player loses 1 energy.
• Stalemate: Contested columns give no energy.
• Split Light: Contested columns give half energy to each tied player.
• Shared Light: Contested columns give full energy to every tied player.

Additional Cards Worth Considering

• Root Pulse: Root shifts cost 0 this round.
• Still Soil: Root shifts are disabled this round.
• Thin Air: Diagonal growth costs +1.
• Tailwind: Diagonal growth costs -1 once per turn.
• Canopy Tax: The tallest branch of each player costs +1 to extend.
• Undergrowth: The first growth each turn costs 0.
• Dry Season: Banking loses 1 energy when used.
• Tall Reward: Your tallest leaf gains +2 energy.
• Wide Reward: If you control the most columns, gain +2 energy.
• Twig Bloom: New leaves created this round gain +1 energy when scored.
• Heavy Shade: Columns with 2 or more players present count as contested.
• Sunbreak: Empty columns next to your branch give +1 energy.

Best Initial Card Set

For the first implementation, avoid the cards that require the most new geometry or crossing logic. Start with cards that reuse existing board evaluation.

Phase 1 card set

• Leaf Surge: Each leaf gains +1 energy.
• Branching Season: Each branch beyond your first gives +1 energy.
• West Light: Left third columns give +1 energy.
• East Light: Right third columns give +1 energy.
• High Noon: Center third columns give +1 energy.
• Sun Ladder: Straight-up growth costs -1 once per turn.
• Storehouse: Banking is enabled this round.
• Stalemate: Contested columns give no energy.
• Split Light: Contested columns give half energy to each tied player.
• Shared Light: Contested columns give full energy to every tied player.

Phase 2 card set

Add later after the rules core is stable:

• Shade Cloth
• Sap Theft
• Hedge Trimmer
• Disease Sweep
• Root Pulse
• Still Soil

Why split it this way:

• Phase 1 mostly changes scoring and move costs.
• Phase 2 needs new concepts like coverage protection, branch crossing checks, pruning, or per-turn drain.

Rules Clarifications To Lock Down

Initiative seat draft

• Players use a pure seat-selection token, not growth bidding.
• Players choose specific seat numbers.
• Seats are drafted publicly in bidding order, so no seat conflict resolution is needed.
• Bidding order is determined by setup rule:
  • rotating from a random starting anchor, or
  • lowest lifetime growth income first

Lifetime growth income

Track all growth ever gained.

This should include:

• starting growth at game start
• round-end sunlight income
• per-turn sunlight income
• seat bonus growth
• card-generated growth
• random event growth like sunbeam bonuses
• recovered or protected growth if the game records that as gain

This should not double-count:

• banked energy carried into a later round after it was already counted when first gained

Implementation note:

• Add a dedicated lifetimeGrowthIncome stat to each player.
• Update it only at the moment growth is awarded.

Banking

Current open issue:

• Banking should likely become conditional on a round card rather than always-on.

Recommended rule:

• By default, banking is disabled.
• Storehouse enables banking for that round.

Why:

• This helps reduce the economy snowball.
• It gives the weather deck a meaningful strategic lever.

Contested columns

The current game reads column ownership by the top intercepting node. Weather cards that talk about contested columns require a clear definition.

Recommended definition:

• A column is contested if 2 or more players have a node in that column and they are tied under the active contest rule.

Open design task:

• Decide whether contest is based on equal top row, any shared presence, or special card-defined presence.

Recommended default:

• Contest means two or more players share the best topmost position for that column.

This keeps the rule closest to current sunlight logic.

Leaves and branches

These terms need firm technical definitions before implementation.

Recommended definitions:

• leaf: a node with no children
• branch: a root-to-leaf path, or more simply for scoring, each leaf represents one branch

Recommended implementation simplification:

• Use leaf count instead of true branch count in the first pass.
• Rename card text if needed to match the actual rule.

Example:

• Instead of Branching Season: Each branch beyond your first gives +1 energy, consider Leaf Burst: Each leaf after your first gives +1 energy.

This is much easier to explain and compute.

Branch crossing

Sap Theft needs a precise crossing rule.

Risk:

• The current data model stores branch segments, but crossing detection between diagonal edges is new logic.

Recommendation:

• Do not include crossing-based cards in phase 1.
• If added later, count only actual geometric edge intersections between different players' segments.

Hedge Trimmer

This card is flavorful but potentially destructive and swingy.

Risks:

• Requires pruning nodes and edges from the board.
• Can invalidate pending move assumptions.
• Needs a clear “same level” definition.

Recommendation:

• Delay to phase 2.
• Define it as: Before scoring, all nodes above the shortest tallest-player height are removed.
• Only apply between turns or at round end, never mid-turn.

Disease Sweep

This can be implemented in more than one way.

Choices:

• lose growth before each turn
• lose sunlight before end-of-round tally
• kill twigs as the current disease event does

Recommendation:

• For a card, use the simple economy version: Before each turn, that player loses 1 energy.
• Keep the existing random disease event separate.

Implementation Risks

Player identity and turn order are currently coupled

Current risk:

• player.id is treated as both a stable identity and an array index.

Plan:

• Keep players in stable id order.
• Introduce turnOrder: PlayerId[] for seats and active order.
• Update turn flow and render helpers to use turnOrder where needed.

The game needs explicit phases

Current risk:

• The code uses ad hoc flow control plus animation locks.

Plan:

• Add a typed phase model:
  • initiative_bid
  • weather_draft
  • turn
  • round_end
  • game_over

The code is currently one large file

Current risk:

• Rules, state, rendering, and DOM events are tightly mixed.

Plan:

• Convert to TypeScript first.
• Extract pure rules before feature work.

Per-turn income changes the economy deeply

Current risk:

• Existing logic assumes income is only awarded between rounds.

Plan:

• Keep round_end income as the stable default.
• Add per_turn as an alternate rules path after the initiative and weather phases are working.
• Add positional surcharges to slow runaway chaining.

TV readability

Current risk:

• Too many active modifiers will be hard to track.

Plan:

• Cap active cards per round.
• Keep card titles short.
• Show active effects in one compact panel with icons or one-line summaries.

Banking may conflict with weather cards

Current risk:

• If banking is always available and also appears on a card, the card has no value.

Plan:

• Make banking conditional on round effects, or convert the card into a banking bonus instead of availability.

Randomness vs strategy

Current risk:

• Too much randomness in the weather row can obscure good play.

Plan:

• Start with a small curated deck.
• Reveal a modest row each round.
• Consider a rotating deck instead of full shuffle if needed after testing.

Proposed TypeScript Module Structure

• src/main.ts
• src/constants.ts
• src/state/types.ts
• src/state/createGame.ts
• src/state/reducer.ts
• src/rules/board.ts
• src/rules/moves.ts
• src/rules/scoring.ts
• src/rules/initiative.ts
• src/rules/weather.ts
• src/rules/turnFlow.ts
• src/ui/renderBoard.ts
• src/ui/renderSidebar.ts
• src/ui/renderScoreboard.ts
• src/ui/renderModals.ts
• src/app/events.ts

Proposed Type Model

Core types to introduce early:

• PlayerId
• NodeKey
• Setup
• GameState
• Player
• Phase
• TurnMove
• WeatherCardId
• WeatherCardDefinition
• ActiveRoundEffect

New setup fields:

• initiativeMode: "fixed" | "bid"
• biddingOrderRule: "rotating" | "lowest_growth_income"
• incomeTiming: "round_end" | "per_turn"
• weatherDraftEnabled: boolean

New player fields:

• lifetimeGrowthIncome: number

New game state fields:

• phase
• turnOrder
• seatChoices
• initiativeAnchorPlayerId
• weatherRow
• draftedWeather
• bannedWeather
• activeRoundEffects

Execution Order

Milestone 1: TypeScript conversion and safe refactor

1. Add TypeScript and config.
2. Convert src/main.js to src/main.ts without changing behavior.
3. Extract constants and types.
4. Extract pure board, move, and scoring helpers.
5. Keep current gameplay working exactly as-is.

Milestone 2: Turn-order refactor

1. Separate stable player identity from seat order.
2. Introduce turnOrder.
3. Update active-player logic to walk turnOrder.
4. Add explicit phase handling.

Milestone 3: Initiative draft phase

1. Add setup controls for initiative mode and bidding-order rule.
2. Add lifetime growth income tracking.
3. Implement rotating bid order.
4. Implement lowest-growth-income bid order.
5. Add public seat selection modal.
6. Apply seat growth bonuses.

Milestone 4: Weather draft-ban phase

1. Define weather card data in rules/weather.ts.
2. Add setup toggle for weather phase.
3. Implement weather row generation.
4. Implement draft-or-ban action in seat order.
5. Render active effects clearly.
6. Apply phase 1 weather cards in scoring and move cost logic.

Milestone 5: Per-turn income mode

1. Add setup control for income timing.
2. Implement payout to the active player immediately after their turn.
3. Keep round-end mode intact.
4. Verify banking and pass logic still make sense.

Milestone 6: Distance-based balancing

1. Add root-distance surcharge support.
2. Start with a simple formula such as:
   • extraCost = floor((abs(dx) + abs(dy)) / 4)
3. Apply only in per_turn mode at first.
4. Tune after playtesting.

Milestone 7: Phase 2 weather cards

1. Add crossing-based cards if still desired.
2. Add hedge-trimming/pruning cards.
3. Add disease drain cards.
4. Rebalance text and values based on playtests.

Testing Plan

Add rule-level tests as soon as the core logic is modularized.

Priority coverage:

• legal growth moves
• root shift legality
• scoring by column
• contested column resolution modes
• seat draft ordering
• lifetime growth income tracking
• weather draft resolution
• weather effect application
• per-turn payout behavior
• distance surcharge cost calculation

Recommended First Shipping Configuration

• initiative mode: bid
• bidding order rule: rotating
• income timing: round_end
• weather draft: enabled
• banking: enabled only through Storehouse
• weather deck: only phase 1 cards

Why this first:

• It directly attacks the symmetry problem.
• It fixes turn-order leverage without also changing all economy timing at once.
• It keeps the new concepts readable for group play.

Summary

The most important design shift is this:

• turn order becomes a public seat draft
• each round gains a public asymmetric card market
• mirror play is no longer automatically safe because players can deny and reshape incentives before growth begins

The best implementation strategy is:

• TypeScript first
• modular rules second
• initiative phase third
• weather card system fourth
• per-turn economy mode after the game flow is stable