Code and instructions handoff

You are setting up Sketchbook, a wall-tablet dashboard for Home Assistant, in another person's home. This file is written for you, the agent. Work through it top to bottom; every step says what to change, where, and how to check it. You will not need to ask the authors anything.

#What you're building

Sketchbook draws the home like a page from an architect's sketchbook: graphite pencil drawings that colour in when something is on. The Home page is a three-quarter aerial drawing of the house under a sky that follows the real sun (drag the sun or moon along its loop to preview any hour), with lit windows, a heated-pool glow, garden lamps, solar / battery / power notes and the cats popping up in the room they're in. Rooms shows 18 pencil sketches that bloom into colour when the room's light is on (dimmer, A/C ±, curtain and lock status). Curtains & Sheers puts real 3D curtains in front of each window's view and reacts to the weather. Then Animals (where each cat is and has been), Garden (a plan with 20 light pins), Energy (the day's solar, grid and battery chart), Network and Vacuum. English ⇄ 日本語.

Out of the box it runs as a demo of a made-up home ("Sakura Home" in Tokyo, a fictional family and six fictional cats). Nothing in it is a real home. Your job: run the demo, connect it to the person's Home Assistant, map their entities, optionally redraw the pictures of their own home, and put it on their tablet.

Sketchbook — the Home page at golden hour

What the person needs

• Home Assistant 2024.1 or newer (uses the WebSocket API, weather.get_forecasts, and the REST history, calendar and template endpoints). No HACS cards, no custom frontend.
• A wall tablet or any modern browser. The design is made for 1376 × 1032 CSS px, landscape (a 13" tablet); it also works at 1180 × 820 (11" tablets). Phones are not a target.
• A computer with Node.js 18+ to build it (the tablet only runs the result).

Time: demo 10 min · mapping entities 1–3 h (depends on how many rooms and devices) · going live 30 min · pictures of their own home 2–6 h (optional — the made-up pictures work as placeholders).

#What's in this package

HANDOFF.md              this guide            README.md   3-line pointer            LICENSE   MIT (code) + notes
package.json            exact versions it was built and tested with
vite.config.ts          dev server (+ live-mode proxy) and builds; BASE = where a build will be hosted
tsconfig.json  index.html  .gitignore
.env.example            copy to .env.live for live mode (Home Assistant address, token for the dev server, BASE)
panel-loader.js         mode B: makes the dashboard a page in Home Assistant's sidebar
live/README.md          the go-live kit in detail (modes A, B, C, troubleshooting)
docs/still.jpg          what it looks like
tools/
  sketchbook_art.py     picture pipeline (Python + Pillow): rooms, window plates, house, garden, cats, thumbnails,
                        background cut-out, measuring grid
  measure.html          click-to-measure helper for window polygons and anchor points (open in a browser, offline)
  prompts.json          the exact prompts used to draw the made-up home, each with the command that processes it
src/
  main.tsx              start-up switch: demo (default) · live (VITE_HA_MODE=live) · sidebar panel (?panel=1)
  main.demo.tsx         demo entry: mock backend + demo time/weather bridge
  main.live.tsx         live entry for modes A and C          main.panel.tsx   live entry for mode B
  App.tsx, app/views.tsx   the menu: which pages exist, their order and labels
  ha/                   types.ts (the HaBackend interface) · HaProvider.tsx (hooks) · wsBackend.ts (live) ·
                        hassBackend.ts (sidebar) · authFetch.ts (token on REST calls) · mockBackend.ts (demo)
  config/               ← EVERY entity id and per-house setting lives here (Step 2)
  views/, components/   the pages and their parts
  lib/                  sun & sky maths (sky.ts), forecasts, history, music, network data, formatting
  i18n/                 i18n.tsx + ja.ts (English → Japanese dictionary) + ja-fonts.ts
  styles/               theme.css (colour and font tokens), app.css, fonts.css
  demo/                 the made-up home: states snapshot, synthetic day, calendar, music, bridge — never in a live build
  assets/               pictures bundled by Vite (house, garden, rooms, plates, cats, thumbs) + fonts (+ OFL licences)
static/                 served as-is at /local/… and /fonts/…: robot and lamp icons, app icon, network gear,
                        camera "spotting" photos, demo music covers and camera stills, Manrope font

#Run the demo first

npm install
npm run dev            # serves http://localhost:5173/ (and on the LAN: the dev server listens on all interfaces)

Open it in a desktop browser window of roughly 1376 × 1032 (or devtools' device mode). The made-up home runs entirely in the browser: no Home Assistant, and the demo layer (src/demo/sandbox.ts) blocks every network request except Google Fonts (only when 日本語 is switched on) and the RainViewer radar tiles on the Home page. If you see the drawn house with a sky, the toolchain works — do this before touching their house.

Things to try: drag the sun on Home into the night (it springs back when you let go); tap a room sketch on Rooms (it colours in); open a curtain; switch to 日本語; Garden → "All lights on".

The demo clock starts at 16:30 and keeps running. Start-up URL parameters: ?t=21:15 (time; also ?demoTime=), ?wx=rainy (weather — sunny, partlycloudy, cloudy, rainy, pouring, lightning-rainy, fog, snowy), ?lang=ja. A page that shows the demo in an iframe can change time and weather live with postMessage (src/demo/bridge.ts documents the messages). As time moves, the demo switches its lights the way an automation would (evening scene after sunset, night lights after 23:00), so the drawings colour in at dusk.

Other scripts: npm run build → the same demo as static files in dist/ (any web host; BASE=/sub/path/ npm run build for a sub-folder) · npm run typecheck (tsc --noEmit, 0 errors) · npm run preview (serve dist/).

#How it works

Home Assistant ──► HaBackend  (src/ha/types.ts — one small interface)
                     ├─ wsBackend    live, over HA's WebSocket API (subscribe_entities, call_service)
                     ├─ hassBackend  inside HA's sidebar (HA hands the app its `hass` object)
                     └─ mockBackend  demo: an in-memory made-up home
                ──► HaProvider hooks (src/ha/HaProvider.tsx)
                     useEntity(id) · useEntities([ids])      → state + attributes, live
                     useCallService()(domain, service, data, { entity_id })
                     useCallServiceResponse()                → services that return data (weather.get_forecasts)
                ──► views/ and components/
   + REST  fetch("/api/…"): history for the charts (/api/history/period), calendars (/api/calendars/<id>),
           the "lights on" list (/api/states + /api/template). In live mode authFetch adds the user's token.

• Views never know which backend is behind the hooks. Each view subscribes only to its own entities (it stays light on big installations). Keep that when you add cards: useEntities([...ids]), never "all states".
• Demo vs live: src/main.tsx picks main.demo.tsx unless the build/dev mode is live (see Step 3). A live build contains no demo code at all (src/demo/, the mock backend and the demo bridge are tree-shaken out).
• Config: src/config/*.ts holds every entity id and every per-house setting (rooms, curtains, garden lights, where the windows are on the drawing, cats …). Changing the house = changing these files + the pictures.
• i18n: visible text goes through t("English text") (useT() from src/i18n/i18n.tsx); src/i18n/ja.ts maps English → Japanese, and room/cat names shown on screen are looked up the same way. The flag toggle switches en/ja; Japanese fonts are loaded only then. To add their language: copy ja.ts to e.g. de.ts and translate the values; add the code to Lang and the lookup in i18n.tsx; add a button to components/shell/LangToggle.tsx; change the "ja-JP" locale picks (search ja-JP) to their locale; or replace Japanese entirely by editing ja.ts in place. Strings missing from the dictionary simply show in English.
• Theming: CSS custom properties in src/styles/theme.css — paper --paper*, graphite --lead*, lamp yellow --lamp, coloured-pencil inks --cerulean --sap --vermilion --violet, energy --solar --grid --batt, the dark "cloth" sidebar --cloth*, fonts --f-hand (Shantell Sans) and --f-print. The sky tints the paper live: src/lib/sky.ts sets --paper, --paper-shade and --cloth from the sun's height.
• Pictures and how they are layered and anchored (specs in Step 4):
  • Home (components/home/HouseStage.tsx): the sky is CSS, coloured from the real sun position (lib/sky.ts), with stars, clouds, rain, fog, snow and lightning from the weather entity. Over it the house: house-day-cut.webp (transparent background) cross-fades to house-night-body.webp (indigo body) as the sun sets, with house-night-lines.webp (white-pencil lines) on top at night. Between those layers an SVG in the drawing's own pixels (1800 × 791) draws the lit windows — WINDOWS in config/houseArt.ts: a polygon per window and the light(s) that light it, hatched yellow + glow, brighter after sunset — the heated pool (POOL_PTS), lamp halos (PAVILION, GARAGE, ENTRANCE_LAMP), the solar/battery/house energy notes (ENERGY_AT = the point on the house, ENERGY_LABEL = where the note sits) and cat perches (CAT_PERCH, one per cat-room key, where a cat pops up).
  • Rooms (components/rooms/RoomCard.tsx): two pixel-aligned layers per room, <key>-sk.webp (pencil) under <key>-col.webp (colour). Turning the light on reveals the colour with a round "bloom" from where you tapped; the colour layer's opacity follows brightness (42 % + 58 % × brightness).
  • Curtains & Sheers (views/CurtainsSheersView.tsx, components/curtains3d/engine.ts, three.js): a flat plate — the view out of that window, plates/<key>-day.webp / -night.webp — behind 3D curtains and sheers that open and close at motor speed. The weather entity picks the lighting (day / overcast / wet / storm and their night variants, rain and lightning on the glass). Per room in config/curtains3d.ts: the plate key, the entities, fabric colour, and the glass rectangle (glass: [0, 0, 1, 1] = the plate fills the window).
  • Garden (views/GardenView.tsx): garden-day.webp cross-fades to garden-night.webp; 20 light pins sit at fractions of the picture (config/garden.ts, x and y from 0 to 1); glows are SVG.
  • Animals: transparent cat sketches (assets/cats/<cat>.webp) in the donuts and pop-ups; two "spotted by the cameras" photos in static/local/snapshots/animals/.
  • Menu thumbnails: assets/thumbs/*.webp (168 × 112), cut from the pictures above.

#Step 1 — Inventory their Home Assistant

Get the Home Assistant address (e.g. http://homeassistant.local:8123) and, for development only, a long-lived access token (their profile → Security → Long-lived access tokens). List every entity:

export HA=http://homeassistant.local:8123 TOKEN=…            # keep the token out of git; .env.live is ignored
curl -s -H "Authorization: Bearer $TOKEN" "$HA/api/states" \
 | python3 -c 'import json,sys; [print(e["entity_id"], "|", e["state"], "|", e["attributes"].get("friendly_name", "")) for e in json.load(sys.stdin)]' \
 | sort > ha-entities.txt
curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" "$HA/api/template" \
 -d '{"template":"{% for a in areas() %}{{ area_name(a) }}: {{ area_entities(a) | join(\", \") }}\n{% endfor %}"}' > ha-areas.txt

(Or Developer Tools → States in Home Assistant.) Domains this dashboard reads or controls: light, switch, climate, sensor, weather, calendar, media_player, vacuum, lock, script, input_number, input_select, input_boolean, button, select, input_text, input_datetime. Use ha-areas.txt to match their rooms to the dashboard's rooms. Ask the person which rooms, floors and features they want: the dashboard never needs every entity. Anything they don't have, you hide — each row below says how. Never put the token in a build or a committed file.

#Step 2 — Map entities

Replace the made-up ids (*.sk_*) with theirs. "State/attributes used" is what the code reads; "services" is what it calls. Names you can change freely (room titles, cat names, labels) are in the same files. Rows marked (demo only) need nothing. Example ids are the made-up home's.

#Rooms page and room cards — src/config/rooms.ts

FLOOR_VIEW in this file is unused.

#Home page — src/config/entities.ts, src/config/houseArt.ts, src/components/home/HouseStage.tsx

The radar map (components/home/RadarMap.tsx) is not an entity: see "Make it theirs" for its location.

#Curtains & Sheers — src/config/curtains3d.ts (ROOMS3D)

Each room has types[] — one per curtain, sheer or blind — of two kinds:

Most homes have cover.* entities instead: use the cover helpers below (no code change), or change the code — add a kind: "cover" with one cover id, and in views/CurtainsSheersView.tsx read open = state === "open", moving = state === "opening" || state === "closing" and call cover.open_cover / cover.close_cover. Each room also has curtainS / sheerS (motor seconds, used for the animation), baseHex (fabric colour), outdoor (true = the weather shows through), floor, name and the plate key. Delete a room object to drop it; an empty floor hides its tab content. src/config/curtains.ts is (demo only) — the mock backend reads motor times from it.

#Garden — src/config/garden.ts

#Energy — src/views/EnergyView.tsx (E)

No solar or battery at all → remove the energy entry from src/app/views.tsx and the three energy notes on Home (EnergyNote lines in HouseStage.tsx). The ¥ sign is in EnergyView.tsx.

#Animals — src/config/animals.ts

CAT_ACTIVITY_VIEW is unused.

#Vacuum — src/components/vacuum/vacuumModel.ts, plan in src/config/groundPlan.ts

#Music — src/components/music/useMusicData.ts, src/lib/music.ts, src/components/shell/MediaBar.tsx

Playback works with any media_player. The search/favourites tabs need a music integration that offers those response services; most homes don't have musicplus — then those tabs stay empty: hide them in components/music/MusicPlayer.tsx, or rewire them to media_player.browse_media / media_player.search_media. Internet radio uses media_player.browse_media with the Radio Browser integration.

#Network — src/lib/networkData.ts (makeNet())

A drawn rack of network gear (gateway, switches, recorder, power strip, access points, servers, the internet line, cameras) where each device's ent map names sensors for cpu, mem, temp, clients, uptime, latency and power (63 made-up ids such as sensor.sk_net_wan1_latency, sensor.sk_net_lan_clients, sensor.sk_net_pdu_power). Match them to their network integration's sensors (router/switch/AP integrations expose most of these), drop devices they don't have (the pictures are generic, in static/local/network/assets/gear/), or remove network from src/app/views.tsx.

#Helpers they may need to create

Create helpers in Home Assistant's UI (Settings → Devices & services → Helpers → Create helper), and scripts and automations in Settings → Automations & scenes (switch the editor to Edit in YAML and paste). With a token you can also create them through the config API (POST /api/config/script/config/<id>, POST /api/config/automation/config/<id>) — don't hand-edit configuration.yaml. The YAML below is the definition to paste; it uses the 2024.10+ syntax (triggers: / actions:; older versions: trigger: with platform: and service:). Replace living / ids with theirs.

A/C on a room card — a Number helper input_number.living_ac_target (16–30, step 1, °C), then:

# Script "Living A/C on/off" (script id: living_ac_toggle) — the card's fan button calls script.turn_on
sequence:
  - if:
      - condition: state
        entity_id: climate.living_ac
        state: "off"
    then:
      - action: climate.set_temperature
        target:
          entity_id: climate.living_ac
        data:
          hvac_mode: cool
          temperature: "{{ states('input_number.living_ac_target') | float(24) }}"
    else:
      - action: climate.turn_off
        target:
          entity_id: climate.living_ac
mode: single

# Automation "Living A/C follows its target" — the card's − / + change the helper
triggers:
  - trigger: state
    entity_id: input_number.living_ac_target
conditions:
  - condition: not
    conditions:
      - condition: state
        entity_id: climate.living_ac
        state: "off"
actions:
  - action: climate.set_temperature
    target:
      entity_id: climate.living_ac
    data:
      temperature: "{{ trigger.to_state.state | float }}"
mode: restart

Curtains from a cover (no code change) — for each curtain, two Template helpers and a script:

• Template helper → Switch "Living curtains open": state template {{ is_state('cover.living_curtains', 'open') }}, turn on: cover.open_cover, turn off: cover.close_cover (target cover.living_curtains) → use as open / ROOMS[].blackout.
• Template helper → Sensor "Living curtains direction": state template {{ states('cover.living_curtains') if states('cover.living_curtains') in ['opening', 'closing'] else 'idle' }} → use as dir.
• Script living_curtains_toggle: sequence: [{action: cover.toggle, target: {entity_id: cover.living_curtains}}], mode: single → use as script.

Energy totals — if they only have power sensors, first an Integral helper per power sensor (method Left, metric prefix k, time unit hours) to get kWh. Then Utility Meter helpers on each kWh sensor with cycles daily, weekly, monthly (sensor.grid_import_daily …). Savings = Template helper (Sensor), e.g. today: {{ ((states('sensor.solar_energy_daily') | float(0) - states('sensor.grid_export_daily') | float(0)) * 0.31 + states('sensor.grid_export_daily') | float(0) * 0.16) | round(2) }} with their tariff and feed-in rate; yesterday/week/month/year come from Utility Meters on that savings sensor (Utility Meter tracks the last period in its last_period attribute — a Template helper can expose it).

Cat room time — History stats helper per cat per room (Settings → Helpers on recent versions; on older ones the history_stats sensor platform): entity sensor.mochi_room, state kitchen_1, type ratio, start {{ today_at() }}, end {{ now() }} (for _today_) or start {{ now() - timedelta(days=7) }} (for _7d_). Name it so the entity id becomes sensor.mochi_room_ratio_today_kitchen_1.

#Step 3 — Go live

The kit is already wired into this package (src/main.tsx switch, src/main.live.tsx, src/main.panel.tsx, src/ha/wsBackend.ts, hassBackend.ts, authFetch.ts, vite.config.ts, .env.example, panel-loader.js). Read live/README.md — it has the full steps and troubleshooting. In short:

1. cp .env.example .env.live.
2. Mode C first (development against their Home Assistant): set VITE_HA_TARGET and VITE_HA_TOKEN, run npm run dev:live, open the printed address. The dev server proxies /api (REST + WebSocket) to Home Assistant and adds the token. Walk every page while you map entities (Step 2). Keep it on their network.
3. Mode A (recommended for the wall): keep BASE=/local/dashboard/, npm run build:live, copy everything in dist/ to <config>/www/dashboard/ on the Home Assistant machine (Samba / File editor / Studio Code Server app, or scp), open http(s)://<their-ha>:8123/local/dashboard/index.html on the tablet and log in once with Home Assistant's own login page. No token is ever baked into a build (the config refuses).
4. Mode B (a page in the sidebar): mode A's build + panel-loader.js in the same folder + the panel_custom: block from the top of panel-loader.js in configuration.yaml (the one YAML edit; restart Home Assistant).

Before the first live build, also do these app-specific changes:

• Location and clock — src/lib/sky.ts: set LAT, LON to their home; the sun and sky read the tablet's wall clock as the home's local time through TYO (a fixed +9 h for the demo's Tokyo). Replace const TYO = 9 * 3600000; with their offset — best, make it follow the tablet (correct through daylight saving): const TYO = -new Date().getTimezoneOffset() * 60000; and move it into wallMs(), tyoParts(), skyNowMs() and crossings() as a call (tzMs()) so it is re-read after a DST change.
• Radar — src/components/home/RadarMap.tsx: LAT, LON, and the three map labels (points AIRPORT, SUMIDA, BAY and their <text> lines: move/rename or delete), plus the outline file (see "Make it theirs").
• Delete the demo when you are done (optional — a live build already leaves it out): src/demo/, src/ha/mockBackend.ts, src/lib/mockApi.ts, src/main.demo.tsx, and the else { import("./main.demo") } branch in src/main.tsx. src/config/curtains.ts is then unused too.

#Step 4 — Pictures

Every picture the app uses. keep = generic, fine in any home; replace = shows the made-up home (it still works as a placeholder, but it isn't their house).

The style (every picture of a series must share it): a page from an architect's sketchbook on white drawing paper — confident graphite pencil line work with light hatching and faint construction lines, coloured in with soft coloured pencils, loose strokes, some paper left white; lamps glowing honey-gold; no people, no animals, no text. The exact prompts used for the made-up home are in tools/prompts.json — keep each "Style" tail, change only the subject.

Prompt templates (adapt the subject; keep the tail word for word):

• Room (16:9, ~2k): "A wide landscape illustration of {their room: the main furniture, the lamps, the window treatment, materials and colours}. Style: a page from an architect's sketchbook on white drawing paper - confident graphite pencil line work with light hatching and faint construction lines, then coloured in with coloured pencils in soft natural colours, every lamp switched on and glowing honey-gold with warm light pooling around it. Loose pencil strokes, some paper left white. The main furniture sits across the middle band of the picture. No people, no animals, no text or lettering anywhere, no border, no frame." (Draw rooms lit: the colour layer is the "on" look.)
• Window plate (4:3, 3:4 or 3:2 to match the window): "The view out through a floor-to-ceiling window of {their house type} seen from inside the room: slim dark charcoal window frames divide the glass into {N} tall panes, and the frames run edge to edge so the window fills the whole picture; beyond the glass, {what that window looks out on}, on a bright clear day. Style: an architect's sketchbook drawing on white paper - confident graphite pencil line work with light hatching, coloured in with soft coloured pencils (fresh greens, clear sky blue, warm timber, pale stone), loose strokes, some paper left white. No curtains, no blinds, no people, no animals, no text, no border."
• House (21:9, ~4k, transparent background): "An elevated three-quarter bird's-eye drawing of one whole plot, drawn as a single isolated vignette on a transparent background (no sky, nothing outside the plot). {Their house: storeys, cladding, roof (solar panels?), windows per floor, front door, garage, front garden; the back garden wrapping behind it}. Style: …same tail… Daylight, every window unlit. No people, no animals, no cars, no text." Windows must be drawn unlit — the app lights them.
• Garden (21:9, ~4k): "A high bird's-eye three-quarter view looking down into the back garden of {their house}, drawn edge to edge in a wide landscape format. Along the top of the picture runs the back of the house … {every feature that has a light: pool, trees, paths, lanterns}. Style: …"
• Cat (2:3, ~1k, transparent): "{Their cat's coat, eye colour and build}, sitting upright and facing the viewer, the whole body from the tips of the ears to the paws, the tail curled round the paws, drawn as a single isolated sketch on a transparent background: confident graphite pencil outlines and light hatching, coloured in with soft coloured pencils, loose strokes, a faint pencil shadow under the paws. A gentle, sweet expression. Nothing else in the picture: no background, no text, no border."

Processing — tools/sketchbook_art.py (Python 3.8+ and Pillow: pip install Pillow; run from the package root; writes into src/assets/…; --out DIR to write elsewhere first). Usage is printed with no arguments.

python3 tools/sketchbook_art.py room   living.png living          # → rooms/living-col.webp + rooms/living-sk.webp
python3 tools/sketchbook_art.py plate  dining-view.png dining 4:3 # → plates/dining-day/-night.webp + plates/thumb/dining.webp
python3 tools/sketchbook_art.py cutout house.png house-cut.png    # only if the generator can't do transparency
python3 tools/sketchbook_art.py house  house-cut.png              # → house/house-day-cut + night-body + night-lines
python3 tools/sketchbook_art.py garden garden.png                 # → garden/garden-day + garden-night
python3 tools/sketchbook_art.py cat    cat-mochi.png mochi        # → cats/mochi.webp
python3 tools/sketchbook_art.py thumbs network-corner.png         # → thumbs/*.webp (after the others exist)
python3 tools/sketchbook_art.py grid   src/assets/house/house-day-cut.webp grid.png 50   # a measuring grid

The pencil (sk) and night layers are derived from the same drawing, so they always line up with it. Pictures are cropped to fill (cover), centred — frame the subject in the middle band.

Anchors to re-measure after a new house or garden drawing (open tools/measure.html in a browser, load the picture, click): config/houseArt.ts — WINDOWS (4+ points per window, polygon mode → pts: P([...]), plus the light ids), POOL_PTS, GARAGE, PAVILION, ENTRANCE_LAMP, ENERGY_AT (solar panels, battery, middle of the house), ENERGY_LABEL (free space for each note), CAT_PERCH (one per cat-room key: a window sill or roof edge in that room). config/garden.ts — each light's x/y (fraction mode). Room cards, plates, cats and thumbnails need no anchors. Unused anchors can stay; the house art size is fixed by ART_W/ART_H (1800 × 791, set by the tool).

Generators (the made-up home was drawn with a paid AI image service — GPT Image, text prompts only; most people don't have one, and any of these work):

• Best match for this look, free: ChatGPT's free image tier or Microsoft Designer / Bing Image Creator (both follow long style prompts well and keep pencil hatching); Google Gemini (good at "keep the same style as this picture"); Ideogram, Leonardo, Adobe Firefly, Krea (free daily credits).
• Local, free, unlimited: FLUX.1 [schnell] or SDXL in ComfyUI or Forge (add a pencil-sketch LoRA, fix the seed per series), Draw Things on a Mac/iPad. Transparent backgrounds: render on white, then cutout.
• Without AI: their own photos of each room through a "pencil sketch + watercolour" filter (the room command then makes the graphite layer — keep camera height and angle similar across rooms); a free 3D model of the house in Sweet Home 3D or Blender rendered from the three-quarter angle and run through the same filter (also great for the garden); or an illustrator.
• Keep a series consistent: one style tail for everything; generate the house first and use it as the style reference for the rest ("same style as this drawing"); same seed / same model / same quality for a series; similar eye height and lens for rooms; let the subject sit in the middle band. Their own photos of the house, rooms and pets are fine as image-to-image references — it's their home.

#Step 5 — Build & run

• npm run build:live (mode A/B) → dist/; npm run build = the demo. Host: Home Assistant's www/ (mode A/B, recommended — same origin, HA's login), or any static host for the demo.
• Wall tablet: Android → Fully Kiosk Browser (start URL = the dashboard, keep screen on, motion detection to wake, auto-reload on error); iPad → Safari → Share → Add to Home Screen (runs full-screen, no browser bars), then Settings → Accessibility → Guided Access to lock it; Display → Auto-Lock: Never while charging. Keep the tablet on power.
• Screen size: designed at 1376 × 1032 CSS px landscape (13" class); fine at 1180 × 820 (11"). Layout is fluid, not scaled; on smaller screens trim columns rather than shrink. Portrait is not supported.

#Step 6 — Verify

Tick every line on the real tablet (or mode C on a computer):

• Every page opens: Home, Rooms (both floors), Curtains & Sheers (every window chip), Animals, Garden, Energy, Network, Vacuum (minus the ones you removed) — no blank areas, no "—" where a value should be.
• Home: the sky matches the real time of day at their home; sunrise/sunset times on the loop match their weather app; dragging the sun previews another hour and springs back.
• Turning a light on in Home Assistant colours in its room card within a second; the right window glows on the house drawing after dusk; tapping a card toggles the right light, the slider dims it.
• A/C − / + change the right target; the fan button switches the right unit; the climate list shows real states.
• Each curtain button moves the right curtain; open/closed text on the room card matches.
• Garden pins toggle the right lights; "All lights on/off" works.
• Energy: the chart shows today's real curve; totals and savings are plausible numbers in their units/currency.
• Weather label, temperature and rain/fog/snow effects match weather.*; calendar shows their events.
• Music: play/pause/next/volume on the right speakers.
• Browser console: no errors (devtools, or Safari's Web Inspector over USB for an iPad).
• Performance on the tablet: page turns smooth; leave it running an hour — memory steady, clock still ticking.

#Make it theirs

• Names: room titles (config/rooms.ts name, TITLE/KEY maps in components/rooms/RoomCard.tsx), cat names (config/animals.ts), labels in config/entities.ts, the house name in index.html (<title>, app title meta) and the sidebar logo (components/shell/Sidebar.tsx); add Japanese/their language for new names in i18n/ja.ts.
• Rooms: add or remove room objects; each needs a KEY (picture name) and its two pictures. Floors are the "1st"/"2nd" tabs (views/RoomsView.tsx).
• Pages: src/app/views.tsx is the menu — delete entries they don't want, reorder, rename. Optional extra: a Translate page exists (views/TranslateView.tsx, not in the menu; it uses a speech-to-text endpoint at /whisper and the free MyMemory translation API).
• Colours and fonts: src/styles/theme.css tokens; fonts in src/styles/fonts.css (--f-hand, --f-print).
• Radar map: RadarMap.tsx LAT/LON + labels; src/lib/tokyoGeo.ts holds the sea, coast and river outlines as SVG paths in zoom-9 Web-Mercator pixels relative to the centre. For their area, fetch natural=coastline and waterway=river ways in a ~150 km box from OpenStreetMap (Overpass API), project each point with the file's lonToX/latToY at zoom 9 minus the centre's, and write the paths — or set the three exports to ""/[] to show the radar alone.
• Currency and tariff: the ¥ sign in EnergyView.tsx (savings), and the tariff in their savings helpers.
• Language: see "How it works → i18n".

#Gotchas

• Clock and timezone: the demo deliberately reads the tablet's wall clock as Tokyo time so every visitor sees a sky that matches the clock. Live, set LAT/LON and make TYO follow the tablet (Step 3) — otherwise the sky is hours off. The tablet must be set to the home's timezone.
• iPad / WebKit: Safari throttles timers and three.js in background tabs and when the screen sleeps — after waking, the sky and clock catch up on the next minute (a visibilitychange handler refreshes the sky). Add to Home Screen for full-screen; old iPads (3 GB RAM) can struggle with the 3D curtain page — it is the heaviest view; open it on demand rather than as the start page.
• Memory on big installations: keep per-view subscriptions (never subscribe to all states); the "Lights on" list polls /api/states every 30 s — on thousands of entities raise pollMs in useRealLights.
• Mixed content: a dashboard on https:// cannot talk to http:// Home Assistant — serve it from HA itself (mode A) and the address matches.
• Pictures: WebP needs iOS 14+. Keep the house drawing's background truly transparent (the sky must show through); large pictures (over ~2000 px) cost memory on tablets for no visible gain.
• prefers-reduced-motion is honoured: animations and transitions collapse to instant, rain/snow draw one still frame. Turn it off on the tablet if they want the full effect.
• Entities that don't exist draw nothing rather than crash, so a forgotten id looks like "nothing happens" — check the browser console and ha-entities.txt when a control seems dead.
• Services with responses (weather.get_forecasts) in mode C go over REST because the dev proxy can mangle large WebSocket frames (already set up in main.live.tsx).

#Licences

• Code: MIT — see LICENSE ("Copyright (c) 2026 dashboards.casa").
• Fonts: each under the SIL Open Font License 1.1, licence file next to it — Shantell Sans (src/assets/fonts/OFL-ShantellSans.txt), Trirong (src/assets/fonts/OFL-Trirong.txt), Manrope (static/fonts/OFL-Manrope.txt). Japanese fonts are loaded from Google Fonts at runtime (OFL as well).
• The made-up home's pictures: made for this demo (generated from text prompts, no reference photos) — free to use as examples and placeholders.
• npm packages (React, three.js, Vite, @mdi/js icons, home-assistant-js-websocket …): their own licences, in node_modules/<package>/LICENSE after npm install.
• Radar tiles: RainViewer's free public API — check its current terms (attribution) before a public deployment.