Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(home-bridge): gate Home Assistant's own turn-off tool before it unlocks a door

nirholasf54b124df161
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17ee4c0f4..fee60eaa4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
## 2026-09-02
- **Docs · Materialize: turn a generation into a real object** (`/docs/materialize`): How to print any three.ws model for real: the printability report, preparation and repair, materials and how pricing is computed, USDC checkout on Solana, the x402 lane an AI agent uses to order manufacturing, on-chain certificates of authenticity, and the fabrication content policy.
+- **Docs · three.ws Home** (`/docs/smart-home`): How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.
- **Generated animation seeding** (`/docs/animation-seeding`): How three.ws generates its own animation clips: the text-to-motion GPU lane, the world-space quality gate that judges joint positions instead of raw rotations, the resumable bulk runner, and the rotating free subset.
- **Materialize** (`/materialize`): Turn any 3D model into a real printed object. Live printability analysis and automatic repair, a true-scale AR preview on your own desk, an itemized price from the mesh's own measured volume, and USDC checkout on Solana.
- **NVIDIA NGC Container EULA** (`/legal/nvidia-ngc-eula`): License terms for three.ws container images distributed through the NVIDIA NGC catalog: what the license covers, the model weights the image does not ship, and the data the container does not collect.
@@ -23,12 +24,14 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Examples gains a voice, an AI's eye on 3D, and a filter**: Three more runnable examples and a way to find them. The avatar can now speak a line you type: the free text-to-speech lane synthesizes it and a new speakAudio() method routes the audio through the same analyser the built-in voice uses, so the mouth follows the real waveform instead of miming. A second example calls the look_at_model tool on the public MCP server and shows exactly what an AI assistant sees when it inspects a mesh: four rendered angles plus a plain-language read on the geometry, which is how an agent judges its own output and decides to try again. A third reads the live tool list off that same server, so the page can never advertise a tool that was renamed or dropped. With seventeen examples the page also gets a filter: type to search names, descriptions and tags, or narrow by tag, and the lanes fold away as they empty. A deep link always wins over an active filter. (`/examples`) `[feature, improvement, sdk]`
- **Fact checks stop saying "not enough evidence" when the evidence was there**: A fact check reads five sources and asks a language model where each one stands on the claim. When that model answered in a shape the reader could not parse, every source was quietly recorded as saying nothing, the check reported "not enough evidence", and nothing anywhere said the reading had failed. A live check on whether a tomato is a vegetable came back that way while holding the Supreme Court case that settles the question. The reader now copes with the formats models actually use, including the thinking-out-loud preamble and code fences it used to choke on, and it no longer stops at the first square bracket it sees. When a reply genuinely cannot be read, the check now says it was degraded instead of presenting a verdict it did not earn, which also keeps that answer out of the week-long cache and out of the published accuracy score. The same fault had been collapsing the three search angles behind each check down to one. (`/fact-checker`) `[fix, improvement]`
- **Fixed a footer link that led to a dead page**: The terminal page's footer offered an Avatars link that pointed at an address the site does not serve, so clicking it returned a 404 instead of the avatar gallery. It now opens the gallery, the same place every other page sends you. On the knock page, a placeholder link that sat empty until the profile finished loading was removed, so people navigating by keyboard or screen reader no longer land on a link with no name and nowhere to go. (`/tty`) `[fix]`
+- **Groundwork for agents that can run your house**: A three.ws agent already has a body, a voice and a memory, all of it stuck inside a browser tab. This is the first piece of letting it reach past the screen: a new developer package, @three-ws/home-bridge, that connects an agent to a real Home Assistant, the open-source home platform that already runs in millions of houses and already speaks to Zigbee, Z-Wave, Matter, Thread and about fifteen hundred other things. We wrote no device code at all, on purpose. What the package adds is the part nobody had built: live state from the house shaped into rooms, so a 3D scene can dim when your real lights dim; "good night" and "I'm leaving" resolved to the scenes you already made yourself, in Home Assistant, rather than to something we invented for you; and a safety gate that reads the way our on-chain one does. Turning a light off is free. Unlocking a door stops and asks you, every time, until you say otherwise for that one door. Locking up never asks, because moving your house toward safety should not need permission. That last part turned out to matter more than expected: Home Assistant's own "turn it off" command performs an unlock when you point it at a lock, so an assistant told to turn something off can open your front door with nothing in the command's name to warn anyone. Our gate catches it. All of it was built and checked against a real Home Assistant running here, not against stand-ins, and the write-up of what else is out there and where this goes next (voice in every room, the agent standing in a live model of your home) is published alongside it. (`/docs/smart-home`) `[sdk, docs, security]`
- **License terms for three.ws containers on NVIDIA NGC**: three.ws is preparing to publish its image-to-3D inference server in NVIDIA's NGC catalog, so the licence that will cover those container images is now public. It states plainly what you get: Apache-2.0 source, no model weights inside the image (you bring your own, under the upstream licence), and a container that carries no analytics or telemetry and sends nothing back to us. It sits alongside the other policies on the legal page. (`/legal/nvidia-ngc-eula`) `[docs]`
- **Limited editions: cap how many copies of your model can ever exist**: Any model you forged now has a Physical editions panel on its page where you set one number: how many physical copies of it may ever be printed. Leave it empty and it stays an open edition, which is what every model is by default. Set it and the number starts meaning something everywhere: the price panel tells a buyer which number they would be and how many are left, a sold-out edition is refused where the price is quoted rather than after someone has paid, and every certificate that ships reads "3 of 25" for good. It counts copies that actually shipped rather than orders people started, so an abandoned checkout never strands the last one, and it cannot be lowered below what has already left the building, because a certificate reading "edition 7 of 5" would be a lie already in somebody's hands. There is also now a page at /cert for looking a certificate up by the number printed on its card, and a certificate whose on-chain proof was delayed retries on its own until it lands. (`/materialize`) `[feature, improvement]`
- **Materialize checkout: buy a real print, or let an agent buy one**: You can now order a physical print of a model and pay for it. Quote the job, pick a material and a size, and checkout hands you a payment in USDC on Solana with the itemised price you were shown, never a recomputed one. Once the payment lands the order moves into safety screening on its own, and every step writes to a timeline you can read at any time. The same checkout is open to AI agents at /api/x402/print-order: an agent quotes the job, pays, and a real object is manufactured and shipped to a street address, with no account anywhere in the loop. Prices come from one catalog file and nothing else, a quote is signed so it cannot be altered on the way to checkout, and an order that was never going to be accepted is refused before anyone is charged. (`/materialize`) `[feature, sdk]`
- **Materialize will not print a weapon, a key to your door, or somebody else's brand**: Printing something is not like generating a picture of it. A refused image costs nobody anything; a printed firearm part is a crime in most of the places we ship to, and a working copy of a key is a burglary tool. So Materialize checks every order twice, and the rules are code rather than a polite request. It refuses firearm components, suppressors, ammunition and magazines, keys and lock picks, counterfeit goods and other people's brand marks, concealed and spring-loaded blades, drug paraphernalia, and realistic firearm likenesses at life size. The first check runs before you are ever asked to pay, so a refusal costs nothing, and it names the category, links the policy, and says what you can print instead. The second runs on the paid order on its way to the printer, and an order that fails it is refunded rather than quietly shipped. What this deliberately does not do is refuse the ordinary: a tabletop miniature carrying a weapon prints, a blunt prop sword prints, your own logo prints. Full policy is in the docs. (`/materialize`) `[feature, security]`
- **Materialize: your generation, printed and posted to you**: Everything the forge makes has lived on a screen. Materialize prints it and ships it. Point it at any model, yours or one from the gallery, and it measures the mesh first: whether it is a closed solid, how many separate pieces it is, where the holes are, how thin the thinnest wall gets, and its exact volume. That measurement is the price, so nothing is guessed. Pick a material and a height and you get an itemized quote, every line shown, in resin, tough resin, nylon, full-colour sandstone, draft plastic or stainless steel. Before it prints, the model is rebuilt as a watertight solid, its holes filled, scaled to the size you chose, and hollowed with drain holes if that saves you money. Full-colour prints carry the colour sampled from the model's own texture, which is what lets a printer reproduce what you see on screen. Checkout is USDC on Solana, holders get up to fifteen percent off, and you can follow the order from screening to production to the tracking number. An AI agent can order one too, over x402, with nobody in the loop: as far as we know that makes this the first API where an agent pays and a real object turns up at a real address. (`/materialize`) `[feature]`
- **Photo mode in the coin worlds now actually hands you the photo**: Press P in a coin world, or the camera button on the heads-up display, and you get a picture of the world on a share card: the scene itself, the three.ws mark, the coin you are standing in, and, during a live event, that event's name stamped on it. The card was there but the shutter went nowhere. Every single press answered "Couldn't photograph the world just now" and showed nothing, because of a fault in the code that builds the preview, so nobody has ever actually been handed one of these. Pressing it now opens the card, with Download and Copy image next to it. The picture is taken as a separate render rather than grabbed off the screen, so no panel, name tag or chat line is ever in the frame, and it works the same in zen mode, which is when most people will want it. It costs nothing when you are not using it: none of photo mode is loaded until the first press. Two smaller things fixed alongside: taking a second photo while the first card is open now replaces it cleanly instead of briefly stacking two sheets, where a click landing in the wrong moment could dismiss the shot you just took; and the line promising that P takes another one is true now, and visible, having previously rendered as nothing at all. The camera button also stays lit while the picture is being taken, instead of going quiet: taking the photo is real work, and on a slow phone it can run for a few seconds, which previously looked like a button that did nothing. Verified end to end in both Chrome and Safari, on a laptop frame and a phone frame, down to the pixels in the saved file, so the black rectangle that a mishandled 3D screenshot usually produces cannot come back unnoticed. (`/play`) `[fix, feature]`
+- **Take a photo of your world and post it**: Press P in a /play world, or the camera button on the HUD, and the world is captured onto a share card: your view of the town with the three.ws mark, the coin you are standing in and the date along the bottom, ready to download or paste straight into a post. The interface is never in the shot. The photo is a second frame rendered off screen just for you, so the chat, the job board and the name tags stay out of the picture no matter what is on screen when you press. It works in zen mode too, which is usually exactly when the world looks worth photographing, and while an event is running the card carries that event's name. Nothing is uploaded anywhere: the card is built in your browser and it is yours. The whole feature only downloads on your first press, so a session that never takes a photo never pays for it. (`/play`) `[feature]`
- **Text-to-animation is no longer rationed like a paid service**: Turning a sentence into an animation runs entirely on our own GPUs, but it was being counted against the allowance meant for services we pay a third party for: thirty a day, per person. It now uses the free allowance that lane deserves, which is eight times higher, so you can iterate on a motion prompt properly instead of running out halfway through. (`/animations`) `[improvement]`
- **The 3D Studio connector for ChatGPT is documented as the eleven tools it actually serves**: The free 3D Studio connector grew to eleven tools when look_at_model landed alongside check_job, but a lot of the writing about it had not caught up: the connector page, the press kit, the partner page, the blog summary, the announcement copy, the press release and the store-submission package still said nine or ten, and the social card enumerated only nine tool names. Every one of those now matches a fresh pull from the live server, the social card lists all eleven, and the module headers inside the connector describe the real catalog including which tools spend generation quota. A test now pins the total, so the next tool to land fails the suite instead of quietly re-opening the same drift. The standalone viewer also stopped crediting the AR launch endpoint with a renderer it no longer loads. Two smaller corrections rode along: the pending-generation example now shows the field that tells a client whether the model coming back is a bare mesh or a finished rig, and the three places the platform pins the 3D viewer library are now explained in one comment, so nobody has to guess why an embed and a standalone page load different builds. (`/docs/mcp-studio`) `[docs, fix]`
- **The animation gallery shows you clips instead of a spinner**: The motion library is nearly 3,000 clips and growing, and /animations used to download the entire catalog before it would draw a single card. Now the first batch of clips appears as soon as it arrives and the rest fill in behind it while you are already browsing, searching and filtering. However large the library gets, you start looking at animations after the same short wait. (`/animations`) `[improvement]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index feecc81a6..92eae72bd 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -119,6 +119,7 @@ bottom.
| `/play` event souvenirs (a free wearable you keep for having been there) | Config `public/event.json` (`souvenir.cosmeticId`, the same file the countdown reads). Server: window/world/item resolution [multiplayer/src/event-drop.js](multiplayer/src/event-drop.js), join-time grant `_grantEventSouvenir` in [multiplayer/src/rooms/WalkRoom.js](multiplayer/src/rooms/WalkRoom.js), `event` tier + catalog entry [multiplayer/src/cosmetics-catalog.js](multiplayer/src/cosmetics-catalog.js), unlock + persistence [multiplayer/src/economy.js](multiplayer/src/economy.js). Client: drop card [src/game/event-souvenir.js](src/game/event-souvenir.js), wardrobe treatment [src/game/cosmetics-wardrobe.js](src/game/cosmetics-wardrobe.js). Asset: [public/accessories/laurel-meetup.glb](public/accessories/laurel-meetup.glb) generated by [scripts/generate-accessory-glbs.mjs](scripts/generate-accessory-glbs.mjs), poster by [scripts/render-accessory-thumbs.mjs](scripts/render-accessory-thumbs.mjs) | In-repo | Everyone who joins the event world between an event's `startsAt` and `endsAt` is granted a free commemorative wearable (the Meetup Laurel), once, forever, wearable in every coin world. After `endsAt` it is never granted again and there is no purchase path at any point: a third catalog tier, `event`, carries `price: 0`, so the boutique's `tier === 'premium' && price > 0` filter excludes it by construction and the x402 purchase ledger is filtered to premium ids so it cannot mint one. Server-authoritative and idempotent: the window and the world both come from the shared event config (never a client option), the grant is a no-op on an account that already owns it, and the one-shot `souvenir` message only fires on the not-owned to owned transition, so a reconnect produces neither a duplicate nor a second announcement. Fails open on every axis (no config, unreachable config, closed window, wrong world all mean grant nothing and never delay a join). Doc: [docs/event-souvenirs.md](docs/event-souvenirs.md). Tests: [tests/event-souvenir.test.js](tests/event-souvenir.test.js); live conformance `node scripts/play-souvenir-conformance.mjs` (real server, no browser) and `node scripts/play-souvenir-e2e.mjs` (real browser) |
| `/play` Coin Wars portal (in-world war door, league board, spectator screen) | Client: [src/game/war-portal.js](src/game/war-portal.js) + [src/game/war-portal.css](src/game/war-portal.css) (plaza landmark, canvas league board, queue panel, results echo), wired in [src/game/coincommunities.js](src/game/coincommunities.js); arena page [pages/play/war.html](pages/play/war.html) `→ /play/war` → [src/play/war.js](src/play/war.js) + [src/play/war-world.js](src/play/war-world.js) + [src/play/war.css](src/play/war.css). API: [api/wars.js](api/wars.js) `→ /api/wars` over [api/_lib/wars-store.js](api/_lib/wars-store.js) (ledger + queue + live registry) and [api/_lib/war-ticket.js](api/_lib/war-ticket.js) (signs a pairing). Server: [multiplayer/src/rooms/ClashRoom.js](multiplayer/src/rooms/ClashRoom.js) `clash_arena`, pairing math [multiplayer/src/war-matchmaking.js](multiplayer/src/war-matchmaking.js), ticket verify [multiplayer/src/war-ticket.js](multiplayer/src/war-ticket.js), spectator snapshots [multiplayer/src/war-live.js](multiplayer/src/war-live.js), league math [multiplayer/src/war-standings.js](multiplayer/src/war-standings.js), portal location [multiplayer/src/world-features.js](multiplayer/src/world-features.js) `WAR_PORTAL` | In-repo | F18. Coin Wars ran full community-vs-community battles with an Elo league behind it and no door into it from any world. The portal is that door: a plaza landmark whose board shows this coin's real league standing, its last battles, and any war running right now (read from `/api/wars`, folded through the arena's own standings module, never a second implementation). Press `E` to run the coin's holder gate and queue the community; the matchmaker pairs it with another waiting community, seals both sides into an HMAC war ticket, and hands the player to `/play/war` with a return link carrying the full coin identity, so walking back lands in the same world with the result already echoing on the board. While a war is live the board becomes a spectator screen (score, round clock, kill feed) off a cheap poll, and a win takes the board over for a few seconds. Costs nothing when nobody is near it: no poll fires outside `WAR_PORTAL_BOARD_REACH`. Docs: [docs/coin-wars.md](docs/coin-wars.md). Tests: [tests/war-matchmaking.test.js](tests/war-matchmaking.test.js), [tests/clash-match.test.js](tests/clash-match.test.js) |
| `/play` event countdown (lobby banner + in-world pill) | Self-attaching module [src/game/event-countdown.js](src/game/event-countdown.js) loaded by [pages/play.html](pages/play.html); config `public/event.json` (single source of the event window; the file is the edit surface for scheduling an event), read through the shared parser + state machine in [src/shared/event-config.js](src/shared/event-config.js). Verified end to end in a real browser by `npm run verify:event` ([scripts/verify-event-countdown.mjs](scripts/verify-event-countdown.mjs)). Campaign orders: the `event-` files in [prompts/finish/](prompts/finish/) | In-repo | While `public/event.json` describes an upcoming or live event, the lobby shows a banner (name, tagline, local-time start, ticking countdown, CTA into the event world) and the in-world view gets a dismissible top-center pill (dismissal persisted per event in localStorage). Three explicit states: upcoming, live (pulsing marker, CTA suppressed when already standing in the event world), and over (everything unmounts, the interval stops). Zero edits to `coincommunities*.js` by design (the ambient-crowd pattern): it waits for the lobby DOM and mounts nothing when the config is missing, malformed, or expired. |
+| `/play` photo mode (the share card people post) | Lazy client module [src/game/photo-mode.js](src/game/photo-mode.js) (event stamp, card compositor, preview sheet); the offscreen render itself is [src/game/scene-capture.js](src/game/scene-capture.js), shared with the build thumbnail; HUD button + busy/pressed states in [src/game/coincommunities-ui.js](src/game/coincommunities-ui.js) (`#cc-photo-btn`, `setPhotoActive`/`setPhotoBusy`); `P` key and the import site in [src/game/coincommunities.js](src/game/coincommunities.js) (`_openPhotoMode()`); styles in [src/game/coincommunities.css](src/game/coincommunities.css); event stamp read from `public/event.json` | In-repo | Press `P` (or the HUD camera button) and the world is composited onto a share card: the shot, the three.ws mark, the coin and world it came from, the date, and, while an event window is open, that event's name in a pill. **The chrome is never in the shot, by construction rather than by hiding it:** the capture is one extra frame rendered into a `WebGLRenderTarget` on demand, not a read of the live canvas, so the HUD, chat and nameplates were never in the GL frame and `preserveDrawingBuffer` (a full buffer copy on EVERY frame, for the sake of a rare screenshot) stays off. That is also why it cannot black-frame: the classic `domElement.toDataURL()` bug returns black because the compositor has already cleared the drawing buffer, and this path never reads it. Works in zen mode on purpose (a world with no chrome on it is exactly the shot people want), survives a retake over an open card, and the whole module is imported on the FIRST press, so a session that never takes a photo never downloads it. Copy-to-clipboard is feature-detected per engine and says so when a browser refuses, rather than failing quietly; Download saves the same PNG either way. Nothing leaves the browser. Tests: [tests/photo-mode.test.js](tests/photo-mode.test.js) (compositor + sheet under jsdom, capture stubbed). Real-browser proof, both engines: `node scripts/play-photo-mode-check.mjs` ([scripts/play-photo-mode-check.mjs](scripts/play-photo-mode-check.mjs)); `MODE=scene` drives the shipped `takePhoto` over a real WebGLRenderer in seconds and measures the captured pixels, `MODE=world` boots the actual world and drives the key and the button. |
| The event landing page (`/event`) | [pages/event.html](pages/event.html) `→ /event`, page module [src/event-page.js](src/event-page.js); config `public/event.json` (the SAME file the `/play` countdown reads, never a second copy of the times); live population [api/play/population.js](api/play/population.js) `→ /api/play/population`, backed by the multiplayer server's public `/population` aggregate in [multiplayer/src/index.js](multiplayer/src/index.js) | Live | The one link the community shares before and during an event, written for someone with zero context. Hero countdown ticking off `public/event.json`, a single large CTA into the event world, a plain-language "what to expect" built only from what `/play` actually does, and the run of show rendered in the visitor's own timezone with an "Add to calendar" button that builds a real RFC 5545 `.ics` in the browser (no third-party calendar service, so the guest list never leaves the device). Four designed states: upcoming (days/hours/minutes/seconds), live (LIVE marker plus the real number of people standing in the world), ended (says it happened, relabels the agenda to "What happened", and still routes people into `/play`), and no-config (an honest "no event scheduled" with the same door). The live number is real or absent: when the multiplayer server is unreachable the panel keeps the live state and drops the count instead of inventing one. Doc: [docs/api-reference.md](docs/api-reference.md#play-population-api). |
| Home page event strip (`/`) | Self-attaching module [src/home-event-banner.js](src/home-event-banner.js) loaded by [pages/home.html](pages/home.html); same config `public/event.json` through [src/shared/event-config.js](src/shared/event-config.js) | Live | Puts the live event in front of everyone who lands on three.ws, not just the people who already opened `/play`. A slim announcement bar between the nav and the hero: event name, start time in the visitor's own timezone, a countdown ticking to the second, and one CTA into the $THREE world (suppressed when the visitor is already there). Same three states as the `/play` surfaces and the same auto-unmount at `endsAt`, flipping upcoming to live without a reload. Dismissal shares the `/play` pill's `cc-event-dismissed:<startsAt>` key, so waving the reminder away on the home page also clears it in-world; the `/play` lobby banner stays, because it is lobby content rather than an overlay. Styled from the home page's own tokens (mono kicker, hairline pill CTA) and light-theme aware. Verified with `npm run verify:event`. |
| `/play` friends, presence & verified profiles (drawer, cross-world DMs, in-world profile cards) | Client: [src/game/friends-panel.js](src/game/friends-panel.js) (shared with `/walk`), mounted in [src/game/coincommunities.js](src/game/coincommunities.js) `_openFriends()`/`_closeFriends()`, HUD button + unread badge in [src/game/coincommunities-ui.js](src/game/coincommunities-ui.js), account-level state/polling in [src/friends.js](src/friends.js), profile card in the shared inspector [src/shared/avatar-inspector.js](src/shared/avatar-inspector.js) (`renderProfile`). Server: signed ticket verify + `socialHub` registration + verified `username` on the Player schema in [multiplayer/src/rooms/WalkRoom.js](multiplayer/src/rooms/WalkRoom.js) + [multiplayer/src/schemas.js](multiplayer/src/schemas.js), ticket signer [api/_lib/presence-store.js](api/_lib/presence-store.js) / verifier [multiplayer/src/presence-token.js](multiplayer/src/presence-token.js), hub in [multiplayer/src/social-hub.js](multiplayer/src/social-hub.js) | In-repo | W09+W10 of the World Online program (program brief retired to git history). Press `J` or the HUD `Friends` button to open a right-docked drawer showing your account's friend graph; live online/offline presence per coin world, requests, and DM threads; the same graph and threads `/walk` and the standalone `/friends` page already share. `community-net.js` carries a signed presence ticket into every `walk_world` join and forwards the server's `social` push onto its own event bus, which is what makes a `/play` player visible to friends and able to receive a live DM. W10 makes the platform identity first-class in-world: the ticket also carries the account's username + display name (signed, so nobody can wear a handle they don't own), WalkRoom publishes the verified `username` on the Player schema, nameplates show the @handle, the signed-in lobby defaults to the account's display name with an @handle chip, and clicking any verified player (or `I`) opens their real three.ws profile card in the shared avatar inspector: bio, follower counts, follow/unfollow (`/api/users/:username/follow`), the right friends verb (Message → the in-world DM drawer when already friends, Add friend / Accept otherwise), their latest creations, and a link to `/u/<username>`. Works identically in `/walk` (same room, same inspector). Tests: [tests/play-friends-presence.test.js](tests/play-friends-presence.test.js), [tests/play-profile-identity.test.js](tests/play-profile-identity.test.js). |
@@ -346,6 +347,7 @@ packages/loom-mcp/ → @three-ws/loom-mcp (MCP server — Lo
packages/spatial-mcp/ → @three-ws/spatial-mcp (Spatial MCP validator, builder + conformance fixture corpus)
packages/agent-sniper/ → @three-ws/agent-sniper (engine + CLI + MCP server + x402 paid API — autonomous, self-custodial pump.fun sniper)
packages/companion-sdk/ → @three-ws/companion (personal companion: client + SSE stream, shared triage rules, page stage, CLI, MCP server)
+packages/home-bridge/ → @three-ws/home-bridge (agent to a real home: Home Assistant state + actions, room graph for the 3D scene, physical-action gate)
walk-sdk/ → @three-ws/walk (page walking companion + playground + avatar picker)
herald-sdk/ → @three-ws/herald (deliver a message in person: rules engine, avatar/card presenters, sources, CLI)
tour-sdk/ → @three-ws/tour (guided site tour: 3D guide walks a live site, spotlights sections)
@@ -409,6 +411,7 @@ npm).
| `@three-ws/strategies` | [packages/strategies/](packages/strategies) | `api/strategies.js`, `dca-strategies.js`, copy/mirror engines | Automated trading strategies (DCA, copy, mirror) |
| `@three-ws/pumpfun-skills` | [packages/pumpfun-skills/](packages/pumpfun-skills) | [pump-fun-skills/](pump-fun-skills) | pump.fun create-coin / swap / fees skills (runtime mint) |
| `@three-ws/portal` | [packages/portal/](packages/portal) | `api/portal` | Any website as a walkable 3D world: pure layout, API client, CLI, MCP server |
+| `@three-ws/home-bridge` | [packages/home-bridge/](packages/home-bridge) | `docs/smart-home.md` | The agent's connection to a real house. Live Home Assistant entity state and service calls over the first-party WebSocket API, the user's own curated tools over the `mcp_server` MCP endpoint, a floor/area/entity room graph with per-room lighting, climate and security rollups for the 3D scene, household macros resolved to the scenes the user already built, and a physical-action gate that never lets an unlock through without an explicit yes. Zero device code: Home Assistant owns Zigbee, Z-Wave, Matter, Thread and the other 1,500 integrations. Docs: [docs/smart-home.md](docs/smart-home.md) |
| `@three-ws/irl` | [packages/irl/](packages/irl) | `api/irl/`, `_lib/geohash.js` | Geofenced real-world presence + nearby discovery |
| `@three-ws/sign-language` | [packages/sign-language/](packages/sign-language) | `/sign-language`, `/asl-alphabet`, signed chat replies | The ASL engine as a published bundle: text → one signed clip, zero runtime dependencies |
| `@three-ws/pose` | [packages/pose/](packages/pose) | `get_pose_seed`, `api/mcp-3d.js` | Pose-seed generation for rigged avatars |
diff --git a/data/changelog.json b/data/changelog.json
index f2d290db4..26f9f6fbb 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,26 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-09-02",
+ "title": "Take a photo of your world and post it",
+ "summary": "Press P in a /play world, or the camera button on the HUD, and the world is captured onto a share card: your view of the town with the three.ws mark, the coin you are standing in and the date along the bottom, ready to download or paste straight into a post. The interface is never in the shot. The photo is a second frame rendered off screen just for you, so the chat, the job board and the name tags stay out of the picture no matter what is on screen when you press. It works in zen mode too, which is usually exactly when the world looks worth photographing, and while an event is running the card carries that event's name. Nothing is uploaded anywhere: the card is built in your browser and it is yours. The whole feature only downloads on your first press, so a session that never takes a photo never pays for it.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/play"
+ },
+ {
+ "date": "2026-09-02",
+ "title": "Groundwork for agents that can run your house",
+ "summary": "A three.ws agent already has a body, a voice and a memory, all of it stuck inside a browser tab. This is the first piece of letting it reach past the screen: a new developer package, @three-ws/home-bridge, that connects an agent to a real Home Assistant, the open-source home platform that already runs in millions of houses and already speaks to Zigbee, Z-Wave, Matter, Thread and about fifteen hundred other things. We wrote no device code at all, on purpose. What the package adds is the part nobody had built: live state from the house shaped into rooms, so a 3D scene can dim when your real lights dim; \"good night\" and \"I'm leaving\" resolved to the scenes you already made yourself, in Home Assistant, rather than to something we invented for you; and a safety gate that reads the way our on-chain one does. Turning a light off is free. Unlocking a door stops and asks you, every time, until you say otherwise for that one door. Locking up never asks, because moving your house toward safety should not need permission. That last part turned out to matter more than expected: Home Assistant's own \"turn it off\" command performs an unlock when you point it at a lock, so an assistant told to turn something off can open your front door with nothing in the command's name to warn anyone. Our gate catches it. All of it was built and checked against a real Home Assistant running here, not against stand-ins, and the write-up of what else is out there and where this goes next (voice in every room, the agent standing in a live model of your home) is published alongside it.",
+ "tags": [
+ "sdk",
+ "docs",
+ "security"
+ ],
+ "link": "/docs/smart-home"
+ },
{
"date": "2026-09-02",
"title": "A polish pass over the coin worlds, from the friends drawer to every button on a phone",
diff --git a/data/pages.json b/data/pages.json
index 2a203c447..6ce6e21b7 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -2613,6 +2613,14 @@
"changefreq": "monthly",
"added": "2026-08-16"
},
+ {
+ "path": "/docs/smart-home",
+ "title": "Docs \u00b7 three.ws Home",
+ "description": "How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-09-02"
+ },
{
"path": "/docs/tty-avatar",
"title": "Docs · Terminal avatar",
diff --git a/docs/smart-home.md b/docs/smart-home.md
index a6791f35e..73c730082 100644
--- a/docs/smart-home.md
+++ b/docs/smart-home.md
@@ -1,6 +1,7 @@
# three.ws Home: the agent as the interface to your physical space
-**Status:** research complete, architecture decided, implementation staged.
+**Status:** research complete, architecture decided, phase 1 built and verified against a
+real Home Assistant instance.
**Date:** 2026-09-02.
**Question asked:** can the three.ws 3D agent control a real home, and how much of it already exists in open source?
@@ -94,12 +95,17 @@ the idea already has an audience, and [hacs/integration](https://github.com/hacs
1. **Home Assistant as the device layer.** We write zero device drivers. Not one. Zigbee,
Z-Wave, Matter, Thread, BLE, cloud APIs, IR blasters, the long tail of 1,500 integrations:
that is a decade of work by 10,000 contributors and it is already in the user's house.
-2. **`mcp_server` for actions.** The user's home becomes just another MCP server in an
- ecosystem where we already run 40+ of them. No new wire format, no new auth story, no
- custom command schema, and every capability the user exposes to their own LLM is exposed
- to their three.ws agent with identical permissions.
-3. **`home-assistant-js-websocket` for state.** MCP is request/response. A living 3D scene
- needs a push stream. This library is first-party, dependency-free, and reconnects itself.
+2. **`home-assistant-js-websocket` as the always-available channel.** State *and* actions.
+ It is first-party, dependency-free, reconnects and resubscribes itself, and works on any
+ instance with nothing but a token. MCP is request/response; a living 3D scene needs a push
+ stream, and this is it.
+3. **`mcp_server` as the capability upgrade.** When a home has it enabled, that home becomes
+ just another MCP server in an ecosystem where we already run 40+ of them: no new wire
+ format, no new auth story, no custom command schema, and every capability the user exposed
+ to their own LLM is exposed to their three.ws agent with identical permissions. Verified
+ against a live instance: 29 real tools, no code of ours behind any of them. It is an
+ upgrade rather than a requirement because it has to be set up first, and a bridge that
+ only worked on configured instances would leave most homes out.
4. **HA scenes and scripts for macros.** "Good night" and "I'm leaving" are not new concepts
we invent. They are `scene.turn_on` and `script.turn_on`, already modelled, already
editable by the user in an interface they know. Our agent resolves intent to an existing
@@ -180,7 +186,20 @@ this control, so we inherit it rather than inventing a parallel one). Locks, gar
alarm panels, and anything HA marks as a security entity require an explicit confirmation
every time until the user grants a standing allowance per entity. A voice channel that can
unlock a front door on a misheard phoneme is not a feature, and the first-party HA exposure
-setting is the correct place for that boundary to live.
+setting is the correct place for the outer boundary to live.
+
+One finding from building this makes the gate non-optional, and it is not obvious from the
+outside. Home Assistant's own Assist tools are polymorphic, and its published description of
+`intent__HassTurnOff` reads:
+
+> Turns off/closes a device or entity. **For locks, this performs an 'unlock' action.**
+
+So a model that has been told to turn something off can unlock a front door, and nothing in
+the tool name says so. Confirmed against a live instance: with a lock exposed to Assist (which
+is exactly what a user who wants voice lock control does), `HassTurnOff` on it really does
+unlock the door. Our gate therefore has to sit in front of the MCP channel too, resolving each
+call's targets to real entities and working out the service each one would actually perform.
+That is `classifyMcpCall` in the bridge.
---
@@ -188,12 +207,13 @@ setting is the correct place for that boundary to live.
Each phase is shippable on its own and none of them block on the next.
-**Phase 1: connect and act.**
-`packages/home-bridge/` holds one client with the two channels (MCP over
-`@modelcontextprotocol/sdk`, which is already a dependency at `^1.29.0`, and state over
-`home-assistant-js-websocket`). A home connection record, a `/home` connect flow that takes
-a base URL and a long-lived token, and the home tools registered into the existing agent
-tool catalog. Verified against a real Home Assistant instance in Docker, not a fixture.
+**Phase 1: connect and act. Built.**
+[`packages/home-bridge/`](../packages/home-bridge) is the client: the WebSocket channel for
+state and actions, the MCP channel for the user's curated tools, the room graph, intent
+resolution against the house's own scenes, and the physical-action gate in front of both. See
+[its README](../packages/home-bridge/README.md). What remains in this phase is product
+surface, not protocol: the connection record, a `/home` connect flow, and registration of the
+home tools into the existing agent tool catalog.
**Phase 2: the 3D home.** `/home` renders a live scene from the entity registry: areas
become rooms, lights become lights, and the agent stands in it. Scene lighting is driven by
@@ -209,7 +229,37 @@ and robots, and it is the same protocol either way.
---
-## 6. Licensing
+## 6. What was actually verified
+
+Nothing in this document is inferred from documentation alone. A real Home Assistant
+(`ghcr.io/home-assistant/home-assistant:stable`, the `demo` integration, 122 entities across
+three areas and one floor, plus two user scenes named "Bedtime" and "Away Mode") was run in
+Docker and driven through the bridge:
+
+| Claim | How it was checked | Result |
+|---|---|---|
+| The WebSocket channel needs nothing but a token | `HomeBridge.connect()` against the live instance | Connected, 3 rooms, 1 floor, 122 entities |
+| Live state drives the 3D scene | Ran the house's "Bedtime" scene, read the room graph back | Bedroom brightness fell to 0.157 with colour `[255, 164, 82]`, other rooms went dark |
+| A macro resolves to the user's own scene | `activate('good night')` in a house with no scene called "Good night" | Resolved to `scene.bedtime` at 0.95 confidence and ran it |
+| A macro with no match stays silent | `activate('movie time')` in a house with no movie scene | No match, nothing fired |
+| The gate blocks an unlock | `call('lock', 'unlock', ...)` with no confirmation | Refused; door stayed locked |
+| Confirmation lets it through | The same call with `{ confirmed: true }` | Door unlocked |
+| Locking up never prompts | `call('lock', 'lock', ...)` | Ran, no prompt |
+| `mcp_server` gives us the user's tools | Enabled the integration, opened the MCP channel | 29 real tools; a tool call turned on a real light |
+| HA's own `HassTurnOff` unlocks locks | Exposed a lock to Assist, called it through the gate | Gate refused; with `{ confirmed: true }` the door really did unlock |
+| A bad token reads as auth, not as an outage | Connected with a junk token | `code: 'auth'` |
+| A home without `mcp_server` is not an error | Opened the MCP channel against a nonexistent API | `code: 'no_mcp'` with a recovery message |
+
+The registry snapshot from that instance is checked in as the package's test fixture
+(`packages/home-bridge/tests/fixtures/home.json`, regenerated by
+`scripts/capture-home-fixture.mjs`), so a Home Assistant registry change shows up as a failing
+test rather than as a surprise in someone's house. The live checks above are also a test file
+(`packages/home-bridge/tests/live-home.test.js`), which skips itself unless
+`HOME_ASSISTANT_URL` and `HOME_ASSISTANT_TOKEN` are set.
+
+---
+
+## 7. Licensing
Everything we take into our own process is permissive: Apache-2.0 (Home Assistant, the JS
WebSocket client, matter.js, openWakeWord), MIT (Wyoming's reference implementation,
diff --git a/docs/start-here.md b/docs/start-here.md
index 29ffc8597..a43c61a52 100644
--- a/docs/start-here.md
+++ b/docs/start-here.md
@@ -120,6 +120,7 @@ Want the model in your hands rather than on a screen? [Materialize](./materializ
- **Need a ready-made character or prop?** → The [Character Library](./character-library.md) has 106 rigged characters (one click into the Studio, Animation Studio, or an embed) and the [Object Library](./object-library.md) has hundreds of CC0 props with live preview, AR placement, and direct GLB download
- **Rendering avatars outside the viewer?** → [Media and render API](./media-api.md): avatar PNG renders for `<img>` tags, posed clip renders, the runtime GLB optimizer, the CORS-open model proxy, and the free vision and speech-to-text endpoints; companion to the [3D API](./3d-api.md)
- **Want the avatar in your terminal, or as your coding agent's face?** → [Terminal avatar](./tty-avatar.md): `npx @three-ws/tty-avatar <avatar id>` draws any avatar or agent body live in a terminal (truecolor half-blocks, braille, or plain ASCII, no browser or GPU), and `install-hooks --write` ties its moods to Claude Code so it thinks while the agent reads, works while it edits, and celebrates when it finishes
+- **Want the agent to reach past the screen?** → [three.ws Home](./smart-home.md): the plan for an agent that runs your house, and the [`@three-ws/home-bridge`](../packages/home-bridge/README.md) package that already connects one to a real Home Assistant. Live state from your rooms so a 3D scene dims when your real lights dim, "good night" resolved to the scene you already built yourself, and a gate that stops and asks before anything unlocks a door
- **Putting avatars in your build pipeline?** → [Avatar CLI](./avatar-cli.md): four offline commands that scaffold a hash-anchored avatar manifest from a wallet and a GLB, validate it against the published schema, and print an embed snippet that renders. Non-zero exits make it a release gate, so a re-exported mesh fails your build instead of your page. [Ship an avatar manifest](./tutorials/ship-an-avatar-manifest.md) is the guided walkthrough
- **Uploaded an avatar that loads but never moves?** → [Rig Doctor](./rig-doctor.md): drop the `.glb` and find out in a second why. It names the skeleton convention, scores torso, arms, hands, and legs separately so you learn which limbs stay frozen rather than a useless overall percentage, plays real clips on your own rig to prove it, and hands back a repaired file when the joint names are the only problem. Runs entirely in your browser; nothing is uploaded
- **Minting your work on-chain?** → [Minted 3D assets](./minted.md): the /minted gallery of avatars minted as Metaplex Core NFTs, the opt-in mint flow, baked provenance, and enforced remix royalties
diff --git a/packages/home-bridge/LICENSE b/packages/home-bridge/LICENSE
new file mode 100644
index 000000000..b5ae2a4e1
--- /dev/null
+++ b/packages/home-bridge/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2026 nirholas
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/packages/home-bridge/README.md b/packages/home-bridge/README.md
new file mode 100644
index 000000000..8a4572b03
--- /dev/null
+++ b/packages/home-bridge/README.md
@@ -0,0 +1,191 @@
+# @three-ws/home-bridge
+
+**Connect a three.ws agent to a real home.**
+
+This is the layer between a three.ws agent and [Home Assistant](https://www.home-assistant.io):
+live entity state, safe service calls, a room graph the 3D scene can render, and the optional
+Model Context Protocol channel.
+
+It deliberately implements **no device support at all**. Zigbee, Z-Wave, Matter, Thread, BLE,
+and the long tail of 1,500 integrations are Home Assistant's job, and it does that job better
+than anything we would write. This package is the 200 lines in the middle that were missing.
+
+Why this exists, what else was evaluated, and where it goes next:
+[docs/smart-home.md](../../docs/smart-home.md).
+
+## Install
+
+```bash
+npm install @three-ws/home-bridge
+```
+
+The Model Context Protocol channel is optional. Install `@modelcontextprotocol/sdk` alongside
+this package if you want it; everything else works without it.
+
+## What you need from the user
+
+A **base URL** and a **long-lived access token** (Home Assistant, Profile, Security,
+Long-lived access tokens, Create token).
+
+The URL has to be one your code can actually reach. A page served over https cannot open a
+plain-http LAN address, and a cloud server cannot route to `192.168.x.x` at all, so a home
+that is only on its own network needs a remote https URL (Home Assistant Cloud, or the
+user's own reverse proxy). `normalizeBaseUrl` and `isPrivateHost` let you say that up front
+instead of after a timeout.
+
+## Use it
+
+```js
+import { HomeBridge } from '@three-ws/home-bridge';
+
+const home = new HomeBridge({
+ baseUrl: 'https://abc123.ui.nabu.casa',
+ token: process.env.HOME_ASSISTANT_TOKEN,
+});
+
+// connect() opens the state socket, reads the floor/area/device/entity
+// registries, and resolves once the room graph is ready.
+const graph = await home.connect();
+
+for (const room of graph.rooms) {
+ console.log(room.name, room.lighting, room.climate, room.secured);
+}
+// Bedroom { total: 1, on: 1, brightness: 0.157, rgb: [255,164,82] } null null
+// Living Room { total: 2, on: 2, ... } { temperature: 23, sources: 1 } { locks: 1, unlocked: [], openings: 1, open: ['cover.living_room_window'], secure: false }
+
+// The graph rebuilds itself on every state push, so a 3D scene can just redraw.
+home.on('graph', (next) => scene.apply(next));
+
+await home.call('light', 'turn_on', { entity_id: 'light.kitchen_lights', brightness_pct: 40 });
+
+home.close();
+```
+
+### "Good night" is a scene the user already built
+
+Household macros are not something this package invents. They are `scene.*` and `script.*`
+entities the user made in an editor they already know, and their own "Bedtime" scene knows
+about the plant light and the fish tank in a way no amount of reasoning over an entity list
+will. `activate()` finds it:
+
+```js
+const { ran, match } = await home.activate('good night');
+// match: { entityId: 'scene.bedtime', macro: 'good_night', confidence: 0.95,
+// reason: '"good night" is the Good night macro, and Bedtime is this home\'s version of it.' }
+```
+
+Phrases resolve through a synonym table (`good night`, `goodnight`, `bedtime`, `time for bed`
+all reach the same place) and then through fuzzy matching on the scene names. A house with no
+matching scene returns `{ ran: false, match: null }` rather than firing the closest thing it
+can find. Pass `{ dryRun: true }` to resolve without running.
+
+## The physical-action gate
+
+**Reads are free. Writes that open the house stop and ask.** The rule is asymmetric on
+purpose: locking up, closing the garage, and arming the alarm move the house toward safety and
+never prompt; unlocking, opening, and disarming always do.
+
+```js
+try {
+ await home.call('lock', 'unlock', { entity_id: 'lock.front_door' });
+} catch (err) {
+ if (err.code === 'needs_confirmation') {
+ // err.pending: { domain, service, data, risk: 'security', entityId }
+ // Show the user what is about to happen, then repeat with the flag.
+ await home.call('lock', 'unlock', { entity_id: 'lock.front_door' }, { confirmed: true });
+ }
+}
+```
+
+`confirmed: true` represents a human saying yes. Never set it from model output.
+
+A standing allowance is per entity and per direction, never per domain: a user who lets the
+agent open the office door has not let it open the front door.
+
+```js
+home.allowList.add('lock.office_door');
+```
+
+## The MCP channel
+
+Home Assistant's first-party [`mcp_server`](https://www.home-assistant.io/integrations/mcp_server/)
+integration exposes the exact tools the user chose to give their own LLM. When a home has it
+enabled, an agent gets that curated surface for free.
+
+```js
+import { connectHomeMcp, flattenEntities } from '@three-ws/home-bridge';
+
+const mcp = await connectHomeMcp({
+ baseUrl,
+ token,
+ entities: () => flattenEntities(home.graph),
+ isAllowed: (id) => home.allowList.has(id),
+});
+
+console.log(mcp.tools.map((t) => t.name));
+// intent__HassTurnOn, intent__HassTurnOff, light__HassLightSet, climate__HassClimateSetTemperature, ...
+
+await mcp.callTool({ name: 'light__HassLightSet', arguments: { name: 'Kitchen Lights', brightness: 30 } });
+```
+
+**Pass `entities` or the gate is off, and you need the gate here more than anywhere else.**
+Home Assistant's own description of `intent__HassTurnOff` reads: *"Turns off/closes a device
+or entity. For locks, this performs an 'unlock' action."* A model told to turn something off
+can unlock a front door, and nothing in the tool name says so. `classifyMcpCall` resolves the
+call's targets against the live entity list, works out the service each one would really
+perform, and applies the same rule the WebSocket path uses. This is verified against a live
+instance in `tests/live-home.test.js`.
+
+An instance without the integration set up throws `ERR.NO_MCP`, which is an ordinary state to
+be in and not an outage. The WebSocket channel works on every instance with nothing but a
+token, so the MCP channel is always an upgrade and never a requirement.
+
+## Errors
+
+Every failure carries a `code`, because a connect screen has to tell "your token is wrong"
+apart from "your house is offline".
+
+| `code` | Means | What to tell the user |
+|---|---|---|
+| `bad_url` | Not a URL, or plain http from an https page | Use your remote https URL |
+| `auth` | Home Assistant rejected the token | Create a new long-lived token |
+| `unreachable` | No answer at all | The home may be LAN-only |
+| `needs_confirmation` | A guarded action, no explicit yes | Show `err.pending`, then confirm |
+| `no_mcp` | `mcp_server` is not enabled | Optional: offer to add it |
+| `call_failed` | Connected, request failed | Surface the message |
+| `not_connected` | Used before `connect()` | A bug in the caller |
+
+## API
+
+| Export | What it does |
+|---|---|
+| `HomeBridge` | One live connection: `connect`, `call`, `activate`, `macros`, `graph`, `states`, `on`, `close` |
+| `connectHomeMcp` | The optional MCP capability channel, gated |
+| `buildHomeGraph` | Registries plus states to the room graph. Pure |
+| `flattenEntities` | The room graph to one flat entity list |
+| `summarizeLighting` / `summarizeClimate` / `summarizeSecurity` | Per-room rollups the 3D scene reads |
+| `resolveIntent` / `matchMacro` / `MACROS` | Phrase to an existing scene or script |
+| `classifyCall` / `classifyMcpCall` / `createAllowList` | The physical-action gate |
+| `normalizeBaseUrl` / `isPrivateHost` | URL handling and the LAN reachability check |
+
+## Tests
+
+```bash
+npx vitest run packages/home-bridge
+```
+
+The default suite runs against `tests/fixtures/home.json`, a recording of a real Home
+Assistant instance rather than hand-written shapes (regenerate it with
+`scripts/capture-home-fixture.mjs`). Set `HOME_ASSISTANT_URL` and `HOME_ASSISTANT_TOKEN` to
+also run the live suite, which changes real state on a real instance:
+
+```bash
+docker run -d --name ha -p 8123:8123 ghcr.io/home-assistant/home-assistant:stable
+# add `demo:` to its configuration.yaml for a house full of entities, then restart
+HOME_ASSISTANT_URL=http://localhost:8123 HOME_ASSISTANT_TOKEN=... npx vitest run packages/home-bridge
+```
+
+## License
+
+Apache-2.0. Built on [`home-assistant-js-websocket`](https://github.com/home-assistant/home-assistant-js-websocket)
+(Apache-2.0) and [`@leeoniya/ufuzzy`](https://github.com/leeoniya/uFuzzy) (MIT).
diff --git a/packages/home-bridge/package.json b/packages/home-bridge/package.json
index d2e78ed8e..90d382ef6 100644
--- a/packages/home-bridge/package.json
+++ b/packages/home-bridge/package.json
@@ -29,12 +29,14 @@
},
"files": [
"src",
- "README.md"
+ "README.md",
+ "LICENSE"
],
"scripts": {
"test": "vitest run --root ../.. packages/home-bridge/tests"
},
"dependencies": {
+ "@leeoniya/ufuzzy": "^1.0.19",
"home-assistant-js-websocket": "^9.6.0"
},
"peerDependencies": {
diff --git a/packages/home-bridge/src/index.js b/packages/home-bridge/src/index.js
index ab88084a6..8bd0f62bb 100644
--- a/packages/home-bridge/src/index.js
+++ b/packages/home-bridge/src/index.js
@@ -2,6 +2,6 @@ export { HomeBridge, toBridgeError } from './bridge.js';
export { ERR, HomeBridgeError } from './errors.js';
export { MACROS, matchMacro, resolveIntent } from './intents.js';
export { connectHomeMcp } from './mcp.js';
-export { buildHomeGraph, domainOf, summarizeClimate, summarizeLighting, summarizeSecurity } from './rooms.js';
-export { classifyCall, createAllowList, GUARDED_COVER_CLASSES, GUARDED_DOMAINS } from './safety.js';
+export { buildHomeGraph, domainOf, flattenEntities, summarizeClimate, summarizeLighting, summarizeSecurity } from './rooms.js';
+export { classifyCall, classifyMcpCall, createAllowList, resolveMcpTargets, GUARDED_COVER_CLASSES, GUARDED_DOMAINS } from './safety.js';
export { isPrivateHost, normalizeBaseUrl } from './url.js';
diff --git a/packages/home-bridge/src/mcp.js b/packages/home-bridge/src/mcp.js
index 6897890e9..17fec7be3 100644
--- a/packages/home-bridge/src/mcp.js
+++ b/packages/home-bridge/src/mcp.js
@@ -13,6 +13,7 @@
*/
import { ERR, HomeBridgeError } from './errors.js';
+import { classifyMcpCall } from './safety.js';
import { normalizeBaseUrl } from './url.js';
/**
@@ -23,9 +24,14 @@ import { normalizeBaseUrl } from './url.js';
* built-in Assist API lives at /api/mcp/assist; the bare /api/mcp uses the
* instance default.
* @param {string} [options.clientName] reported to Home Assistant in the handshake
- * @returns {Promise<{ client: object, tools: Array, close: () => Promise<void> }>}
+ * @param {() => Array} [options.entities] live entity list, normally
+ * `() => flattenEntities(bridge.graph)`. Supplying it turns on the physical
+ * action gate for tool calls, which is the only way an agent driving these
+ * tools is safe: see classifyMcpCall for why the tool names do not tell you.
+ * @param {(entityId: string) => boolean} [options.isAllowed] standing per-entity approvals
+ * @returns {Promise<{ client: object, tools: Array, callTool: Function, close: () => Promise<void> }>}
*/
-export async function connectHomeMcp({ baseUrl, token, api, clientName = 'three.ws' } = {}) {
+export async function connectHomeMcp({ baseUrl, token, api, clientName = 'three.ws', entities, isAllowed } = {}) {
const { http } = normalizeBaseUrl(baseUrl);
if (!token) throw new HomeBridgeError(ERR.AUTH, 'A Home Assistant long-lived access token is required.');
@@ -60,9 +66,31 @@ export async function connectHomeMcp({ baseUrl, token, api, clientName = 'three.
}
const { tools } = await client.listTools();
+
+ /**
+ * Call a home tool through the gate.
+ *
+ * @param {{ name: string, arguments?: object }} call
+ * @param {{ confirmed?: boolean }} [options] confirmed:true is the user's
+ * explicit yes. Never set it from model output.
+ */
+ const callTool = async (call, options = {}) => {
+ if (typeof entities === 'function' && !options.confirmed) {
+ const verdict = classifyMcpCall(call.name, call.arguments || {}, entities());
+ const cleared = verdict.guarded && verdict.targets.every((id) => isAllowed?.(id));
+ if (verdict.guarded && !cleared) {
+ const err = new HomeBridgeError(ERR.NEEDS_CONFIRMATION, verdict.reason);
+ err.pending = { tool: call.name, arguments: call.arguments, risk: verdict.risk, targets: verdict.targets };
+ throw err;
+ }
+ }
+ return client.callTool(call);
+ };
+
return {
client,
tools,
+ callTool,
close: () => client.close(),
};
}
diff --git a/packages/home-bridge/src/rooms.js b/packages/home-bridge/src/rooms.js
index ed9d1c520..6986d58c3 100644
--- a/packages/home-bridge/src/rooms.js
+++ b/packages/home-bridge/src/rooms.js
@@ -61,11 +61,15 @@ export function buildHomeGraph({ floors = [], areas = [], devices = [], entities
const entityId = entry.entity_id;
seen.add(entityId);
const areaId = entry.area_id || deviceArea.get(entry.device_id) || null;
- const item = describeEntity(entityId, entry, states[entityId]);
+ const item = describeEntity(entityId, entry, states[entityId], areaId);
if (!item) continue;
const room = areaId && rooms.get(areaId);
- if (room) room.entities.push(item);
- else unassigned.push(item);
+ if (room) {
+ item.areaName = room.name;
+ room.entities.push(item);
+ } else {
+ unassigned.push(item);
+ }
}
// Entities created in YAML never reach the entity registry, and the demo and
@@ -73,7 +77,7 @@ export function buildHomeGraph({ floors = [], areas = [], devices = [], entities
// half of some houses, so pick them up from the state map directly.
for (const [entityId, state] of Object.entries(states)) {
if (seen.has(entityId)) continue;
- const item = describeEntity(entityId, null, state);
+ const item = describeEntity(entityId, null, state, null);
if (item) unassigned.push(item);
}
@@ -92,13 +96,14 @@ export function buildHomeGraph({ floors = [], areas = [], devices = [], entities
};
}
-function describeEntity(entityId, registryEntry, state) {
+function describeEntity(entityId, registryEntry, state, areaId) {
const domain = domainOf(entityId);
if (!RENDERABLE_DOMAINS.has(domain)) return null;
const attributes = state?.attributes || {};
return {
entityId,
domain,
+ areaId: areaId || null,
name: registryEntry?.name || attributes.friendly_name || registryEntry?.original_name || entityId,
deviceClass: attributes.device_class || registryEntry?.device_class || registryEntry?.original_device_class || null,
state: state?.state ?? 'unavailable',
@@ -163,3 +168,11 @@ export function summarizeSecurity(entities) {
if (!locks.length && !openings.length) return null;
return { locks: locks.length, unlocked, openings: openings.length, open, secure: unlocked.length === 0 && open.length === 0 };
}
+
+/** Every renderable entity in the house as one flat list, area id included. */
+export function flattenEntities(graph) {
+ const out = [];
+ for (const room of graph?.rooms || []) out.push(...room.entities);
+ out.push(...(graph?.unassigned || []));
+ return out;
+}
diff --git a/packages/home-bridge/src/safety.js b/packages/home-bridge/src/safety.js
index f1014adad..3d590087a 100644
--- a/packages/home-bridge/src/safety.js
+++ b/packages/home-bridge/src/safety.js
@@ -84,3 +84,101 @@ export function createAllowList(entityIds = []) {
list: () => [...allowed],
};
}
+
+/**
+ * The same gate, in front of the Model Context Protocol channel.
+ *
+ * This is not belt and braces, it is load bearing. Home Assistant's own Assist
+ * tools are deliberately polymorphic, and its published description of
+ * `intent__HassTurnOff` reads: "Turns off/closes a device or entity. For locks,
+ * this performs an 'unlock' action." So a model that has been told to turn
+ * something off can unlock a front door, and nothing in the tool name says so.
+ *
+ * We resolve the tool call's targets against the live entity list, translate
+ * each one into the service it would really perform, and run the same
+ * classification the WebSocket path uses.
+ *
+ * @param {string} toolName the MCP tool name, e.g. "intent__HassTurnOff"
+ * @param {object} args the arguments the model produced
+ * @param {Array<{entityId: string, name: string, domain: string, deviceClass: string|null, areaId: string|null, attributes: object}>} entities
+ * @returns {{ guarded: boolean, risk: string|null, reason: string, targets: string[] }}
+ */
+export function classifyMcpCall(toolName, args = {}, entities = []) {
+ const intent = String(toolName || '').split('__').pop();
+ const direction = MCP_INTENT_DIRECTION[intent];
+ if (!direction) return { guarded: false, risk: null, reason: '', targets: [] };
+
+ const targets = resolveMcpTargets(args, entities);
+ const hits = [];
+ for (const entity of targets) {
+ const service = serviceForDirection(entity.domain, direction);
+ if (!service) continue;
+ const verdict = classifyCall({ domain: entity.domain, service, entityId: entity.entityId, attributes: entity.attributes });
+ if (verdict.guarded) hits.push({ entity, verdict });
+ }
+ if (!hits.length) return { guarded: false, risk: null, reason: '', targets: targets.map((e) => e.entityId) };
+
+ const names = hits.map((h) => h.entity.name).join(', ');
+ return {
+ guarded: true,
+ risk: hits[0].verdict.risk,
+ reason: `"${toolName}" would ${direction === 'off' ? 'unlock or open' : 'open'} ${names}.`,
+ targets: hits.map((h) => h.entity.entityId),
+ };
+}
+
+/** Which way each Assist intent pushes an entity. */
+const MCP_INTENT_DIRECTION = {
+ HassTurnOn: 'on',
+ HassTurnOff: 'off',
+ HassSetPosition: 'position',
+};
+
+function serviceForDirection(domain, direction) {
+ if (domain === 'lock') return direction === 'off' ? 'unlock' : 'lock';
+ if (domain === 'cover') {
+ if (direction === 'position') return 'set_cover_position';
+ return direction === 'on' ? 'open_cover' : 'close_cover';
+ }
+ if (domain === 'valve') {
+ if (direction === 'position') return 'set_valve_position';
+ return direction === 'on' ? 'open_valve' : 'close_valve';
+ }
+ if (domain === 'alarm_control_panel') return direction === 'off' ? 'alarm_disarm' : 'alarm_arm_away';
+ return null;
+}
+
+/**
+ * Assist targets are a name, or a domain, or an area, or a device class, or any
+ * combination. Reproduce that resolution so the gate sees the same entities the
+ * intent will.
+ */
+export function resolveMcpTargets(args = {}, entities = []) {
+ const name = normalizeTarget(args.name);
+ const domains = toArray(args.domain).map(normalizeTarget).filter(Boolean);
+ const deviceClasses = toArray(args.device_class).map(normalizeTarget).filter(Boolean);
+ const area = normalizeTarget(args.area);
+
+ // No target at all means "everything the intent applies to", which is the
+ // broadest and therefore the most dangerous case, not the safest.
+ const filtered = entities.filter((e) => {
+ if (name && normalizeTarget(e.name) !== name && normalizeTarget(e.entityId) !== name) return false;
+ if (domains.length && !domains.includes(e.domain)) return false;
+ if (deviceClasses.length && !deviceClasses.includes(normalizeTarget(e.deviceClass))) return false;
+ if (area && normalizeTarget(e.areaId) !== area && normalizeTarget(e.areaName) !== area) return false;
+ return true;
+ });
+ return filtered;
+}
+
+function normalizeTarget(value) {
+ return String(value ?? '')
+ .toLowerCase()
+ .replace(/[\s_-]+/g, ' ')
+ .trim();
+}
+
+function toArray(value) {
+ if (value == null) return [];
+ return Array.isArray(value) ? value : [value];
+}
diff --git a/packages/home-bridge/tests/fixtures/home.json b/packages/home-bridge/tests/fixtures/home.json
new file mode 100644
index 000000000..3c5ee58a9
--- /dev/null
+++ b/packages/home-bridge/tests/fixtures/home.json
@@ -0,0 +1,1432 @@
+{
+ "_source": "Recorded from a real Home Assistant instance (docker ghcr.io/home-assistant/home-assistant:stable) running the demo integration, with three areas, one floor, and two user scenes. Not hand-written: regenerate by pointing scripts/capture-home-fixture.mjs at any instance.",
+ "floors": [
+ {
+ "floor_id": "ground_floor",
+ "name": "Ground floor",
+ "level": 0,
+ "icon": null
+ }
+ ],
+ "areas": [
+ {
+ "area_id": "living_room",
+ "name": "Living Room",
+ "icon": "mdi:sofa",
+ "floor_id": "ground_floor",
+ "aliases": []
+ },
+ {
+ "area_id": "kitchen",
+ "name": "Kitchen",
+ "icon": "mdi:stove",
+ "floor_id": "ground_floor",
+ "aliases": []
+ },
+ {
+ "area_id": "bedroom",
+ "name": "Bedroom",
+ "icon": "mdi:bed",
+ "floor_id": "ground_floor",
+ "aliases": []
+ }
+ ],
+ "devices": [
+ {
+ "id": "e690362aad494c5b2eb79131d6e22e1a",
+ "area_id": null,
+ "name": "Sun"
+ },
+ {
+ "id": "bb8f0556ef84eed54f178dde192a9bfb",
+ "area_id": null,
+ "name": "Backup"
+ },
+ {
+ "id": "a4d24210a270ed3217aab4f26f46a2bd",
+ "area_id": null,
+ "name": "Google Translate en com"
+ },
+ {
+ "id": "2ec833737b627d775722879de4fcfba1",
+ "area_id": null,
+ "name": "Basement Floor Wet"
+ },
+ {
+ "id": "9d46f32a54020b501a53851f9f3327f1",
+ "area_id": null,
+ "name": "Movement Backyard"
+ },
+ {
+ "id": "9fc4cbfbf5305340d7fd87034dc17f9e",
+ "area_id": null,
+ "name": "Outside Temperature"
+ },
+ {
+ "id": "318164cfc0a4983822733c80240f1e7b",
+ "area_id": null,
+ "name": "Push"
+ },
+ {
+ "id": "8a84afd34a4001c67bdab5c455e79077",
+ "area_id": null,
+ "name": "HeatPump"
+ },
+ {
+ "id": "e70d2d25aba01c0b18687fa4029d4434",
+ "area_id": null,
+ "name": "Hvac"
+ },
+ {
+ "id": "49de48e2e716ee64a39aa650a4e77385",
+ "area_id": null,
+ "name": "Ecobee"
+ },
+ {
+ "id": "c1211266a8d4123303b89953992dd589",
+ "area_id": null,
+ "name": "Kitchen Window"
+ },
+ {
+ "id": "30bacd9554f761a26c17e8831a29ebd4",
+ "area_id": null,
+ "name": "Hall Window"
+ },
+ {
+ "id": "8d3d0ba2ad95dccaff8fd291a97efc93",
+ "area_id": null,
+ "name": "Living Room Window"
+ },
+ {
+ "id": "27fb91b71765f7572821547aca0cb7c4",
+ "area_id": null,
+ "name": "Garage Door"
+ },
+ {
+ "id": "74c07d6fb548627014cefdb4fd5d9da4",
+ "area_id": null,
+ "name": "Pergola Roof"
+ },
+ {
+ "id": "e9ae046b857dcfb6af0ccc9dc0cd0342",
+ "area_id": null,
+ "name": "Date"
+ },
+ {
+ "id": "71bb66585ce8dd3f4da7050235ef39d4",
+ "area_id": null,
+ "name": "Date and Time"
+ },
+ {
+ "id": "049567b121de1018a27f0f18f638c953",
+ "area_id": null,
+ "name": "Bed Light"
+ },
+ {
+ "id": "e2e0c3a8fbf451e1dafdaefe59e0bcb6",
+ "area_id": null,
+ "name": "Ceiling Lights"
+ },
+ {
+ "id": "f838ae3c5527f7db3ae6dd9af1752334",
+ "area_id": null,
+ "name": "Kitchen Lights"
+ },
+ {
+ "id": "5f65fe755b2bb7e35b7a07b176fd7dcb",
+ "area_id": null,
+ "name": "Office RGBW Lights"
+ },
+ {
+ "id": "36086faa0ff0d4232ebbe0865d113374",
+ "area_id": null,
+ "name": "Living Room RGBWW Lights"
+ },
+ {
+ "id": "03eedae0814b3e66612e163cbaf19af8",
+ "area_id": null,
+ "name": "Entrance Color + White Lights"
+ },
+ {
+ "id": "868235a056deb76c060b4f74969bbbf4",
+ "area_id": null,
+ "name": "Notifier"
+ },
+ {
+ "id": "648b537228c2ebdef8a29273ef8671ad",
+ "area_id": null,
+ "name": "volume"
+ },
+ {
+ "id": "7dfbd77ae4b39653cf6a3eb44c1e12d0",
+ "area_id": null,
+ "name": "PWM 1"
+ },
+ {
+ "id": "db648141c6a7cd60328d496dfef0a51e",
+ "area_id": null,
+ "name": "Large Range"
+ },
+ {
+ "id": "81017c919d04efc215becbf8e790dced",
+ "area_id": null,
+ "name": "Small Range"
+ },
+ {
+ "id": "58768a7b915cd12e5d55e963f9c2a46b",
+ "area_id": null,
+ "name": "Temperature setting"
+ },
+ {
+ "id": "ef7b6ea296853fd7e1ec062897034862",
+ "area_id": null,
+ "name": "Speed"
+ },
+ {
+ "id": "b347b9e9065e8b5fe9e0bb3e3858cb39",
+ "area_id": null,
+ "name": "Outside Humidity"
+ },
+ {
+ "id": "b8e134ffe704bc5371c51f4f204f0199",
+ "area_id": null,
+ "name": "Carbon monoxide"
+ },
+ {
+ "id": "6825a017272f51b325b16f0ff8193159",
+ "area_id": null,
+ "name": "Carbon dioxide"
+ },
+ {
+ "id": "d9aa19a6594978d8c41be6a586f6337d",
+ "area_id": null,
+ "name": "Power consumption"
+ },
+ {
+ "id": "46caf32beb6d11c2e3cd2faf13a05aa1",
+ "area_id": null,
+ "name": "Total energy 1"
+ },
+ {
+ "id": "cbc53fe988854bf2b07d1785a5a29613",
+ "area_id": null,
+ "name": "Total energy 2"
+ },
+ {
+ "id": "7b659143175b97f82c63815dde375f87",
+ "area_id": null,
+ "name": "Total gas 1"
+ },
+ {
+ "id": "d216e0d104c7fa1746fbc1674c6298fa",
+ "area_id": null,
+ "name": "Total gas 2"
+ },
+ {
+ "id": "41af9dc13f688a3e6e66c317c0cfd700",
+ "area_id": null,
+ "name": "Thermostat"
+ },
+ {
+ "id": "01895fc0235c71a6859bc14519d193d0",
+ "area_id": null,
+ "name": "Decorative Lights"
+ },
+ {
+ "id": "684b7e0cd0d9e4c98aa1debd4b5dd0b5",
+ "area_id": null,
+ "name": "AC"
+ },
+ {
+ "id": "1b27f822648b2983c0b696445c1b3783",
+ "area_id": null,
+ "name": "Text"
+ },
+ {
+ "id": "995f62ae7fedbc891b66f4ec851851a6",
+ "area_id": null,
+ "name": "Password"
+ },
+ {
+ "id": "64f0f4a67ec40783ee16c88f24ef8249",
+ "area_id": null,
+ "name": "Text with 1 to 5 characters"
+ },
+ {
+ "id": "7bbcfef8d30c286be7387a414ed13b11",
+ "area_id": null,
+ "name": "Text with only lower case characters"
+ },
+ {
+ "id": "4ff5ed2327318665efe52a478842be9b",
+ "area_id": null,
+ "name": "Time"
+ },
+ {
+ "id": "494993e6bbf958b00edb35d6adfce633",
+ "area_id": null,
+ "name": "Demo Update No Install"
+ },
+ {
+ "id": "d46b83a6199b02f374ca9ffd0647f655",
+ "area_id": null,
+ "name": "Demo No Update"
+ },
+ {
+ "id": "1b146b3b1c70b8c2669d2a98ad59f051",
+ "area_id": null,
+ "name": "Demo add-on"
+ },
+ {
+ "id": "ad8c1b782c5863e5beb4cdf7853f3eeb",
+ "area_id": null,
+ "name": "Demo Living Room Bulb Update"
+ },
+ {
+ "id": "3764c45ebf36b8793f129550e25ebb6f",
+ "area_id": null,
+ "name": "Demo Update with Progress"
+ },
+ {
+ "id": "2158431ce616a12e6696c006d7273666",
+ "area_id": null,
+ "name": "Demo Update with Decimal Progress"
+ },
+ {
+ "id": "9e36a75cd735fa136ed441a64ae97f5b",
+ "area_id": null,
+ "name": "Demo vacuum 0 ground floor"
+ },
+ {
+ "id": "36a7c0b269c7ab653498d2cfda10db7d",
+ "area_id": null,
+ "name": "Demo vacuum 1 first floor"
+ },
+ {
+ "id": "41596dac04dad3a9f490e199da46d15a",
+ "area_id": null,
+ "name": "Demo vacuum 2 second floor"
+ },
+ {
+ "id": "374439fd7ff062abba569427d5074c38",
+ "area_id": null,
+ "name": "Demo vacuum 3 third floor"
+ },
+ {
+ "id": "f95a26b1d0212612a2a7fe60498f8f67",
+ "area_id": null,
+ "name": "Demo vacuum 4 fourth floor"
+ },
+ {
+ "id": "c6fd9046352e4a72fa9e08cf71caae18",
+ "area_id": null,
+ "name": "Front Garden"
+ },
+ {
+ "id": "a35f6c582851598bf262acd524f80da0",
+ "area_id": null,
+ "name": "Orchard"
+ },
+ {
+ "id": "9e83706e6785a1085738df87260c1f1a",
+ "area_id": null,
+ "name": "Back Garden"
+ },
+ {
+ "id": "c014ea79bd08d59b6a72cc6c791cec9d",
+ "area_id": null,
+ "name": "Trees"
+ }
+ ],
+ "entities": [
+ {
+ "entity_id": "alarm_control_panel.security",
+ "device_id": null,
+ "area_id": null,
+ "name": null,
+ "original_name": "Security",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "binary_sensor.basement_floor_wet",
+ "device_id": "2ec833737b627d775722879de4fcfba1",
+ "area_id": "living_room",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "binary_sensor.movement_backyard",
+ "device_id": "9d46f32a54020b501a53851f9f3327f1",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "binary_sensor.outside_temperature_battery_charging",
+ "device_id": "9fc4cbfbf5305340d7fd87034dc17f9e",
+ "area_id": null,
+ "name": null,
+ "original_name": "Battery Charging",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "climate.heatpump",
+ "device_id": "8a84afd34a4001c67bdab5c455e79077",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "climate.hvac",
+ "device_id": "e70d2d25aba01c0b18687fa4029d4434",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "climate.ecobee",
+ "device_id": "49de48e2e716ee64a39aa650a4e77385",
+ "area_id": "living_room",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "cover.kitchen_window",
+ "device_id": "c1211266a8d4123303b89953992dd589",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "cover.hall_window",
+ "device_id": "30bacd9554f761a26c17e8831a29ebd4",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "cover.living_room_window",
+ "device_id": "8d3d0ba2ad95dccaff8fd291a97efc93",
+ "area_id": "living_room",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "cover.garage_door",
+ "device_id": "27fb91b71765f7572821547aca0cb7c4",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "cover.pergola_roof",
+ "device_id": "74c07d6fb548627014cefdb4fd5d9da4",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "fan.living_room_fan",
+ "device_id": null,
+ "area_id": null,
+ "name": null,
+ "original_name": "Living Room Fan",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "fan.ceiling_fan",
+ "device_id": null,
+ "area_id": "bedroom",
+ "name": null,
+ "original_name": "Ceiling Fan",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "fan.percentage_full_fan",
+ "device_id": null,
+ "area_id": null,
+ "name": null,
+ "original_name": "Percentage Full Fan",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "fan.percentage_limited_fan",
+ "device_id": null,
+ "area_id": null,
+ "name": null,
+ "original_name": "Percentage Limited Fan",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "fan.preset_only_limited_fan",
+ "device_id": null,
+ "area_id": null,
+ "name": null,
+ "original_name": "Preset Only Limited Fan",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "light.bed_light",
+ "device_id": "049567b121de1018a27f0f18f638c953",
+ "area_id": "bedroom",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "light.ceiling_lights",
+ "device_id": "e2e0c3a8fbf451e1dafdaefe59e0bcb6",
+ "area_id": "living_room",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "light.kitchen_lights",
+ "device_id": "f838ae3c5527f7db3ae6dd9af1752334",
+ "area_id": "kitchen",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "light.office_rgbw_lights",
+ "device_id": "5f65fe755b2bb7e35b7a07b176fd7dcb",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "light.living_room_rgbww_lights",
+ "device_id": "36086faa0ff0d4232ebbe0865d113374",
+ "area_id": "living_room",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "light.entrance_color_white_lights",
+ "device_id": "03eedae0814b3e66612e163cbaf19af8",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "sensor.outside_temperature",
+ "device_id": "9fc4cbfbf5305340d7fd87034dc17f9e",
+ "area_id": "kitchen",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "sensor.outside_temperature_battery",
+ "device_id": "9fc4cbfbf5305340d7fd87034dc17f9e",
+ "area_id": null,
+ "name": null,
+ "original_name": "Battery",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "switch.decorative_lights",
+ "device_id": "01895fc0235c71a6859bc14519d193d0",
+ "area_id": "kitchen",
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "switch.ac",
+ "device_id": "684b7e0cd0d9e4c98aa1debd4b5dd0b5",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "valve.front_garden",
+ "device_id": "c6fd9046352e4a72fa9e08cf71caae18",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "valve.orchard",
+ "device_id": "a35f6c582851598bf262acd524f80da0",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "valve.back_garden",
+ "device_id": "9e83706e6785a1085738df87260c1f1a",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "valve.trees",
+ "device_id": "c014ea79bd08d59b6a72cc6c791cec9d",
+ "area_id": null,
+ "name": null,
+ "original_name": null,
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "scene.bedtime",
+ "device_id": null,
+ "area_id": null,
+ "name": null,
+ "original_name": "Bedtime",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ },
+ {
+ "entity_id": "scene.away_mode",
+ "device_id": null,
+ "area_id": null,
+ "name": null,
+ "original_name": "Away Mode",
+ "original_device_class": null,
+ "disabled_by": null,
+ "hidden_by": null
+ }
+ ],
+ "states": {
+ "alarm_control_panel.security": {
+ "entity_id": "alarm_control_panel.security",
+ "state": "disarmed",
+ "attributes": {
+ "code_format": "number",
+ "changed_by": null,
+ "code_arm_required": true,
+ "previous_state": null,
+ "next_state": null,
+ "friendly_name": "Security",
+ "supported_features": 63
+ }
+ },
+ "binary_sensor.basement_floor_wet": {
+ "entity_id": "binary_sensor.basement_floor_wet",
+ "state": "off",
+ "attributes": {
+ "device_class": "moisture",
+ "friendly_name": "Basement Floor Wet"
+ }
+ },
+ "binary_sensor.movement_backyard": {
+ "entity_id": "binary_sensor.movement_backyard",
+ "state": "on",
+ "attributes": {
+ "device_class": "motion",
+ "friendly_name": "Movement Backyard"
+ }
+ },
+ "binary_sensor.outside_temperature_battery_charging": {
+ "entity_id": "binary_sensor.outside_temperature_battery_charging",
+ "state": "off",
+ "attributes": {
+ "device_class": "battery_charging",
+ "friendly_name": "Outside Temperature Battery Charging"
+ }
+ },
+ "climate.heatpump": {
+ "entity_id": "climate.heatpump",
+ "state": "heat",
+ "attributes": {
+ "hvac_modes": [
+ "heat",
+ "off"
+ ],
+ "min_temp": 7,
+ "max_temp": 35,
+ "current_temperature": 25,
+ "temperature": 20,
+ "hvac_action": "heating",
+ "friendly_name": "HeatPump",
+ "supported_features": 385
+ }
+ },
+ "climate.hvac": {
+ "entity_id": "climate.hvac",
+ "state": "cool",
+ "attributes": {
+ "hvac_modes": [
+ "off",
+ "heat",
+ "cool",
+ "auto",
+ "dry",
+ "fan_only"
+ ],
+ "min_temp": 7,
+ "max_temp": 35,
+ "min_humidity": 30,
+ "max_humidity": 99,
+ "target_humidity_step": 5,
+ "fan_modes": [
+ "on_low",
+ "on_high",
+ "auto_low",
+ "auto_high",
+ "off"
+ ],
+ "swing_modes": [
+ "auto",
+ "1",
+ "2",
+ "3",
+ "off"
+ ],
+ "swing_horizontal_modes": [
+ "auto",
+ "rangefull",
+ "off"
+ ],
+ "current_temperature": 22,
+ "temperature": 21,
+ "target_temp_high": null,
+ "target_temp_low": null,
+ "current_humidity": 54.2,
+ "humidity": 67.4,
+ "fan_mode": "on_high",
+ "hvac_action": "cooling",
+ "swing_mode": "off",
+ "swing_horizontal_mode": "auto",
+ "friendly_name": "Hvac",
+ "supported_features": 943
+ }
+ },
+ "climate.ecobee": {
+ "entity_id": "climate.ecobee",
+ "state": "heat_cool",
+ "attributes": {
+ "hvac_modes": [
+ "off",
+ "cool",
+ "heat_cool",
+ "auto",
+ "dry",
+ "fan_only"
+ ],
+ "min_temp": 7,
+ "max_temp": 35,
+ "fan_modes": [
+ "on_low",
+ "on_high",
+ "auto_low",
+ "auto_high",
+ "off"
+ ],
+ "preset_modes": [
+ "home",
+ "eco",
+ "away"
+ ],
+ "swing_modes": [
+ "auto",
+ "1",
+ "2",
+ "3",
+ "off"
+ ],
+ "current_temperature": 23,
+ "target_temp_high": 24,
+ "target_temp_low": 21,
+ "fan_mode": "auto_low",
+ "preset_mode": "home",
+ "swing_mode": "auto",
+ "friendly_name": "Ecobee",
+ "supported_features": 442
+ }
+ },
+ "cover.kitchen_window": {
+ "entity_id": "cover.kitchen_window",
+ "state": "closed",
+ "attributes": {
+ "is_closed": true,
+ "friendly_name": "Kitchen Window",
+ "supported_features": 11
+ }
+ },
+ "cover.hall_window": {
+ "entity_id": "cover.hall_window",
+ "state": "open",
+ "attributes": {
+ "is_closed": false,
+ "current_position": 10,
+ "friendly_name": "Hall Window",
+ "supported_features": 15
+ }
+ },
+ "cover.living_room_window": {
+ "entity_id": "cover.living_room_window",
+ "state": "open",
+ "attributes": {
+ "supported_speeds": [
+ "slow",
+ "default"
+ ],
+ "is_closed": false,
+ "current_position": 70,
+ "current_tilt_position": 50,
+ "friendly_name": "Living Room Window",
+ "supported_features": 511
+ }
+ },
+ "cover.garage_door": {
+ "entity_id": "cover.garage_door",
+ "state": "closed",
+ "attributes": {
+ "is_closed": true,
+ "device_class": "garage",
+ "friendly_name": "Garage Door",
+ "supported_features": 3
+ }
+ },
+ "cover.pergola_roof": {
+ "entity_id": "cover.pergola_roof",
+ "state": "closed",
+ "attributes": {
+ "is_closed": true,
+ "current_tilt_position": 60,
+ "friendly_name": "Pergola Roof",
+ "supported_features": 240
+ }
+ },
+ "fan.living_room_fan": {
+ "entity_id": "fan.living_room_fan",
+ "state": "off",
+ "attributes": {
+ "preset_modes": [
+ "auto",
+ "smart",
+ "sleep",
+ "on"
+ ],
+ "direction": "forward",
+ "oscillating": false,
+ "percentage": null,
+ "percentage_step": 33.333333333333336,
+ "preset_mode": null,
+ "friendly_name": "Living Room Fan",
+ "supported_features": 55
+ }
+ },
+ "fan.ceiling_fan": {
+ "entity_id": "fan.ceiling_fan",
+ "state": "off",
+ "attributes": {
+ "preset_modes": null,
+ "percentage": null,
+ "percentage_step": 33.333333333333336,
+ "preset_mode": null,
+ "friendly_name": "Ceiling Fan",
+ "supported_features": 49
+ }
+ },
+ "fan.percentage_full_fan": {
+ "entity_id": "fan.percentage_full_fan",
+ "state": "off",
+ "attributes": {
+ "preset_modes": [
+ "auto",
+ "smart",
+ "sleep",
+ "on"
+ ],
+ "direction": "forward",
+ "oscillating": false,
+ "percentage": null,
+ "percentage_step": 33.333333333333336,
+ "preset_mode": null,
+ "friendly_name": "Percentage Full Fan",
+ "supported_features": 55
+ }
+ },
+ "fan.percentage_limited_fan": {
+ "entity_id": "fan.percentage_limited_fan",
+ "state": "off",
+ "attributes": {
+ "preset_modes": [
+ "auto",
+ "smart",
+ "sleep",
+ "on"
+ ],
+ "percentage": null,
+ "percentage_step": 33.333333333333336,
+ "preset_mode": null,
+ "friendly_name": "Percentage Limited Fan",
+ "supported_features": 49
+ }
+ },
+ "fan.preset_only_limited_fan": {
+ "entity_id": "fan.preset_only_limited_fan",
+ "state": "off",
+ "attributes": {
+ "preset_modes": [
+ "auto",
+ "smart",
+ "sleep",
+ "on"
+ ],
+ "preset_mode": null,
+ "friendly_name": "Preset Only Limited Fan",
+ "supported_features": 56
+ }
+ },
+ "light.bed_light": {
+ "entity_id": "light.bed_light",
+ "state": "on",
+ "attributes": {
+ "min_color_temp_kelvin": 2000,
+ "max_color_temp_kelvin": 6535,
+ "effect_list": [
+ "rainbow",
+ "off"
+ ],
+ "supported_color_modes": [
+ "color_temp",
+ "hs"
+ ],
+ "effect": "rainbow",
+ "color_mode": "color_temp",
+ "brightness": 40,
+ "color_temp_kelvin": 2631,
+ "hs_color": [
+ 28.55,
+ 67.974
+ ],
+ "rgb_color": [
+ 255,
+ 164,
+ 82
+ ],
+ "xy_color": [
+ 0.532,
+ 0.388
+ ],
+ "friendly_name": "Bed Light",
+ "supported_features": 4
+ }
+ },
+ "light.ceiling_lights": {
+ "entity_id": "light.ceiling_lights",
+ "state": "off",
+ "attributes": {
+ "min_color_temp_kelvin": 2000,
+ "max_color_temp_kelvin": 6535,
+ "supported_color_modes": [
+ "color_temp",
+ "hs"
+ ],
+ "color_mode": null,
+ "brightness": null,
+ "color_temp_kelvin": null,
+ "hs_color": null,
+ "rgb_color": null,
+ "xy_color": null,
+ "friendly_name": "Ceiling Lights",
+ "supported_features": 0
+ }
+ },
+ "light.kitchen_lights": {
+ "entity_id": "light.kitchen_lights",
+ "state": "off",
+ "attributes": {
+ "min_color_temp_kelvin": 2000,
+ "max_color_temp_kelvin": 6535,
+ "supported_color_modes": [
+ "color_temp",
+ "hs"
+ ],
+ "color_mode": null,
+ "brightness": null,
+ "color_temp_kelvin": null,
+ "hs_color": null,
+ "rgb_color": null,
+ "xy_color": null,
+ "friendly_name": "Kitchen Lights",
+ "supported_features": 0
+ }
+ },
+ "light.office_rgbw_lights": {
+ "entity_id": "light.office_rgbw_lights",
+ "state": "on",
+ "attributes": {
+ "supported_color_modes": [
+ "rgbw"
+ ],
+ "color_mode": "rgbw",
+ "brightness": 180,
+ "hs_color": [
+ 0,
+ 49.804
+ ],
+ "rgb_color": [
+ 255,
+ 128,
+ 128
+ ],
+ "xy_color": [
+ 0.524,
+ 0.313
+ ],
+ "rgbw_color": [
+ 255,
+ 0,
+ 0,
+ 255
+ ],
+ "friendly_name": "Office RGBW Lights",
+ "supported_features": 0
+ }
+ },
+ "light.living_room_rgbww_lights": {
+ "entity_id": "light.living_room_rgbww_lights",
+ "state": "on",
+ "attributes": {
+ "supported_color_modes": [
+ "rgbww"
+ ],
+ "color_mode": "rgbww",
+ "brightness": 180,
+ "hs_color": [
+ 0.923,
+ 50.98
+ ],
+ "rgb_color": [
+ 255,
+ 127,
+ 125
+ ],
+ "xy_color": [
+ 0.528,
+ 0.315
+ ],
+ "rgbww_color": [
+ 255,
+ 0,
+ 0,
+ 255,
+ 0
+ ],
+ "friendly_name": "Living Room RGBWW Lights",
+ "supported_features": 0
+ }
+ },
+ "light.entrance_color_white_lights": {
+ "entity_id": "light.entrance_color_white_lights",
+ "state": "on",
+ "attributes": {
+ "supported_color_modes": [
+ "hs",
+ "white"
+ ],
+ "color_mode": "hs",
+ "brightness": 180,
+ "hs_color": [
+ 345,
+ 75
+ ],
+ "rgb_color": [
+ 255,
+ 64,
+ 112
+ ],
+ "xy_color": [
+ 0.588,
+ 0.274
+ ],
+ "friendly_name": "Entrance Color + White Lights",
+ "supported_features": 0
+ }
+ },
+ "lock.front_door": {
+ "entity_id": "lock.front_door",
+ "state": "locked",
+ "attributes": {
+ "friendly_name": "Front Door",
+ "supported_features": 0
+ }
+ },
+ "lock.kitchen_door": {
+ "entity_id": "lock.kitchen_door",
+ "state": "unlocked",
+ "attributes": {
+ "friendly_name": "Kitchen Door",
+ "supported_features": 0
+ }
+ },
+ "lock.poorly_installed_door": {
+ "entity_id": "lock.poorly_installed_door",
+ "state": "unlocked",
+ "attributes": {
+ "friendly_name": "Poorly Installed Door",
+ "supported_features": 0
+ }
+ },
+ "lock.openable_lock": {
+ "entity_id": "lock.openable_lock",
+ "state": "locked",
+ "attributes": {
+ "friendly_name": "Openable Lock",
+ "supported_features": 1
+ }
+ },
+ "media_player.living_room": {
+ "entity_id": "media_player.living_room",
+ "state": "playing",
+ "attributes": {
+ "sound_mode_list": [
+ "Music",
+ "Movie"
+ ],
+ "volume_level": 1,
+ "is_volume_muted": false,
+ "media_content_id": "eyU3bRy2x44",
+ "media_content_type": "movie",
+ "media_duration": 300,
+ "media_position": 45,
+ "media_position_updated_at": "2026-09-02T21:10:14.990453+00:00",
+ "media_title": "♥♥ The Best Fireplace Video (3 hours)",
+ "app_name": "YouTube",
+ "sound_mode": "Music",
+ "shuffle": false,
+ "entity_picture": "/api/media_player_proxy/media_player.living_room?token=68050ee39d0e1e1168de2036e077583fc303f6893823c3c7c9e80a0f8ba9ecca&cache=bc2ffb49c4f67034",
+ "friendly_name": "Living Room",
+ "supported_features": 119695
+ }
+ },
+ "media_player.bedroom": {
+ "entity_id": "media_player.bedroom",
+ "state": "playing",
+ "attributes": {
+ "sound_mode_list": [
+ "Music",
+ "Movie"
+ ],
+ "volume_level": 1,
+ "is_volume_muted": false,
+ "media_content_id": "kxopViU98Xo",
+ "media_content_type": "movie",
+ "media_duration": 360000,
+ "media_position": 54000,
+ "media_position_updated_at": "2026-09-02T21:10:14.990469+00:00",
+ "media_title": "Epic sax guy 10 hours",
+ "app_name": "YouTube",
+ "sound_mode": "Music",
+ "shuffle": false,
+ "entity_picture": "/api/media_player_proxy/media_player.bedroom?token=4706a0a13a59bd98e8781ebf36de566cfbe18415ac7afc04624e4a1c1cbd6014&cache=e4513ed94ec89151",
+ "friendly_name": "Bedroom",
+ "supported_features": 119695
+ }
+ },
+ "media_player.walkman": {
+ "entity_id": "media_player.walkman",
+ "state": "playing",
+ "attributes": {
+ "sound_mode_list": [
+ "Music",
+ "Movie"
+ ],
+ "group_members": [],
+ "volume_level": 1,
+ "is_volume_muted": false,
+ "media_content_id": "bounzz-1",
+ "media_content_type": "music",
+ "media_duration": 213,
+ "media_title": "I Wanna Be A Hippy (Flamman & Abraxas Radio Mix)",
+ "media_artist": "Technohead",
+ "media_album_name": "Bounzz",
+ "media_track": 1,
+ "sound_mode": "Music",
+ "shuffle": false,
+ "repeat": "off",
+ "entity_picture": "/api/media_player_proxy/media_player.walkman?token=770fa76c148c7aaaaf237144584a1227747d97cf3e5a4ed80fe3c269d1408c9a&cache=62c0c516acbc53a9",
+ "friendly_name": "Walkman",
+ "supported_features": 914877
+ }
+ },
+ "media_player.kitchen": {
+ "entity_id": "media_player.kitchen",
+ "state": "playing",
+ "attributes": {
+ "sound_mode_list": [
+ "Music",
+ "Movie"
+ ],
+ "group_members": [],
+ "volume_level": 1,
+ "is_volume_muted": false,
+ "media_content_id": "bounzz-1",
+ "media_content_type": "music",
+ "media_duration": 213,
+ "media_title": "I Wanna Be A Hippy (Flamman & Abraxas Radio Mix)",
+ "media_artist": "Technohead",
+ "media_album_name": "Bounzz",
+ "media_track": 1,
+ "sound_mode": "Music",
+ "shuffle": false,
+ "repeat": "off",
+ "entity_picture": "/api/media_player_proxy/media_player.kitchen?token=100a887c23350357c9b7a2a995a1e6385020d29717538e8511a3749117530f13&cache=62c0c516acbc53a9",
+ "friendly_name": "Kitchen",
+ "supported_features": 914877
+ }
+ },
+ "media_player.lounge_room": {
+ "entity_id": "media_player.lounge_room",
+ "state": "playing",
+ "attributes": {
+ "source_list": [
+ "dvd",
+ "youtube"
+ ],
+ "sound_mode_list": [
+ "Music",
+ "Movie"
+ ],
+ "volume_level": 1,
+ "is_volume_muted": false,
+ "media_content_id": "house-of-cards-1",
+ "media_content_type": "tvshow",
+ "media_duration": 3600,
+ "media_title": "Chapter 1",
+ "media_series_title": "House of Cards",
+ "media_season": "1",
+ "media_episode": "1",
+ "app_name": "Netflix",
+ "source": "dvd",
+ "sound_mode": "Music",
+ "shuffle": false,
+ "device_class": "tv",
+ "entity_picture": "/api/media_player_proxy/media_player.lounge_room?token=951ba5642d74007119ada2c8a4cf7a28e20bdfa5e6189621595ddb0ab123709c&cache=cb9d84451faf9351",
+ "friendly_name": "Lounge room",
+ "supported_features": 121265
+ }
+ },
+ "media_player.browse": {
+ "entity_id": "media_player.browse",
+ "state": "playing",
+ "attributes": {
+ "volume_level": 1,
+ "is_volume_muted": false,
+ "sound_mode": "Music",
+ "shuffle": false,
+ "friendly_name": "Browse",
+ "supported_features": 4325376
+ }
+ },
+ "media_player.group": {
+ "entity_id": "media_player.group",
+ "state": "playing",
+ "attributes": {
+ "sound_mode_list": [
+ "Music",
+ "Movie"
+ ],
+ "group_members": null,
+ "volume_level": 1,
+ "is_volume_muted": false,
+ "sound_mode": "Music",
+ "shuffle": false,
+ "friendly_name": "Group",
+ "supported_features": 643983
+ }
+ },
+ "media_player.search": {
+ "entity_id": "media_player.search",
+ "state": "playing",
+ "attributes": {
+ "volume_level": 1,
+ "is_volume_muted": false,
+ "sound_mode": "Music",
+ "shuffle": false,
+ "friendly_name": "Search",
+ "supported_features": 4194304
+ }
+ },
+ "sensor.outside_temperature": {
+ "entity_id": "sensor.outside_temperature",
+ "state": "15.6",
+ "attributes": {
+ "state_class": "measurement",
+ "unit_of_measurement": "°C",
+ "device_class": "temperature",
+ "friendly_name": "Outside Temperature"
+ }
+ },
+ "sensor.outside_temperature_battery": {
+ "entity_id": "sensor.outside_temperature_battery",
+ "state": "12",
+ "attributes": {
+ "state_class": "measurement",
+ "unit_of_measurement": "%",
+ "device_class": "battery",
+ "friendly_name": "Outside Temperature Battery"
+ }
+ },
+ "switch.decorative_lights": {
+ "entity_id": "switch.decorative_lights",
+ "state": "on",
+ "attributes": {
+ "assumed_state": true,
+ "friendly_name": "Decorative Lights"
+ }
+ },
+ "switch.ac": {
+ "entity_id": "switch.ac",
+ "state": "off",
+ "attributes": {
+ "device_class": "outlet",
+ "friendly_name": "AC"
+ }
+ },
+ "valve.front_garden": {
+ "entity_id": "valve.front_garden",
+ "state": "open",
+ "attributes": {
+ "is_closed": false,
+ "friendly_name": "Front Garden",
+ "supported_features": 3
+ }
+ },
+ "valve.orchard": {
+ "entity_id": "valve.orchard",
+ "state": "closed",
+ "attributes": {
+ "is_closed": true,
+ "friendly_name": "Orchard",
+ "supported_features": 3
+ }
+ },
+ "valve.back_garden": {
+ "entity_id": "valve.back_garden",
+ "state": "open",
+ "attributes": {
+ "is_closed": false,
+ "current_position": 70,
+ "friendly_name": "Back Garden",
+ "supported_features": 15
+ }
+ },
+ "valve.trees": {
+ "entity_id": "valve.trees",
+ "state": "open",
+ "attributes": {
+ "is_closed": false,
+ "current_position": 30,
+ "friendly_name": "Trees",
+ "supported_features": 15
+ }
+ },
+ "scene.bedtime": {
+ "entity_id": "scene.bedtime",
+ "state": "2026-09-02T21:17:15.287139+00:00",
+ "attributes": {
+ "entity_id": [
+ "light.bed_light",
+ "light.ceiling_lights",
+ "light.kitchen_lights",
+ "lock.front_door"
+ ],
+ "id": "threews_bedtime",
+ "friendly_name": "Bedtime"
+ }
+ },
+ "scene.away_mode": {
+ "entity_id": "scene.away_mode",
+ "state": "unknown",
+ "attributes": {
+ "entity_id": [
+ "light.bed_light",
+ "light.ceiling_lights",
+ "light.kitchen_lights",
+ "lock.front_door",
+ "climate.ecobee"
+ ],
+ "id": "threews_away",
+ "friendly_name": "Away Mode"
+ }
+ }
+ }
+}
diff --git a/packages/home-bridge/tests/home-bridge.test.js b/packages/home-bridge/tests/home-bridge.test.js
new file mode 100644
index 000000000..4f76ba186
--- /dev/null
+++ b/packages/home-bridge/tests/home-bridge.test.js
@@ -0,0 +1,233 @@
+// The room graph, the intent resolver, and the physical-action gate all run
+// against fixtures/home.json, which is a recording of a real Home Assistant
+// instance (see scripts/capture-home-fixture.mjs), not hand-written shapes. A
+// registry change upstream shows up here rather than in someone's house.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+ buildHomeGraph,
+ classifyCall,
+ classifyMcpCall,
+ createAllowList,
+ ERR,
+ flattenEntities,
+ HomeBridge,
+ isPrivateHost,
+ matchMacro,
+ normalizeBaseUrl,
+ resolveIntent,
+ resolveMcpTargets,
+ summarizeLighting,
+} from '../src/index.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const home = JSON.parse(readFileSync(path.join(HERE, 'fixtures/home.json'), 'utf8'));
+const graph = buildHomeGraph(home);
+const entities = flattenEntities(graph);
+const macros = Object.values(home.states)
+ .filter((s) => s.entity_id.startsWith('scene.') || s.entity_id.startsWith('script.'))
+ .map((s) => ({ entityId: s.entity_id, name: s.attributes.friendly_name || s.entity_id }));
+
+describe('normalizeBaseUrl', () => {
+ it('accepts what a person actually types', () => {
+ expect(normalizeBaseUrl('home.example.com').http).toBe('https://home.example.com');
+ expect(normalizeBaseUrl(' https://home.example.com/ ').http).toBe('https://home.example.com');
+ expect(normalizeBaseUrl('http://192.168.1.10:8123').http).toBe('http://192.168.1.10:8123');
+ });
+
+ it('derives the websocket URL, preserving a reverse-proxy path prefix', () => {
+ expect(normalizeBaseUrl('https://example.com/ha/').ws).toBe('wss://example.com/ha/api/websocket');
+ expect(normalizeBaseUrl('http://localhost:8123').ws).toBe('ws://localhost:8123/api/websocket');
+ });
+
+ it('rejects input that cannot work', () => {
+ expect(() => normalizeBaseUrl('')).toThrow(/required/i);
+ expect(() => normalizeBaseUrl('ftp://home')).toThrow(/scheme/i);
+ });
+
+ it('explains the mixed-content wall before the browser hits it', () => {
+ expect(() => normalizeBaseUrl('http://192.168.1.10:8123', { requireSecure: true })).toThrow(/plain http/i);
+ // Loopback is exempt: a browser treats it as a secure context.
+ expect(normalizeBaseUrl('http://localhost:8123', { requireSecure: true }).loopback).toBe(true);
+ });
+
+ it('knows which hosts a cloud server can never route to', () => {
+ for (const h of ['homeassistant.local', '192.168.1.10', '10.0.0.4', '172.16.9.1', '127.0.0.1', 'nas.lan']) {
+ expect(isPrivateHost(h), h).toBe(true);
+ }
+ for (const h of ['home.example.com', 'abc123.ui.nabu.casa', '8.8.8.8']) {
+ expect(isPrivateHost(h), h).toBe(false);
+ }
+ });
+});
+
+describe('room graph', () => {
+ it('groups the real instance into its real rooms', () => {
+ expect(graph.rooms.map((r) => r.name)).toEqual(['Bedroom', 'Kitchen', 'Living Room']);
+ expect(graph.floors).toEqual([{ id: 'ground_floor', name: 'Ground floor', level: 0, icon: null }]);
+ for (const room of graph.rooms) expect(room.floorId).toBe('ground_floor');
+ });
+
+ it('keeps YAML entities that never reach the entity registry', () => {
+ // The demo integration creates most of its entities outside the registry.
+ // Dropping them would silently hide half of some houses.
+ const registered = new Set(home.entities.map((e) => e.entity_id));
+ const unregistered = graph.unassigned.filter((e) => !registered.has(e.entityId));
+ expect(unregistered.length).toBeGreaterThan(0);
+ });
+
+ it('summarizes lighting the way the 3D scene needs it', () => {
+ expect(summarizeLighting([])).toEqual({ total: 0, on: 0, brightness: 0, rgb: null });
+ const dim = summarizeLighting([
+ { domain: 'light', state: 'on', attributes: { brightness: 51, rgb_color: [255, 0, 0] } },
+ { domain: 'light', state: 'off', attributes: {} },
+ ]);
+ expect(dim).toEqual({ total: 2, on: 1, brightness: 0.2, rgb: [255, 0, 0] });
+ });
+
+ it('treats a light with no brightness attribute as full', () => {
+ expect(summarizeLighting([{ domain: 'light', state: 'on', attributes: {} }]).brightness).toBe(1);
+ });
+
+ it('answers "is this room buttoned up"', () => {
+ const living = graph.rooms.find((r) => r.name === 'Living Room');
+ expect(living.secured).not.toBeNull();
+ expect(living.secured.secure).toBe(living.secured.unlocked.length === 0 && living.secured.open.length === 0);
+ // A room with nothing to secure reports null rather than a false "secure".
+ expect(graph.rooms.find((r) => r.name === 'Kitchen').secured).toBeNull();
+ });
+
+ it('survives an empty house without throwing', () => {
+ expect(buildHomeGraph()).toEqual({ floors: [], rooms: [], unassigned: [] });
+ });
+});
+
+describe('intent resolution', () => {
+ it('maps spoken phrases onto the canonical macros', () => {
+ expect(matchMacro('good night').key).toBe('good_night');
+ expect(matchMacro('Goodnight!').key).toBe('good_night');
+ expect(matchMacro("I'm leaving").key).toBe('leaving');
+ expect(matchMacro('heading out').key).toBe('leaving');
+ expect(matchMacro('welcome home').key).toBe('arriving');
+ expect(matchMacro('what is the weather')).toBeNull();
+ });
+
+ it('finds this house\'s own scene for a macro it never named that way', () => {
+ // The house has "Bedtime", not "Good night". Matching the phrase against
+ // scene names alone would miss it, which is the entire point of the table.
+ const hit = resolveIntent('good night', macros);
+ expect(hit.entityId).toBe('scene.bedtime');
+ expect(hit.macro).toBe('good_night');
+ expect(hit.confidence).toBeGreaterThan(0.9);
+ });
+
+ it('routes leaving to Away Mode', () => {
+ for (const phrase of ["I'm leaving", 'bye', 'heading out', 'away mode']) {
+ expect(resolveIntent(phrase, macros).entityId, phrase).toBe('scene.away_mode');
+ }
+ });
+
+ it('returns nothing rather than firing the wrong scene', () => {
+ // This house has no movie scene. Guessing "Bedtime" would be worse than
+ // admitting the miss and letting the agent compose the calls itself.
+ expect(resolveIntent('movie time', macros)).toBeNull();
+ expect(resolveIntent('good night', [])).toBeNull();
+ });
+
+ it('ignores candidates that are not scenes or scripts', () => {
+ expect(resolveIntent('bedtime', [{ entityId: 'light.bedtime', name: 'Bedtime' }])).toBeNull();
+ });
+});
+
+describe('the physical-action gate', () => {
+ it('lets ordinary things through', () => {
+ expect(classifyCall({ domain: 'light', service: 'turn_on', entityId: 'light.kitchen_lights' }).guarded).toBe(false);
+ expect(classifyCall({ domain: 'climate', service: 'set_temperature' }).guarded).toBe(false);
+ expect(classifyCall({ domain: 'media_player', service: 'turn_off' }).guarded).toBe(false);
+ });
+
+ it('is asymmetric: securing the house never prompts, opening it always does', () => {
+ expect(classifyCall({ domain: 'lock', service: 'lock', entityId: 'lock.front_door' }).guarded).toBe(false);
+ expect(classifyCall({ domain: 'lock', service: 'unlock', entityId: 'lock.front_door' }).guarded).toBe(true);
+ expect(classifyCall({ domain: 'alarm_control_panel', service: 'alarm_arm_away' }).guarded).toBe(false);
+ expect(classifyCall({ domain: 'alarm_control_panel', service: 'alarm_disarm' }).guarded).toBe(true);
+ });
+
+ it('guards a garage door but not a curtain', () => {
+ const garage = { domain: 'cover', service: 'open_cover', entityId: 'cover.garage_door', attributes: { device_class: 'garage' } };
+ const curtain = { domain: 'cover', service: 'open_cover', entityId: 'cover.living_room_window', attributes: { device_class: 'curtain' } };
+ expect(classifyCall(garage).guarded).toBe(true);
+ expect(classifyCall(garage).risk).toBe('physical');
+ expect(classifyCall(curtain).guarded).toBe(false);
+ });
+
+ it('treats toggle as unsafe, because half of a toggle is an unlock', () => {
+ expect(classifyCall({ domain: 'lock', service: 'toggle', entityId: 'lock.front_door' }).guarded).toBe(true);
+ });
+
+ it('scopes a standing allowance to one entity, never a domain', () => {
+ const allow = createAllowList(['lock.office_door']);
+ expect(allow.has('lock.office_door')).toBe(true);
+ expect(allow.has('lock.front_door')).toBe(false);
+ });
+});
+
+describe('the gate in front of Home Assistant\'s own MCP tools', () => {
+ // Home Assistant documents intent__HassTurnOff as: "Turns off/closes a device
+ // or entity. For locks, this performs an 'unlock' action." A model told to
+ // turn something off can therefore unlock a front door, and the tool name
+ // says nothing about it. Verified against a live instance: with the lock
+ // exposed to Assist, that call really does unlock the door.
+ it('catches the polymorphic unlock hiding inside HassTurnOff', () => {
+ const verdict = classifyMcpCall('intent__HassTurnOff', { name: 'Front Door' }, entities);
+ expect(verdict.guarded).toBe(true);
+ expect(verdict.risk).toBe('security');
+ expect(verdict.targets).toContain('lock.front_door');
+ });
+
+ it('does not prompt for the same tool on a light', () => {
+ expect(classifyMcpCall('intent__HassTurnOff', { name: 'Ceiling Lights' }, entities).guarded).toBe(false);
+ });
+
+ it('catches an untargeted blast across a whole domain', () => {
+ const verdict = classifyMcpCall('intent__HassTurnOff', { domain: 'lock' }, entities);
+ expect(verdict.guarded).toBe(true);
+ expect(verdict.targets.length).toBeGreaterThan(1);
+ });
+
+ it('treats HassTurnOn on a lock as the safe direction', () => {
+ expect(classifyMcpCall('intent__HassTurnOn', { name: 'Front Door' }, entities).guarded).toBe(false);
+ });
+
+ it('leaves tools it does not understand alone', () => {
+ expect(classifyMcpCall('todo__HassListAddItem', { name: 'Front Door' }, entities).guarded).toBe(false);
+ });
+
+ it('resolves targets the way Assist does', () => {
+ const byArea = resolveMcpTargets({ area: 'Kitchen' }, entities);
+ expect(byArea.length).toBeGreaterThan(0);
+ expect(byArea.every((e) => e.areaName === 'Kitchen')).toBe(true);
+ const byDomain = resolveMcpTargets({ domain: ['light'] }, entities);
+ expect(byDomain.every((e) => e.domain === 'light')).toBe(true);
+ });
+});
+
+describe('HomeBridge construction', () => {
+ it('refuses to build without a token', () => {
+ expect(() => new HomeBridge({ baseUrl: 'https://home.example.com' })).toThrow(/token/i);
+ });
+
+ it('refuses a URL it cannot use', () => {
+ expect(() => new HomeBridge({ baseUrl: 'not a url at all', token: 'x' })).toThrow();
+ });
+
+ it('will not act before connect()', async () => {
+ const bridge = new HomeBridge({ baseUrl: 'https://home.example.com', token: 'x' });
+ await expect(bridge.call('light', 'turn_on', {})).rejects.toMatchObject({ code: ERR.NOT_CONNECTED });
+ });
+});
diff --git a/packages/home-bridge/tests/live-home.test.js b/packages/home-bridge/tests/live-home.test.js
new file mode 100644
index 000000000..aa68e8f86
--- /dev/null
+++ b/packages/home-bridge/tests/live-home.test.js
@@ -0,0 +1,103 @@
+// The live suite. Everything in home-bridge.test.js is a pure function over a
+// recording; this file drives a real Home Assistant and changes real state.
+//
+// It skips itself unless you point it at an instance, so the default `npm test`
+// never needs one:
+//
+// docker run -d --name ha -p 8123:8123 ghcr.io/home-assistant/home-assistant:stable
+// # add `demo:` to its configuration.yaml, restart, create a long-lived token
+// HOME_ASSISTANT_URL=http://localhost:8123 HOME_ASSISTANT_TOKEN=... npx vitest run packages/home-bridge
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { connectHomeMcp, ERR, flattenEntities, HomeBridge } from '../src/index.js';
+
+const baseUrl = process.env.HOME_ASSISTANT_URL;
+const token = process.env.HOME_ASSISTANT_TOKEN;
+const live = describe.skipIf(!baseUrl || !token);
+
+const settle = (ms = 600) => new Promise((resolve) => setTimeout(resolve, ms));
+
+live('against a real Home Assistant', () => {
+ /** @type {HomeBridge} */
+ let home;
+
+ beforeAll(async () => {
+ home = new HomeBridge({ baseUrl, token });
+ await home.connect();
+ }, 30_000);
+
+ afterAll(() => home?.close());
+
+ it('connects and builds a room graph from the live registries', () => {
+ expect(home.connected).toBe(true);
+ expect(home.graph.rooms.length + home.graph.unassigned.length).toBeGreaterThan(0);
+ });
+
+ it('changes real state and sees it come back on the socket', async () => {
+ const light = Object.keys(home.states).find((id) => id.startsWith('light.'));
+ const before = home.states[light].state;
+ await home.call('light', 'toggle', { entity_id: light });
+ await settle();
+ expect(home.states[light].state).not.toBe(before);
+ });
+
+ it('refuses to unlock a door without an explicit yes, then does it when asked', async () => {
+ const lock = Object.keys(home.states).find((id) => id.startsWith('lock.') && home.states[id].state === 'locked');
+ if (!lock) return;
+
+ await expect(home.call('lock', 'unlock', { entity_id: lock })).rejects.toMatchObject({
+ code: ERR.NEEDS_CONFIRMATION,
+ });
+ expect(home.states[lock].state).toBe('locked');
+
+ await home.call('lock', 'unlock', { entity_id: lock }, { confirmed: true });
+ await settle(1200);
+ expect(['unlocked', 'unlocking', 'open', 'opening']).toContain(home.states[lock].state);
+
+ // Locking back up is the safe direction and needs no confirmation.
+ await home.call('lock', 'lock', { entity_id: lock });
+ await settle(1200);
+ expect(['locked', 'locking']).toContain(home.states[lock].state);
+ }, 20_000);
+
+ it('reports a bad token as an auth problem, not a network one', async () => {
+ const bad = new HomeBridge({ baseUrl, token: 'not-a-real-token' });
+ await expect(bad.connect()).rejects.toMatchObject({ code: ERR.AUTH });
+ }, 20_000);
+
+ it('runs the household macro this house actually has', async () => {
+ const { match } = await home.activate('good night', { dryRun: true });
+ if (!match) return;
+ expect(match.kind).toMatch(/^(scene|script)$/);
+ const result = await home.activate('good night');
+ expect(result.ran).toBe(true);
+ }, 20_000);
+
+ it('opens the MCP channel when the integration is enabled, and gates its tools', async () => {
+ let mcp;
+ try {
+ mcp = await connectHomeMcp({
+ baseUrl,
+ token,
+ entities: () => flattenEntities(home.graph),
+ isAllowed: (id) => home.allowList.has(id),
+ });
+ } catch (err) {
+ // An instance without mcp_server set up is the ordinary case, and the
+ // error has to say so rather than looking like an outage.
+ expect(err.code).toBe(ERR.NO_MCP);
+ return;
+ }
+
+ expect(mcp.tools.length).toBeGreaterThan(0);
+ const lock = Object.keys(home.states).find((id) => id.startsWith('lock.'));
+ if (lock) {
+ const name = home.states[lock].attributes.friendly_name;
+ await expect(mcp.callTool({ name: 'intent__HassTurnOff', arguments: { name } })).rejects.toMatchObject({
+ code: ERR.NEEDS_CONFIRMATION,
+ });
+ }
+ await mcp.close();
+ }, 30_000);
+});
diff --git a/public/changelog.json b/public/changelog.json
index 34b91384e..2ac28fd9c 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-02T21:11:24.271Z",
+ "generated_at": "2026-09-02T21:28:54.811Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -16,6 +16,16 @@
"launch"
]
},
+ {
+ "date": "2026-09-02",
+ "type": "launch",
+ "title": "Docs · three.ws Home",
+ "summary": "How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.",
+ "link": "/docs/smart-home",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-09-02",
"type": "launch",
@@ -185,6 +195,18 @@
"fix"
]
},
+ {
+ "date": "2026-09-02",
+ "type": "update",
+ "title": "Groundwork for agents that can run your house",
+ "summary": "A three.ws agent already has a body, a voice and a memory, all of it stuck inside a browser tab. This is the first piece of letting it reach past the screen: a new developer package, @three-ws/home-bridge, that connects an agent to a real Home Assistant, the open-source home platform that already runs in millions of houses and already speaks to Zigbee, Z-Wave, Matter, Thread and about fifteen hundred other things. We wrote no device code at all, on purpose. What the package adds is the part nobody had built: live state from the house shaped into rooms, so a 3D scene can dim when your real lights dim; \"good night\" and \"I'm leaving\" resolved to the scenes you already made yourself, in Home Assistant, rather than to something we invented for you; and a safety gate that reads the way our on-chain one does. Turning a light off is free. Unlocking a door stops and asks you, every time, until you say otherwise for that one door. Locking up never asks, because moving your house toward safety should not need permission. That last part turned out to matter more than expected: Home Assistant's own \"turn it off\" command performs an unlock when you point it at a lock, so an assistant told to turn something off can open your front door with nothing in the command's name to warn anyone. Our gate catches it. All of it was built and checked against a real Home Assistant running here, not against stand-ins, and the write-up of what else is out there and where this goes next (voice in every room, the agent standing in a live model of your home) is published alongside it.",
+ "link": "/docs/smart-home",
+ "tags": [
+ "sdk",
+ "docs",
+ "security"
+ ]
+ },
{
"date": "2026-09-02",
"type": "update",
@@ -249,6 +271,16 @@
"feature"
]
},
+ {
+ "date": "2026-09-02",
+ "type": "update",
+ "title": "Take a photo of your world and post it",
+ "summary": "Press P in a /play world, or the camera button on the HUD, and the world is captured onto a share card: your view of the town with the three.ws mark, the coin you are standing in and the date along the bottom, ready to download or paste straight into a post. The interface is never in the shot. The photo is a second frame rendered off screen just for you, so the chat, the job board and the name tags stay out of the picture no matter what is on screen when you press. It works in zen mode too, which is usually exactly when the world looks worth photographing, and while an event is running the card carries that event's name. Nothing is uploaded anywhere: the card is built in your browser and it is yours. The whole feature only downloads on your first press, so a session that never takes a photo never pays for it.",
+ "link": "/play",
+ "tags": [
+ "feature"
+ ]
+ },
{
"date": "2026-09-02",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 2a09f505d..f25089612 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -14,6 +14,14 @@
<category>launch</category>
<description>How to print any three.ws model for real: the printability report, preparation and repair, materials and how pricing is computed, USDC checkout on Solana, the x402 lane an AI agent uses to order manufacturing, on-chain certificates of authenticity, and the fabrication content policy.</description>
</item>
+ <item>
+ <title>Docs · three.ws Home</title>
+ <link>https://three.ws/docs/smart-home</link>
+ <guid isPermaLink="false">2026-09-02:Docs · three.ws Home</guid>
+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>
+ <category>launch</category>
+ <description>How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.</description>
+ </item>
<item>
<title>Generated animation seeding</title>
<link>https://three.ws/docs/animation-seeding</link>
@@ -142,6 +150,14 @@
<category>fix</category>
<description>The terminal page's footer offered an Avatars link that pointed at an address the site does not serve, so clicking it returned a 404 instead of the avatar gallery. It now opens the gallery, the same place every other page sends you. On the knock page, a placeholder link that sat empty until the profile finished loading was removed, so people navigating by keyboard or screen reader no longer land on a link with no name and nowhere to go.</description>
</item>
+ <item>
+ <title>Groundwork for agents that can run your house</title>
+ <link>https://three.ws/docs/smart-home</link>
+ <guid isPermaLink="false">2026-09-02:Groundwork for agents that can run your house</guid>
+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>
+ <category>sdk</category>
+ <description>A three.ws agent already has a body, a voice and a memory, all of it stuck inside a browser tab. This is the first piece of letting it reach past the screen: a new developer package, @three-ws/home-bridge, that connects an agent to a real Home Assistant, the open-source home platform that already runs in millions of houses and already speaks to Zigbee, Z-Wave, Matter, Thread and about fifteen hundred other things. We wrote no device code at all, on purpose. What the package adds is the part nobody had built: live state from the house shaped into rooms, so a 3D scene can dim when your real lights dim; &quot;good night&quot; and &quot;I'm leaving&quot; resolved to the scenes you already made yourself, in Home Assistant, rather than to something we invented for you; and a safety gate that reads the way our on-chain one does. Turning a light off is free. Unlocking a door stops and asks you, every time, until you say otherwise for that one door. Locking up never asks, because moving your house toward safety should not need permission. That last part turned out to matter more than expected: Home Assistant's own &quot;turn it off&quot; command performs an unlock when you point it at a lock, so an assistant told to turn something off can open your front door with nothing in the command's name to warn anyone. Our gate catches it. All of it was built and checked against a real Home Assistant running here, not against stand-ins, and the write-up of what else is out there and where this goes next (voice in every room, the agent standing in a live model of your home) is published alongside it.</description>
+ </item>
<item>
<title>License terms for three.ws containers on NVIDIA NGC</title>
<link>https://three.ws/legal/nvidia-ngc-eula</link>
@@ -190,6 +206,14 @@
<category>fix</category>
<description>Press P in a coin world, or the camera button on the heads-up display, and you get a picture of the world on a share card: the scene itself, the three.ws mark, the coin you are standing in, and, during a live event, that event's name stamped on it. The card was there but the shutter went nowhere. Every single press answered &quot;Couldn't photograph the world just now&quot; and showed nothing, because of a fault in the code that builds the preview, so nobody has ever actually been handed one of these. Pressing it now opens the card, with Download and Copy image next to it. The picture is taken as a separate render rather than grabbed off the screen, so no panel, name tag or chat line is ever in the frame, and it works the same in zen mode, which is when most people will want it. It costs nothing when you are not using it: none of photo mode is loaded until the first press. Two smaller things fixed alongside: taking a second photo while the first card is open now replaces it cleanly instead of briefly stacking two sheets, where a click landing in the wrong moment could dismiss the shot you just took; and the line promising that P takes another one is true now, and visible, having previously rendered as nothing at all. The camera button also stays lit while the picture is being taken, instead of going quiet: taking the photo is real work, and on a slow phone it can run for a few seconds, which previously looked like a button that did nothing. Verified end to end in both Chrome and Safari, on a laptop frame and a phone frame, down to the pixels in the saved file, so the black rectangle that a mishandled 3D screenshot usually produces cannot come back unnoticed.</description>
</item>
+ <item>
+ <title>Take a photo of your world and post it</title>
+ <link>https://three.ws/play</link>
+ <guid isPermaLink="false">2026-09-02:Take a photo of your world and post it</guid>
+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Press P in a /play world, or the camera button on the HUD, and the world is captured onto a share card: your view of the town with the three.ws mark, the coin you are standing in and the date along the bottom, ready to download or paste straight into a post. The interface is never in the shot. The photo is a second frame rendered off screen just for you, so the chat, the job board and the name tags stay out of the picture no matter what is on screen when you press. It works in zen mode too, which is usually exactly when the world looks worth photographing, and while an event is running the card carries that event's name. Nothing is uploaded anywhere: the card is built in your browser and it is yours. The whole feature only downloads on your first press, so a session that never takes a photo never pays for it.</description>
+ </item>
<item>
<title>Text-to-animation is no longer rationed like a paid service</title>
<link>https://three.ws/animations</link>
diff --git a/public/features.json b/public/features.json
index 8af4774f4..f401f6622 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-02T21:11:24.224Z",
+ "generated_at": "2026-09-02T21:28:54.711Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
@@ -3197,6 +3197,16 @@
"tags": [],
"showcase": false
},
+ {
+ "path": "/docs/smart-home",
+ "title": "Docs · three.ws Home",
+ "description": "How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.",
+ "added": "2026-09-02",
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": false
+ },
{
"path": "/docs/tty-avatar",
"title": "Docs · Terminal avatar",
diff --git a/public/llms-full.txt b/public/llms-full.txt
index 8899df05d..3cf47917c 100644
--- a/public/llms-full.txt
+++ b/public/llms-full.txt
@@ -1947,6 +1947,12 @@ URL: https://three.ws/docs/avatar-artifact
The standalone avatar viewer you paste into any site as a one-line iframe: its ?agent= and ?model= parameters, the hosts a model may come from, how a clip-less rig still comes to life, and the sentence the page shows for every way it can fail.
+### Docs · three.ws Home
+
+URL: https://three.ws/docs/smart-home
+
+How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.
+
### Docs · Terminal avatar
URL: https://three.ws/docs/tty-avatar
diff --git a/public/llms.txt b/public/llms.txt
index 57bf854d9..4623c14fa 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -360,6 +360,7 @@ Docs, tutorials, and reference.
- [Docs](https://three.ws/docs): Full documentation: SDKs, API reference, embedding, agent system, smart contracts.
- [Docs · Skill bundles](https://three.ws/docs/skill-bundles): How a bundle of an agent's skills is priced from that agent's own sales rather than a rule of thumb: the median-basket and flat-discount bases, the public pricing and backtest endpoint, the owner endpoints that publish and retire a bundle, and the on-chain checkout that unlocks every skill in one payment.
- [Docs · Avatar Artifact viewer](https://three.ws/docs/avatar-artifact): The standalone avatar viewer you paste into any site as a one-line iframe: its ?agent= and ?model= parameters, the hosts a model may come from, how a clip-less rig still comes to life, and the sentence the page shows for every way it can fail.
+- [Docs · three.ws Home](https://three.ws/docs/smart-home): How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.
- [Docs · Terminal avatar](https://three.ws/docs/tty-avatar): The @three-ws/tty-avatar package: any three.ws avatar or agent body rendered live in a terminal by a software rasterizer (truecolor half-blocks, braille, or plain ASCII), procedural moods, and Claude Code hooks that turn it into your coding agent's face.
- [Docs · Site load performance](https://three.ws/docs/site-performance): The load-cost rules behind every page that is not /play, each with the Lighthouse measurement that produced it: catalogue grids skip the rows nobody can see, analytics waits for the first idle moment, the CDN bundle ships minified, below-the-fold sections load below the fold, and thumbnails decode off the critical path.
- [Docs · Farcaster memory seeding](https://three.ws/docs/farcaster-memory-seeding): Give an agent your Farcaster voice with explicit consent: ownership is proved by signing a challenge with a wallet the fid itself verified on the protocol (Solana first), only your public profile and casts are read, and revoking the grant deletes every memory it produced.
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index 721a9fc2c..2aa95c515 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -83,7 +83,7 @@
<main class="sm-wrap">
<div class="sm-hero">
<h1>Sitemap</h1>
- <p>All 885 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
+ <p>All 886 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
<div class="sm-formats">
<a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
<a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>
@@ -95,7 +95,7 @@
</div>
<div class="sm-filter">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>
- <input id="sm-filter-input" type="search" placeholder="Filter 885 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
+ <input id="sm-filter-input" type="search" placeholder="Filter 886 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
<kbd aria-hidden="true">/</kbd>
</div>
<p class="sm-filter-count" id="sm-filter-count" role="status" aria-live="polite"></p>
@@ -127,6 +127,14 @@
<span class="sm-desc">Check the certificate of authenticity that ships with every three.ws physical print. Scan the code on the box or type the certificate number to see the original 3D model spinning, its edition number, the SHA-256 of the exact bytes that went to the printer, and the Solana transaction attesting both. Each certificate lives at /cert/&lt;id&gt;.</span>
</a>
</li>
+ <li>
+ <a href="/docs/smart-home">
+ <span class="sm-new-date">Sep 2, 2026</span>
+ <span class="sm-title">Docs · three.ws Home</span>
+ <span class="sm-path">/docs/smart-home</span>
+ <span class="sm-desc">How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.</span>
+ </a>
+ </li>
<li>
<a href="/docs/materialize">
<span class="sm-new-date">Sep 2, 2026</span>
@@ -167,14 +175,6 @@
<span class="sm-desc">How three.ws keeps real 3D on ordinary pages without making them slow: previews that spin only while someone is looking, models that load when they are wanted, boxes reserved before late content arrives, and images fetched at the size they are shown.</span>
</a>
</li>
- <li>
- <a href="/docs/spotlight">
- <span class="sm-new-date">Sep 1, 2026</span>
- <span class="sm-title">Docs · Agent Spotlight</span>
- <span class="sm-path">/docs/spotlight</span>
- <span class="sm-desc">How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.</span>
- </a>
- </li>
</ul>
</section>
<nav class="sm-toc" aria-label="Sections">
@@ -2416,7 +2416,7 @@
<section class="sm-section" id="learn">
<header>
- <h2>Learn<span class="sm-count" data-count>402</span></h2>
+ <h2>Learn<span class="sm-count" data-count>403</span></h2>
<p class="sm-section-desc">Docs, tutorials, and reference.</p>
</header>
<ul class="sm-list">
@@ -2448,6 +2448,13 @@
<span class="sm-desc">The standalone avatar viewer you paste into any site as a one-line iframe: its ?agent= and ?model= parameters, the hosts a model may come from, how a clip-less rig still comes to life, and the sentence the page shows for every way it can fail.</span>
</a>
</li>
+ <li>
+ <a href="/docs/smart-home">
+ <span class="sm-title">Docs · three.ws Home</span>
+ <span class="sm-path">/docs/smart-home</span>
+ <span class="sm-desc">How a three.ws agent connects to a real house: the open-source smart-home landscape measured and shortlisted, why Home Assistant owns the device layer, the two channels the @three-ws/home-bridge package speaks, the physical-action gate that never lets an unlock through unasked, and the road from here to voice in every room.</span>
+ </a>
+ </li>
<li>
<a href="/docs/tty-avatar">
<span class="sm-title">Docs · Terminal avatar</span>
diff --git a/scripts/capture-home-fixture.mjs b/scripts/capture-home-fixture.mjs
new file mode 100644
index 000000000..c52a2a4d1
--- /dev/null
+++ b/scripts/capture-home-fixture.mjs
@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Records a real Home Assistant instance into the @three-ws/home-bridge test
+// fixture. The room-graph tests run against a recording of a live instance
+// rather than hand-written shapes, so a Home Assistant registry change shows up
+// as a test failure instead of a production surprise.
+//
+// HOME_ASSISTANT_URL=http://localhost:8123 \
+// HOME_ASSISTANT_TOKEN=<long-lived token> \
+// node scripts/capture-home-fixture.mjs
+//
+// A throwaway instance is one command:
+// docker run -d --name ha -p 8123:8123 ghcr.io/home-assistant/home-assistant:stable
+// then add `demo:` to its configuration.yaml for a house full of real entities.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HA = (process.env.HOME_ASSISTANT_URL || 'http://localhost:8123').replace(/\/+$/, '');
+const TOKEN = process.env.HOME_ASSISTANT_TOKEN;
+const OUT = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '..',
+ 'packages/home-bridge/tests/fixtures/home.json',
+);
+
+if (!TOKEN) {
+ console.error('HOME_ASSISTANT_TOKEN is required (Profile, Security, Long-lived access tokens).');
+ process.exit(1);
+}
+
+// Entity domains the room graph renders, plus the scene and script entities the
+// intent resolver matches against. Everything else is noise in a fixture.
+const KEEP =
+ /^(light|lock|cover|climate|switch|fan|binary_sensor|media_player|alarm_control_panel|valve|scene|script|sensor\.outside_temperature)/;
+
+const registries = await readRegistries();
+const raw = await fetchJson('/api/states');
+
+const states = {};
+for (const s of raw) {
+ if (KEEP.test(s.entity_id)) states[s.entity_id] = { entity_id: s.entity_id, state: s.state, attributes: s.attributes };
+}
+const keep = new Set(Object.keys(states));
+
+const fixture = {
+ _source:
+ 'Recorded from a real Home Assistant instance (docker ghcr.io/home-assistant/home-assistant:stable) running the demo integration, with three areas, one floor, and two user scenes. Not hand-written: regenerate by pointing scripts/capture-home-fixture.mjs at any instance.',
+ floors: registries.floors.map((f) => ({ floor_id: f.floor_id, name: f.name, level: f.level, icon: f.icon ?? null })),
+ areas: registries.areas.map((a) => ({ area_id: a.area_id, name: a.name, icon: a.icon ?? null, floor_id: a.floor_id ?? null, aliases: a.aliases || [] })),
+ devices: registries.devices.map((d) => ({ id: d.id, area_id: d.area_id ?? null, name: d.name_by_user || d.name })),
+ entities: registries.entities
+ .filter((e) => keep.has(e.entity_id))
+ .map((e) => ({
+ entity_id: e.entity_id,
+ device_id: e.device_id ?? null,
+ area_id: e.area_id ?? null,
+ name: e.name ?? null,
+ original_name: e.original_name ?? null,
+ original_device_class: e.original_device_class ?? null,
+ disabled_by: e.disabled_by ?? null,
+ hidden_by: e.hidden_by ?? null,
+ })),
+ states,
+};
+
+fs.writeFileSync(OUT, `${JSON.stringify(fixture, null, '\t')}\n`);
+console.log(
+ `wrote ${path.relative(process.cwd(), OUT)}: ${fixture.areas.length} areas, ${fixture.floors.length} floors, ${fixture.entities.length} registry entities, ${Object.keys(states).length} states`,
+);
+
+async function fetchJson(pathname) {
+ const res = await fetch(HA + pathname, { headers: { authorization: `Bearer ${TOKEN}` } });
+ if (!res.ok) throw new Error(`${pathname} returned ${res.status}`);
+ return res.json();
+}
+
+async function readRegistries() {
+ const wsUrl = `${HA.replace(/^http/, 'ws')}/api/websocket`;
+ const socket = new WebSocket(wsUrl);
+ let nextId = 1;
+ const pending = new Map();
+
+ await new Promise((ready, fail) => {
+ socket.onerror = () => fail(new Error(`Could not open ${wsUrl}`));
+ socket.onmessage = (event) => {
+ const msg = JSON.parse(event.data);
+ if (msg.type === 'auth_required') return socket.send(JSON.stringify({ type: 'auth', access_token: TOKEN }));
+ if (msg.type === 'auth_ok') return ready();
+ if (msg.type === 'auth_invalid') return fail(new Error('Home Assistant rejected the token.'));
+ if (msg.type === 'result') {
+ const entry = pending.get(msg.id);
+ pending.delete(msg.id);
+ if (msg.success) entry.resolve(msg.result);
+ else entry.reject(new Error(JSON.stringify(msg.error)));
+ }
+ };
+ });
+
+ const call = (type) =>
+ new Promise((resolve, reject) => {
+ const id = nextId++;
+ pending.set(id, { resolve, reject });
+ socket.send(JSON.stringify({ id, type }));
+ }).catch(() => []);
+
+ const [floors, areas, devices, entities] = await Promise.all([
+ call('config/floor_registry/list'),
+ call('config/area_registry/list'),
+ call('config/device_registry/list'),
+ call('config/entity_registry/list'),
+ ]);
+ socket.close();
+ return { floors, areas, devices, entities };
+}