--- title: Hero Wall Visual Elevation - Plan type: feat date: 2026-10-12 topic: hero-wall-visual-elevation artifact_contract: ce-unified-plan/v1 product_contract_source: ce-brainstorm execution: code ---

Hero Wall Visual Elevation - Plan

Goal Capsule

Objective: A wall owner can compose and share a wall that looks clearly more premium and cohesive than today's flat/pixel default — warm directional light, textured room shell, and a curated set of matching items — without needing custom asset tools.

Means: Ship one first-party hearth hero room material plus a matching hero catalog set in a hybrid visual language, extending the existing material/lighting/catalog pipeline (KTD1–KTD5).

Product authority: This plan owns first-party wall and catalog-item visual elevation only. User creation/generation at that fidelity, full-catalog redraw, and alternate identity directions (Moonroom, Garden Terminal as hero) are surrounding work, not active scope.

Open blockers: None.

Execution profile: Smoke-first for visual units (browser/e2e class assertions + side-by-side visual check); unit/API validation for material enum; keep existing atmosphere e2e green.

Who finishes: Implementer lands units U1–U6; ship via PR when Verification Contract and Definition of Done pass.

Product Contract

Product Contract preservation: Product Contract unchanged (IDs and meaning preserved; planning sections added below).

Summary

Ship a first-party hero composition: one elevated room (wall, floor, window, directional light) and a curated hero catalog set (~8–12 items) that share one light direction and soft grounding shadows. The look is hybrid — clearly above current flat/pixel fidelity, short of full painterly remaster — so a visit-mode wall using only this set looks show-proudly good.

Problem Frame

Digital Walls already lets owners place catalog objects on materials with lighting presets, but the room and items still read as flat stickers. Shared and visit-mode walls underdeliver against the warmer, lit, textured target owners want. Without a first-party visual standard, later creation tools have nothing concrete to aim at.

Key Decisions

How This Work Fits Together

<!-- ce-section: work-relationships -->

This plan covers first-party hero wall + catalog visual elevation. Broader breakdown below is current understanding, not a committed roadmap.

Actors

Key Flows

Requirements

Hero room

Hero catalog set

Catalog presentation & compatibility

Acceptance Examples

Success Criteria

Scope Boundaries

In scope

Deferred for later

Outside this product’s identity for this slice

Dependencies / Assumptions

Outstanding Questions

Deferred to implementation

Planning Contract

Key Technical Decisions

High-Level Technical Design

flowchart LR
  subgraph room [Hero room]
    M[material-hearth class]
    A[wall-architecture + floor]
    W[richer window-view]
    L[light-golden overlays]
    M --> A
    M --> W
    M --> L
  end
  subgraph items [Hero catalog]
    C[Hero set section]
    S[hero-* sprite assets]
    C --> S
  end
  subgraph cohesion [Cohesion layer]
    SH[directional soft shadows]
    V[visit-mode chrome quiet]
  end
  room --> cohesion
  items --> cohesion
  cohesion --> VM[Visit composition AE1]

Layering: composable wall/floor/architecture + richer window; CSS light overlays add directional warmth; hero sprites sit above with shared shadow treatment; visit mode removes edit grid noise.

Assumptions

Recorded because scoping confirmation was skipped (overnight proceed):

Implementation Constraints

Sequencing

U1 → U2 → U3 → U4 → U5 → U6. U3 asset production can start in parallel with U1/U2 once hero slate is locked from Assumptions. U6 can begin stubs after U1 validation enum lands.

Research Summary

Implementation Units

U1. Hearth material + room shell

Goal: Owners can select a Hearth room that shows an elevated wall/floor/window shell.

Requirements: R1, R8

Dependencies: None

Files:

Approach: 1. Add material-hearth from the plaster/wood + architecture pattern (not greenhouse PNG hide). 2. Enrich .window-view (image or layered CSS) so the exterior reads richer than today’s flat skyline. 3. Use image-rendering: auto on hearth surfaces that carry smooth textures. 4. Wire material select “Hearth room”; extend validation; keep existing materials valid. 5. Align docs/DATA_MODEL.md material list with validation.js (include light and hearth).

