Phaser-native rendering for DOM SVG card visuals (replace svgDom)

[SorraTheOrc]

Headline

Implement Phaser-native SVG card rendering for Main Street so card visuals remain visible and correctly occluded by Help/Settings overlays without relying on svgDom hide/show workarounds.

Problem statement

Main Street still uses DOM/SVG card rendering (scene.svgDom) for several card paths, which sits above the Phaser canvas and forces Help/Settings panels to hide DOM cards while open. This creates visual disappearance behavior and inconsistent layering compared with canvas-native UI overlays.

Users

• Players opening Help/Settings during gameplay who expect cards to remain visible behind overlays.
  • User story: As a player, I want card visuals to remain present while overlays open so UI behavior feels stable and predictable.
• Developers maintaining Main Street and shared UI overlays.
  • User story: As a developer, I want card rendering to follow Phaser depth/layer rules so overlay behavior does not depend on DOM-specific visibility toggles.

Success criteria

• Help and Settings overlays visually occlude card visuals while cards remain present in-scene (not hidden/removed), verified in browser tests.
• Manual svgDom.setVisible(false/true) calls are not required for normal production overlay behavior.
• Rasterization uses keyed texture reuse (per card variant/size/DPR) and avoids unnecessary regeneration during steady-state rendering.
• Main Street card rendering keeps acceptable fidelity versus current visuals at default resolutions and on resize/device DPR changes.
• Validation and safety gates: npm test and npm run build both pass after changes.
• All related documentation is updated to reflect the rendering-path changes, including developer docs and relevant in-code comments.

Constraints

• Must preserve existing gameplay and interaction behavior (card selection/hit areas remain functional).
• Must support fallback behavior in environments where rasterization is unavailable or constrained (tests/SSR/headless cases).
• Must respect canonical Main Street card dimensions/aspect guidance (140x80, fit-inside rendering expectations).
• Must keep scope bounded to rendering/layering behavior; additional unrelated UI refactors should be tracked as separate work items.

Existing state

• src/ui/SettingsPanel.ts and src/ui/HelpPanel.ts explicitly hide/show scene.svgDom when side panels open/close.
• Main Street already has SVG texture helpers and a scene texture manager (SvgTextureHelpers, MainStreetSvgTextureManager) that rasterize SVG into Phaser textures for some display paths.
• DOM renderer (SvgDomRenderer) remains in use for some card flows (notably hand-held event path coverage in existing browser tests).
• Browser tests currently include expectations tied to DOM image visibility changes when overlays open.

Desired change

Unify Main Street card display on Phaser-native textures/GameObjects for production rendering paths so overlay depth ordering works naturally through Phaser containers/depth. Keep a controlled fallback path for unsupported environments, migrate or update tests that currently encode DOM hide/show behavior, and document the final rendering strategy and cache behavior.

Related work

• src/ui/SettingsPanel.ts — Contains current svgDom hide/show behavior that causes card disappearance during panel open.
• src/ui/HelpPanel.ts — Mirrors SettingsPanel hide/show behavior and must align with final layering strategy.
• example-games/main-street/scenes/MainStreetSvgTextureManager.ts — Existing rasterization/cache orchestration that can be extended rather than replaced.
• example-games/main-street/scenes/SvgDomRenderer.ts — Current DOM rendering implementation and likely fallback path boundary.
• example-games/main-street/scenes/SvgTextureHelpers.ts — Core helper for data-URI rasterization and texture keying (ms_card_*).
• tests/main-street/HelpPanelLayering.browser.test.ts — Encodes current DOM visibility expectations; needs revision to validate native layering outcomes.
• tests/main-street/MainStreetSvgSmoke.browser.test.ts — Confirms rasterized SVG texture generation; useful guardrail for migration.
• docs/main-street/prd-milestone-4.md — Documents intended SVG-to-texture runtime path and visual polish expectations.
• docs/main-street/card-dimensions.md — Defines canonical dimensions and rendering constraints relevant to fidelity checks.
• Main Street: PRD Milestone 4 -- Visual Polish, Animation, and Audio (CG-0MM4RF91E1LR5RSY) — Historical context for the SVG texture strategy and visual acceptance intent.
• Main Street: PRD Milestone 6 -- Engine Component Extraction and Refactoring (CG-0MM4RG1GM0SRVENC) — Relevant precedent for extracting stable rendering helpers into shared engine modules.

