`WINGBOARD-SPEC.md`

103 lines
# Wingboard Flip / Peruse — corrected interaction model (Phillip Jeffries reference)

Source of truth for the board display + flip interaction. Supersedes the earlier
"butterfly book-match" model. Grounded in Phillip Jeffries showrooms (they call them
**"wingboards"**; showroom designers are shown **"flipping through wingboards"**, 430+
boards) and two reference images Steve provided (a sample wing binder; a BOYADISPLAY
wall-mounted wing rack fanned open).

## The real-world fixture (what we're recreating)
A wall-mounted **wingboard rack**: a horizontal brushed-brass rail; many large sample
boards (each ~30" wide × 6 ft tall) hang from it, **hinged on a vertical edge**, packed
tightly. Closed, you see only a **~4" sliver** of each board's wallcovering at its
exposed edge — like the fore-edges of books on a shelf. You **flip/swing a wingboard
open** on its vertical hinge (like turning a big page) to reveal its FULL wallcovering;
flipped boards fan to the side. (Image #3 = the wall rack fanned open. Image #2 = the
binder form: closed wings stacked left & right, the selected one open in the center.)

## Showroom layout (50 at a time)
- **50 wingboards** visible at once on the rail (Steve: "show 50 at a time"). Peruse pages
  through all 883.
- Boards overlap at a **~4" pitch** (0.1016 m) so each shows a 4" sliver of its design —
  occlusion gives the sliver for free; NO image slicing needed. (Slicers exist if ever
  wanted: TextureCrop.ts canvas-crop, img_tools.py Pillow, force-crop sharp.)
- Slight per-board angle (fan-deck rake) so the exposed sliver faces the viewer.
- The exposed sliver must show the actual wallcovering (the board's right/leading 4").

## Flip / open interaction
- **Closed:** 4" sliver only.
- **Open (flip):** the selected wingboard swings open on its vertical hinge to face the
  viewer and present its FULL design. Open it **~65°** (Steve: "open up to 65 degrees on
  each") — i.e. the panel rotates out ~65° from the rail plane to present the design;
  if a two-leaf board, each leaf opens 65° to show one continuous design across both.
- **Isolate:** when one board is open, the others dim/recede so the open design is the
  hero (Steve: "isolate the design ... to see entire design").
- **One continuous design:** the open board shows ONE whole wallcovering (NOT mirrored).
  If two leaves, left leaf = left half, right leaf = right half (continuous), not a
  book-match mirror.

## On load
- **All wingboards closed except the MIDDLE one, which is open** showing its design
  (Steve: "onload wings are all closed except for middle design opened").

## Peruse (auto-flip)
- Camera **4 ft back, centered** on the open board.
- Open board N (flip to ~65°), present its full design isolated, **dwell 5 s**, then close
  it and open board N+1 — an automated "flipping through wingboards." Pages window→window,
  endless.
- **Allow pause for more info:** Space pauses the tour on the current open board and
  surfaces the full spec card / more info; resume continues.

## Brand on the wall (Steve: "put the brand in high res on wall too")
- A feature wall carries the house **brand wordmark in HIGH-RES** (crisp, large) — like
  PJ's logo in their showrooms. Use a high-res canvas/texture (≥2048px) or vector-crisp
  text; the current low-res "DESIGNER WALLCOVERINGS" sign is the placeholder to replace.

## Aesthetic (per ART-DIRECTION.md)
Restrained luxury gallery — limewash plaster, warm oak/stone, brushed-brass rail,
soft museum lighting, engraved placards. Phillip-Jeffries-grade calm.

## Verify (every pass)
`node scripts/walkthrough-record.js` → FPS ≥ 50, specs intact (27"×27"), no console
errors; LOOK at the screenshots; iterate on errors. Test over and over all night.

## Design ideas: 4 Horsemen
Use Figma (authenticated, Pro) + 21st Dev + Magic for the HUD + wingboard-browser design
direction; implement in the showroom's vanilla CSS/HTML + Three.js.

## ★ CANONICAL TARGET — Image #6 (Steve: "THIS IS PERFECT. do this!!") 2026-06-28
Reference photo saved at `public/ref/pj-dallas-showroom.png` (Phillip Jeffries Dallas
showroom). Recreate THIS exactly:
- **CORNER-WRAPPING ARC of wingboards** — the rack follows the room corner in a gentle
  arc/bay (NOT a flat back wall). ~20+ tall boards hang in the arc.
- **Packed wingboards, EDGE-SLIVERS** — boards hinged on a vertical edge, raked/angled so
  most show only a thin vertical sliver of their pattern; you see strips of many designs.
- **1–2 boards FLIPPED OPEN in the centre** showing their FULL design face-on (in the
  photo: a black fuchsia floral + a blue speckled pattern). Flipping = swing on the single
  vertical hinge like turning a giant page.
- **DARK BRONZE / black metal FRAMES** around every board.
- **CONSULTATION NOOK in the foreground** — a round warm-wood pedestal table, two cream
  bouclé armchairs, a potted plant, swatch cards on the table.
- **Warm wood floor, cream plaster walls, soft warm gallery light.**
- **USER-ADJUSTABLE reveal slider** — how much of each board shows (sliver width / overlap
  / rake), persisted.
- **Single-vertical-hinge flip** (NOT the centre-spine butterfly). Tap a board → it swings
  open to present its full design; tap again / Next → it closes back into the arc and the
  next opens. Senior guided Next/Back/Auto-Tour still drives which board is open.
- Keep it FPS-safe; occlusion gives the slivers for free.

## ★ SECOND DISPLAY — SAMPLE-CARD WALL on hooks (Steve 2026-06-28, Image #8)
A SEPARATE wall (one full wall) showing EVERY item in the current collection as a small
SAMPLE CARD hung on a hook/peg, in a neat grid — like the PJ swatch-card wall:
- **Small square cards** (each ~one swatch), showing the product IMAGE + a small label
  header (house/brand name) at the top of the card, like a luggage tag.
- **Hung on little hooks/pegs** on a framed board, in an even GRID (e.g. ~10 columns,
  many rows), slight gaps between cards. Cards can have a faint hanging tilt.
- **EVERY item in the current collection** (China Seas 883 — page/scroll the grid; or
  load all as instanced cards for one big wall). Must stay FPS-safe → use INSTANCED
  meshes / texture atlas or lazy texture loading; do NOT load 883 full textures at once.
- **Interaction**: tap a card → it enlarges / flies forward to show the full design + spec
  (reuse the existing focus + spec card); senior Next/Back still works.
- This is a NEW view/wall ("Card Wall" / "Swatch Wall"), ADDITIVE to the wingboard arc
  rack — both are selectable. Queue AFTER the arc-rack pass to avoid file clobber.