Patterns to follow: .wall.material-plaster / .material-wood, .wall-architecture, .window-view in styles.css / index.html; choice(c.material, …) in server/validation.js. Do not follow greenhouse’s “hide architecture + full-room PNG” path.

Test scenarios:

Verification: npm run check; targeted backend validation test or e2e atmosphere test extended for hearth.

---

U2. Directional light + visit quieting for Hearth

Goal: Hearth + golden (or morning) reads as one directional light mood; visit mode quiets grid.

Requirements: R2, R3

Dependencies: U1

Files:

Approach: 1. Strengthen .wall.material-hearth.light-golden (and optionally morning) overlays so wall and floor show directional warmth. 2. Ensure visit mode continues to zero grid alpha; add hearth-specific chrome quieting only if needed. 3. Do not add new lighting enum values.

Patterns to follow: .wall.light-golden::after, .wall.light-morning::after, .app.visit-mode .wall.

Test scenarios:

Verification: Playwright class/visibility assertions; visual smoke screenshot optional.

Execution note: Smoke-first — prefer screenshot/class checks over unit tests for overlays.

---

U3. Hero asset set production

Goal: Produce ~10 hybrid hero sprites covering R4 categories.

Requirements: R4

Dependencies: U2 preferred for light-vector lock (shadow direction matches hearth + golden); may bootstrap shapes earlier but polish after U2 smoke.

Files:

Approach: 1. Treat the generator as partial bootstrap only — most hero categories need hand/vector polish for hybrid quality. 2. Name with hero- prefix; keep file sizes reasonable for the wall canvas. 3. Prefer SVG with soft shading; use PNG only when SVG cannot support later R6 composition. 4. Match shadow/light direction to the U2 hearth + golden vector before calling assets final.

Patterns to follow: Existing assets/objects/*.svg and scripts/generate-object-assets.mjs palette (bootstrap only).

Test scenarios:

Verification: All hero files load 200 from static server; R4 category coverage checklist complete.

---

U4. Catalog Hero set wiring

Goal: Owners discover and place hero items from a dedicated hero catalog section.

Requirements: R4, R7, R8

Dependencies: U3

Files:

Approach: 1. Register hero asset keys; keep legacy sprite list intact. 2. Render a “Hero set” section at the top of the catalog. 3. Extend spriteLabel (and related helpers) to resolve hero keys, not only SPRITE_ASSETS. 4. Adding a hero card creates a sprite item with the corresponding assetKey and hero-appropriate meaning/copy.

Patterns to follow: SPRITE_ASSETS, renderCatalog, spriteAssetUrl, spriteLabel in app.js.

Test scenarios:

Verification: Playwright catalog flow or unit-level catalog render test if available; otherwise e2e.

---

U5. Shadow cohesion for hero items on Hearth

Goal: Hero items on a Hearth wall share soft directional grounding shadows.

Requirements: R5, R6

Dependencies: U1, U2, U4

Files:

Approach: 1. Target hero sprites via variant-hero-* (existing variant-${assetKey} pattern) or an explicit data-hero marker. 2. Apply soft drop-shadow aligned to hearth + golden light vector; avoid harsh pixel offsets used by legacy stickers. 3. Add sprite-specific sway/glow for plant/lamp hero keys (KTD5) — do not assume .item-plant / .item-lamp selectors apply.

Patterns to follow: .item-sprite img filters; animation keyframes from vine/grow-lamp as reference only.

Test scenarios:

Verification: Playwright CSS assertions (image-rendering, class presence) + visual smoke.

---

U6. Persistence, regression, and proof

Goal: Hearth + hero composition persists; legacy paths stay green; proof artifacts exist for R6.

Requirements: R6, R8; AE1–AE3

Dependencies: U1–U5

Files:

Approach: 1. Extend atmosphere e2e for hearth + golden persistence. 2. Add catalog Hero set discovery + place flow. 3. Capture a visit-mode screenshot artifact for manual R6 side-by-side review (moodboard at docs/visual-reference/hearth-pixel-moodboard.png if owner frame unavailable). 4. Add backend validateState coverage for material: "hearth" accept and unknown material reject. 5. Covers AE3 via existing board reload with non-hearth material.

Test scenarios:

Verification: npm run check; npm test; npm run test:e2e (or targeted Playwright file).

Verification Contract

Definition of Done

Appendix

Origin