Risks and assumptions

• Risk: Browser/headless differences in image decode/raster APIs can cause flaky tests.
  • Mitigation note: keep fallback path and prefer assertions against rendered output/state rather than implementation-only internals.
• Risk: Scope creep into broader UI/animation polish while touching overlays.
  • Mitigation note: record non-essential enhancements as linked follow-up work items instead of expanding this item.
• Risk: Texture cache invalidation on resize/DPR changes may cause stale or blurry assets.
  • Mitigation note: explicitly define cache key strategy and regeneration triggers in implementation/docs.
• Assumption: Existing ms_card_* texture key conventions and helper APIs are stable enough to reuse.
• Assumption: Critical user pain is layering/visibility correctness, not pixel-perfect art parity.

Related work (automated report)

• Main Street: PRD Milestone 4 -- Visual Polish, Animation, and Audio (CG-0MM4RF91E1LR5RSY): establishes the intended SVG->texture runtime path and acceptance context for visual layering polish.
• Main Street: PRD Milestone 6 -- Engine Component Extraction and Refactoring (CG-0MM4RG1GM0SRVENC): provides precedent for extracting reusable rendering support from Main Street into shared engine modules.
• src/ui/SettingsPanel.ts and src/ui/HelpPanel.ts: direct source of current svgDom visibility toggles; these files are primary change points for removing DOM-dependent overlay behavior.
• example-games/main-street/scenes/MainStreetSvgTextureManager.ts and example-games/main-street/scenes/SvgTextureHelpers.ts: existing rasterization and texture keying foundation that reduces implementation risk by reusing proven helpers.
• tests/main-street/HelpPanelLayering.browser.test.ts and tests/main-street/MainStreetScene.browser.test.ts: current behavior-based tests that will need migration from DOM visibility assertions to canvas layering assertions.
• docs/main-street/card-dimensions.md: canonical rendering constraints (aspect ratio, fit-inside rules, derived sizes) that must remain true after migration.

Appendix: Clarifying questions & answers

• Q: "Are there unresolved ambiguities requiring an additional user interview round?" — Answer (agent inference): "No; the existing work item description already includes user story, measurable acceptance criteria, implementation boundaries, files/areas likely to change, and risks." Source: CG-0MP8YFNX4007N9ZU description and repository artifact review. Final: yes.

Plan: changelog

• 2026-05-16T23:23:41Z: Decomposed into 6 feature children; created dependency edges; recorded interview Appendix and automated review outputs.

[SorraTheOrc]

effort_and_risk_skill

Effort and Risk Report

Effort | Medium | 42.67h
Risk | High | 18/20
Confidence | 70% | unknowns: Cross-browser rasterization behavior under createImageBitmap/Image decode in CI runtime; Extent of test rewrites needed where current assertions depend on DOM visibility toggling; Whether held-event DOM-only path can migrate without gameplay interaction regressions

{
  "effort": {
    "unit": "hours",
    "tshirt": "Medium",
    "o": 24.0,
    "m": 40.0,
    "p": 72.0,
    "expected": 42.67,
    "recommended": 70.67,
    "range": [
      52.0,
      100.0
    ]
  },
  "risk": {
    "probability": 4.24,
    "impact": 4.24,
    "score": 18,
    "level": "High",
    "top_drivers": [],
    "mitigations": [
      "Add targeted tests and integration checks",
      "Lock dependencies and add compatibility tests",
      "Schedule extra review for risky components"
    ]
  },
  "confidence_percent": 70,
  "assumptions": [
    "Existing SvgTextureHelpers and MainStreetSvgTextureManager can be reused with incremental changes",
    "Browser test infrastructure can reliably assert overlay occlusion with Phaser canvas rendering",
    "Fallback DOM path can remain available behind feature detection/flag"
  ],
  "unknowns": [
    "Cross-browser rasterization behavior under createImageBitmap/Image decode in CI runtime",
    "Extent of test rewrites needed where current assertions depend on DOM visibility toggling",
    "Whether held-event DOM-only path can migrate without gameplay interaction regressions"
  ]
}