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.

37.8 KB
Raw Blame
/**
 * The connect flow for /smart-home.
 *
 * Gets a stranger from "I have a Home Assistant somewhere" to "my agent is
 * connected", and designs every way that goes wrong. There are eleven states
 * and a missing one is what makes a product feel unfinished, so they are
 * enumerated in STATE rather than implied by whichever branch happened to run.
 *
 * Three rules this module holds and never bends:
 *
 *   1. The access token goes to the server exactly once and never comes back.
 *      It is never written to localStorage, never put in a URL, never logged,
 *      and never echoed by the API. The field is cleared the moment a connect
 *      succeeds.
 *   2. Reachability is decided in the browser, before the network. A
 *      192.168.x.x or .local address cannot be reached by three.ws no matter
 *      how long we wait, so we say so immediately instead of spending fifteen
 *      seconds arriving at a worse version of the same sentence.
 *   3. Every string that came from a house (a label, a room, an entity, an
 *      error) is rendered as text. Entity and area names are attacker
 *      influenced, they flow into a page and into a model prompt, and there is
 *      a physical actuator on the other end.
 */

// The `/url` subpath, not the package root: url.js is pure string handling, and
// importing it directly keeps the Home Assistant WebSocket client and the MCP
// SDK (both behind the root export) out of this page's bundle. The same
// functions the server validates with, so the two cannot disagree.
import { isPrivateHost, normalizeBaseUrl } from '@three-ws/home-bridge/url';

import { disclosurePanel } from './disclosure-panel.js';
import { isDegraded, renderManage } from './manage.js';
// Every string a person reads on this page goes through here. Their own words
// (the name they gave their house, the address they typed, a message their own
// Home Assistant returned) are interpolated as values, never baked into a
// source string. See i18n-home.js.
import { plural, t } from './i18n-home.js';

/** The eleven states. Each one has a designed treatment; none falls through. */
export const STATE = Object.freeze({
	SIGNED_OUT: 'signed_out',
	EMPTY: 'empty',
	VALIDATING: 'validating',
	PRIVATE_HOST: 'private_host',
	VERIFYING: 'verifying',
	CONNECTED: 'connected',
	AUTH_FAILED: 'auth_failed',
	UNREACHABLE: 'unreachable',
	DEGRADED: 'degraded',
	REVOKED: 'revoked',
	MANY: 'many',
	/**
	 * Not in the original eleven: the plan ceiling. It surfaced the first time a
	 * second house was connected on a free account, and it needs its own
	 * treatment because the recovery is commercial, not technical: sending
	 * someone back to re-check a URL that was never wrong is the worst possible
	 * answer to "you have run out of homes".
	 */
	QUOTA_REACHED: 'quota_reached',
	/**
	 * Not a failure of the flow above: the other half of it. Most Home Assistant
	 * installs have no address three.ws could ever dial, so for those the house
	 * dials out to us through a small integration. src/home/pair.js owns the
	 * seven states inside this one.
	 */
	PAIRING: 'pairing',
	/**
	 * One home, deep-linked at /smart-home/:id. The route existed before this
	 * state did, which made "Open" on a card a link back to the page it was
	 * already on: a dead path dressed as a button.
	 */
	ONE_HOME: 'one_home',
	/** That id is not a home this account has. Says nothing about whether it exists. */
	NOT_FOUND: 'not_found',
});

/**
 * `/smart-home/<uuid>/settings` addresses one home's settings card; anything
 * else here is the whole list. The bare `/smart-home/<uuid>` is the live 3D
 * house, which is what "Open" on a card means to a person.
 */
const HOME_ID_IN_PATH = /^\/smart-home\/([0-9a-fA-F-]{36})\/settings\/?$/;

/** Where Home Assistant hides the token minting screen. Never make anyone hunt. */
const TOKEN_PATH = 'Profile, Security, Long-lived access tokens, Create token';

const root = document.getElementById('hm-root');

/** Session-lived only: never persisted, so a reload re-reads it from the server. */
let csrfToken = '';

/**
 * The screen currently on the page. State 3 (validating) is a property of one
 * field rather than a different screen, so it is flipped on and off over this
 * without re-rendering: rebuilding the card on a keystroke would take the caret
 * out of the field the person is typing in.
 */
let renderedState = null;

boot();

async function boot() {
	if (!root) return;
	try {
		const homes = await listHomes();
		if (homes === null) return render(STATE.SIGNED_OUT);

		const deepLink = HOME_ID_IN_PATH.exec(location.pathname);
		if (deepLink) {
			const one = homes.find((h) => h.id === deepLink[1]);
			// A miss is answered exactly like a home that belongs to somebody else,
			// because from here they are the same thing and neither should confirm
			// that an id is real.
			return one ? render(STATE.ONE_HOME, { homes: [one] }) : render(STATE.NOT_FOUND, { homes });
		}
		renderHomes(homes);
	} catch (err) {
		// The list failing is not the connect flow failing: offer the connect card
		// with the reason attached, so a stranger is never staring at a dead page.
		render(STATE.EMPTY, { notice: { tone: 'error', title: t('home_connect.list_failed', 'We could not load your homes.'), body: messageOf(err) } });
	}
}

function renderHomes(homes, notice) {
	if (!homes.length) return render(STATE.EMPTY, notice ? { notice } : {});
	render(listState(homes), { homes, ...(notice ? { notice } : {}) });
}

/**
 * Which of the list states this set of houses is in.
 *
 * The manage view renders all three identically on purpose (one list that
 * scales), but the page still has to be able to say which one it is: a card
 * reading "not answering right now" under `data-state="connected"` is the page
 * disagreeing with itself, and it is the difference between state 9 being
 * designed and state 9 being a paragraph.
 */
function listState(homes) {
	if (homes.length > 1) return STATE.MANY;
	return isDegraded(homes[0]) ? STATE.DEGRADED : STATE.CONNECTED;
}

/**
 * Is this stored home the one the user just typed? Compared on the normalized
 * form, because "home.example.com" and "https://home.example.com/" are the same
 * house and the server stores only the normalized one.
 */
function sameHouse(storedBaseUrl, typedBaseUrl) {
	try {
		return storedBaseUrl === normalizeBaseUrl(typedBaseUrl).http;
	} catch {
		return false;
	}
}

// ── The renderer ────────────────────────────────────────────────────────────

/**
 * Render one state. Every path in the flow ends in exactly one call to this, so
 * "which state am I in" is always answerable and never implicit.
 */
function render(state, data = {}) {
	root.setAttribute('aria-busy', state === STATE.VERIFYING ? 'true' : 'false');
	renderedState = state;
	root.dataset.state = state;
	clear(root);

	switch (state) {
		case STATE.SIGNED_OUT: return root.append(signedOut());
		case STATE.EMPTY: return root.append(connectCard(data));
		case STATE.PRIVATE_HOST: return root.append(connectCard(data));
		case STATE.VERIFYING: return root.append(verifying(data));
		case STATE.AUTH_FAILED: return root.append(connectCard(data));
		case STATE.UNREACHABLE: return root.append(connectCard(data));
		case STATE.REVOKED: return root.append(connectCard(data));
		case STATE.QUOTA_REACHED: return root.append(quotaCard(data));
		case STATE.NOT_FOUND: return root.append(notFoundCard(data));
		case STATE.ONE_HOME:
			return root.append(renderManage({
				homes: data.homes || [],
				notice: data.notice,
				onDisconnect: disconnect,
				onReconnect: showConnectCard,
				focused: true,
			}));
		case STATE.PAIRING: return root.append(pairingHost(data));
		case STATE.CONNECTED:
		case STATE.DEGRADED:
		case STATE.MANY:
			return root.append(renderManage({ homes: data.homes || [], notice: data.notice, onDisconnect: disconnect, onReconnect: showConnectCard }));
		default:
			return root.append(connectCard(data));
	}
}

// ── State 1: signed out ─────────────────────────────────────────────────────

/**
 * A disabled form is a worse answer than an explanation: it looks broken and it
 * tells a visitor nothing about why the feature is worth signing in for.
 */
function signedOut() {
	const panel = el('section', 'hm-panel');
	panel.append(
		el('h2', 'hm-panel-title', t('home_connect.signed_out_title', 'Sign in to connect a home')),
		el('p', 'hm-panel-sub', t('home_connect.signed_out_sub', 'Your homes are tied to your three.ws account, because the credential that opens your house is stored encrypted against it and never in this browser.')),
	);

	const list = el('ul', 'hm-ol');
	list.style.listStyle = 'disc';
	for (const line of [
		t('home_connect.signed_out_point_1', 'Your agent reads every room, light, lock and sensor your instance exposes.'),
		t('home_connect.signed_out_point_2', 'It runs the scenes and scripts you already built, by name.'),
		t('home_connect.signed_out_point_3', 'Locking up, closing and arming never prompt. Unlocking, opening and disarming always do.'),
	]) list.append(el('li', '', line));
	panel.append(list);

	const actions = el('div', 'hm-actions');
	actions.style.marginTop = 'var(--space-md)';
	const signIn = el('a', 'hm-btn hm-btn-primary', t('home_connect.sign_in', 'Sign in'));
	signIn.href = `/login?next=${encodeURIComponent('/smart-home')}`;
	const learn = el('a', 'hm-btn hm-btn-ghost', t('home_connect.how_it_works', 'How it works'));
	learn.href = '/docs/smart-home';
	actions.append(signIn, learn);
	panel.append(actions);
	return panel;
}

// ── States 2, 4, 7, 8, 10: the connect card and its failures ────────────────

/**
 * One card serves the empty state and every recoverable failure, because they
 * differ only in the notice above the fields and in which field takes focus.
 * Rebuilding a different card per failure is how the states drift apart.
 */
function connectCard({ notice, values = {}, focus } = {}) {
	const panel = el('section', 'hm-panel');
	const head = el('div', 'hm-panel-head');
	const heading = el('div');
	heading.append(
		el('h2', 'hm-panel-title', t('home_connect.card_title', 'Connect a Home Assistant')),
		el('p', 'hm-panel-sub', t('home_connect.card_sub', 'Everything runs against your own instance. What we store, and what we never store, is spelled out below before you connect.')),
	);
	head.append(heading);
	panel.append(head);

	if (notice) panel.append(noticeEl(notice));

	const form = el('form', 'hm-form');
	form.noValidate = true;

	const label = field({
		id: 'hm-label',
		label: t('home_connect.label_label', 'What do you call it?'),
		hint: t('home_connect.label_hint', 'Shown in your agent and in the action log. "Home", "The office", anything.'),
		value: values.label || '',
		attrs: { type: 'text', maxlength: '120', autocomplete: 'off', placeholder: t('home_connect.label_placeholder', 'Home') },
	});

	const url = field({
		id: 'hm-url',
		label: t('home_connect.url_label', 'Your Home Assistant address'),
		hint: t('home_connect.url_hint', 'The https URL you use from outside the house: Home Assistant Cloud, or your own reverse proxy.'),
		value: values.baseUrl || '',
		attrs: { type: 'url', inputmode: 'url', autocomplete: 'off', spellcheck: 'false', placeholder: 'https://your-home.ui.nabu.casa' },
	});

	const token = tokenField(values.token || '');

	form.append(label.wrap, url.wrap, token.wrap);

	const actions = el('div', 'hm-actions');
	const submit = el('button', 'hm-btn hm-btn-primary', t('home_connect.submit', 'Connect this home'));
	submit.type = 'submit';
	actions.append(submit);
	form.append(actions);

	// State 3: validate as they type, before anything touches the network. The
	// message appears under the field the moment the address is unreachable in
	// principle, which is the only honest time to say it.
	const liveValidate = () => {
		const typed = url.input.value.trim();
		const verdict = checkReachable(url.input.value);
		const invalid = Boolean(typed) && !verdict.ok;
		url.input.setAttribute('aria-invalid', invalid ? 'true' : 'false');
		setInlineError(url, verdict.ok ? '' : verdict.short);
		// The page names the state it is in without rebuilding the card, so a
		// keystroke never costs the caret and the state stays answerable.
		root.dataset.state = invalid ? STATE.VALIDATING : renderedState;
	};
	url.input.addEventListener('input', liveValidate);
	url.input.addEventListener('blur', liveValidate);

	form.addEventListener('submit', (event) => {
		event.preventDefault();
		submitConnect({ form, label: label.input, url: url.input, token: token.input, submit });
	});

	// The disclosure sits between the form and the help, which is the last thing
	// on screen before somebody reaches for the button. It is never folded: a
	// promise you have to open is not one you were told.
	panel.append(disclosurePanel('home.connect', { el }));
	panel.append(form);
	panel.append(tokenHelp());

	// Focus lands on the field that has to change, not back at the top of the
	// form, so keyboard users are not made to walk the whole card again.
	queueMicrotask(() => {
		const target = focus === 'token' ? token.input : focus === 'url' ? url.input : focus === 'label' ? label.input : null;
		if (target) {
			target.focus();
			if (typeof target.select === 'function' && focus === 'token') target.select();
		}
	});

	return panel;
}

/**
 * A deep link to a home this account does not have. Worded so it reveals
 * nothing: a home that was disconnected, a link from someone else's household
 * and an id that never existed all read the same here.
 */
function notFoundCard({ homes = [] } = {}) {
	const panel = el('section', 'hm-panel');
	const wrap = el('div', 'hm-empty');
	wrap.append(
		el('p', 'hm-empty-title', t('home_connect.not_yours_title', 'That home is not on this account')),
		el('p', 'hm-empty-body', homes.length
			? t('home_connect.not_yours_body_some', 'It may have been disconnected, or the link may belong to a different account. Your own homes are below.')
			: t('home_connect.not_yours_body_none', 'It may have been disconnected, or the link may belong to a different account. You have no homes connected yet.')),
	);
	const actions = el('div', 'hm-actions');
	actions.style.justifyContent = 'center';
	const all = el('a', 'hm-btn hm-btn-primary', homes.length ? t('home_connect.see_your_homes', 'See your homes') : t('home_connect.connect_a_home', 'Connect a home'));
	all.href = '/smart-home';
	actions.append(all);
	wrap.append(actions);
	panel.append(wrap);
	queueMicrotask(() => all.focus());
	return panel;
}

/**
 * The plan ceiling. No form: re-submitting the same house would hit the same
 * wall, so the card offers only the two actions that actually change the answer.
 */
function quotaCard({ notice, upgrade } = {}) {
	const panel = el('section', 'hm-panel');
	panel.append(el('h2', 'hm-panel-title', t('home_connect.quota_title', 'This account is at its home limit')));
	if (notice) panel.append(noticeEl(notice));

	const actions = el('div', 'hm-actions');
	const up = el('a', 'hm-btn hm-btn-primary', t('home_connect.see_the_plans', 'See the plans'));
	up.href = typeof upgrade === 'string' && upgrade.startsWith('/') ? upgrade : '/pricing';
	const back = el('button', 'hm-btn hm-btn-ghost', t('home_connect.back_to_homes', 'Back to my homes'));
	back.type = 'button';
	back.addEventListener('click', () => boot());
	actions.append(up, back);
	panel.append(actions);
	queueMicrotask(() => up.focus());
	return panel;
}

/** Where to get a token, inline, so nobody has to go and search for it. */
function tokenHelp() {
	const wrap = el('details', 'hm-panel hm-details');
	wrap.style.marginTop = 'var(--space-md)';
	wrap.style.background = 'transparent';
	const summary = el('summary', '', t('home_connect.token_help_summary', 'Where do I get an access token?'));
	summary.style.cursor = 'pointer';
	summary.style.fontWeight = 'var(--weight-medium)';
	wrap.append(summary);

	const steps = el('ol', 'hm-ol');
	for (const step of [
		t('home_connect.token_step_1', 'Open your Home Assistant and click your user name at the bottom of the sidebar.'),
		t('home_connect.token_step_2', 'Go to the Security tab.'),
		t('home_connect.token_step_3', 'Scroll to Long-lived access tokens and choose Create token.'),
		t('home_connect.token_step_4', 'Name it "three.ws" and copy the token. Home Assistant shows it once.'),
	]) steps.append(el('li', '', step));
	wrap.append(steps);

	const note = el('p', 'hm-hint', t('home_connect.token_help_note', 'The token is encrypted before it is stored and is never sent back to this page. Deleting it in Home Assistant revokes our access immediately, whatever we hold.'));
	note.style.marginTop = 'var(--space-sm)';
	wrap.append(note);
	return wrap;
}

// ── State 5: verifying ──────────────────────────────────────────────────────

/**
 * Named steps, not a bare spinner and not a fake progress bar: each line flips
 * when that step actually completes, so the screen never claims progress it did
 * not make.
 */
function verifying({ steps = [], onCancel } = {}) {
	const panel = el('section', 'hm-panel');
	panel.append(
		el('h2', 'hm-panel-title', t('home_connect.verifying_title', 'Opening a connection to your home')),
		el('p', 'hm-panel-sub', t('home_connect.verifying_sub', 'This runs against your instance directly. It usually takes a second or two.')),
	);

	const list = el('ul', 'hm-steps');
	for (const step of steps) {
		const li = el('li', 'hm-step');
		li.dataset.state = step.state;
		const mark = el('span', 'hm-step-mark', step.state === 'done' ? '✓' : '');
		mark.setAttribute('aria-hidden', 'true');
		li.append(mark, el('span', '', step.text));
		list.append(li);
	}
	panel.append(list);

	const actions = el('div', 'hm-actions');
	actions.style.marginTop = 'var(--space-md)';
	const cancel = el('button', 'hm-btn hm-btn-ghost', t('home_connect.cancel', 'Cancel'));
	cancel.type = 'button';
	cancel.addEventListener('click', () => onCancel && onCancel());
	actions.append(cancel);
	panel.append(actions);
	return panel;
}

/**
 * The pairing flow lives in its own module and manages its own states; this is
 * only the seam that hands it a container and takes the user back when they
 * decide their house has a web address after all.
 */
function pairingHost() {
	const host = el('div', 'hm-pairhost');
	// Deferred so the pairing module (and the polling it starts) is not in the
	// bundle for the many visitors who never open this path.
	import('./pair.js').then(({ renderPairing }) => {
		activePairing?.destroy();
		activePairing = renderPairing({
			mount: host,
			onCancel: () => {
				activePairing?.destroy();
				activePairing = null;
				render(STATE.EMPTY);
			},
			onLinked: () => {
				// The home is real from here on, so the list is what should own it.
				listHomes().then((homes) => homes && renderHomes(homes)).catch(() => null);
			},
		});
	});
	return host;
}

/** One pairing flow at a time; leaving the state stops its polling. */
let activePairing = null;

// ── Submit ──────────────────────────────────────────────────────────────────

async function submitConnect({ form, label, url, token, submit }) {
	const values = { label: label.value.trim(), baseUrl: url.value.trim(), token: token.value };

	if (!values.baseUrl) {
		return render(STATE.EMPTY, {
			values: { label: values.label },
			focus: 'url',
			notice: {
				tone: 'error',
				title: t('home_connect.need_url_title', 'Add your Home Assistant address.'),
				body: t('home_connect.need_url_body', 'It is the https URL you use to reach your house from outside it.'),
			},
		});
	}
	if (!values.token) {
		return render(STATE.EMPTY, {
			values: { label: values.label, baseUrl: values.baseUrl },
			focus: 'token',
			notice: {
				tone: 'error',
				title: t('home_connect.need_token_title', 'Add a long-lived access token.'),
				// TOKEN_PATH is a path inside the reader's own Home Assistant, which
				// their instance shows them in their own language. Interpolated, so
				// no translation ever rewrites a navigation path.
				body: t('home_connect.need_token_body', 'Create one in Home Assistant under {{path}}.', { path: TOKEN_PATH }),
			},
		});
	}

	// State 4: the refusal that costs no network call at all.
	const verdict = checkReachable(values.baseUrl);
	if (!verdict.ok) {
		return render(STATE.PRIVATE_HOST, {
			values: { label: values.label, baseUrl: values.baseUrl },
			focus: 'url',
			notice: verdict.notice,
		});
	}

	submit.disabled = true;
	form.setAttribute('aria-busy', 'true');

	const controller = new AbortController();
	const steps = [
		{ text: t('home_connect.step_address', 'Checking the address'), state: 'done' },
		{ text: t('home_connect.step_connect', 'Opening a connection to your home'), state: 'active' },
		{ text: t('home_connect.step_rooms', 'Reading your rooms and devices'), state: 'pending' },
		{ text: t('home_connect.step_mcp', 'Checking for the Model Context Protocol server'), state: 'pending' },
	];
	render(STATE.VERIFYING, { steps, onCancel: () => controller.abort() });

	try {
		const home = await connectHome(values, controller.signal);
		// The token has done its one job. Drop it before anything else can read it.
		values.token = '';
		const homes = await listHomes();
		renderHomes(homes && homes.length ? homes : [home]);
	} catch (err) {
		if (err?.name === 'AbortError') {
			// Aborting the fetch stops the browser waiting; it does NOT stop the
			// server, which may already have verified the house and written the row.
			// Claiming "nothing was stored" without looking would be a comfortable
			// lie about a credential, so ask before saying anything.
			values.token = '';
			const after = await listHomes().catch(() => null);
			const landed = after?.find((h) => sameHouse(h.base_url, values.baseUrl));
			if (landed) {
				return renderHomes(after, {
					tone: 'info',
					// The label is the name they gave their own house.
					title: t('home_connect.landed_anyway_title', '{{home}} connected anyway.', { home: landed.label }),
					body: t('home_connect.landed_anyway_body', 'You cancelled while it was still verifying, but your home had already answered by then, so it is connected. Disconnect it below if that is not what you wanted.'),
				});
			}
			return render(STATE.EMPTY, {
				values: { label: values.label, baseUrl: values.baseUrl },
				focus: 'url',
				notice: {
					tone: 'info',
					title: t('home_connect.cancelled_title', 'Cancelled.'),
					body: t('home_connect.cancelled_body', 'No home was connected and no token was stored. Try again whenever you are ready.'),
				},
			});
		}
		renderFailure(err, values);
	}
}

/** Maps the API error contract onto the designed failure states. */
function renderFailure(err, values) {
	const code = err?.code || 'call_failed';
	const carried = { label: values.label, baseUrl: values.baseUrl };

	// State 7: a wrong token is a specific, fixable thing. Say which thing.
	if (code === 'auth') {
		return render(STATE.AUTH_FAILED, {
			values: carried,
			focus: 'token',
			notice: {
				tone: 'error',
				title: t('home_connect.auth_failed_title', 'Home Assistant rejected that token.'),
				body: t('home_connect.auth_failed_body', 'Tokens are one per line and easy to truncate on copy. Create a fresh one under {{path}}, then paste the whole string.', { path: TOKEN_PATH }),
			},
		});
	}

	// State 8: distinguish "wrong address" from "the house is not answering".
	if (code === 'unreachable') {
		return render(STATE.UNREACHABLE, {
			values: carried,
			focus: 'url',
			notice: {
				tone: 'error',
				title: t('home_connect.unreachable_title', 'We could not reach that address.'),
				body: messageOf(err),
				bullets: [
					t('home_connect.unreachable_bullet_1', 'If the address is right, check the house is online and reachable from outside your network.'),
					t('home_connect.unreachable_bullet_2', 'If it is only reachable at home, three.ws cannot route to it. The add-on that dials out from inside your network is the path for that.'),
				],
			},
		});
	}

	if (code === 'bad_url') {
		return render(STATE.EMPTY, {
			values: carried,
			focus: 'url',
			notice: { tone: 'error', title: t('home_connect.bad_url_title', 'That address does not look right.'), body: messageOf(err) },
		});
	}

	// A plan ceiling is not a failure of the address or the token, so it must not
	// send the user back to re-check either. It is a decision with a price on it,
	// and the only useful next action is the upgrade or disconnecting a house.
	if (err?.quota) {
		return render(STATE.QUOTA_REACHED, {
			values: carried,
			notice: {
				tone: 'warn',
				title: quotaTitle(err.quota),
				body: messageOf(err),
				bullets: [
					t('home_connect.quota_bullet_1', 'Disconnect a home you no longer use and this one will connect.'),
					t('home_connect.quota_bullet_2', 'Or move to a plan that carries more homes.'),
				],
			},
			upgrade: err.quota.upgrade || '/pricing',
		});
	}

	return render(STATE.EMPTY, {
		values: carried,
		focus: 'url',
		notice: { tone: 'error', title: t('home_connect.generic_failed', 'That did not work.'), body: messageOf(err) },
	});
}

function quotaTitle(quota) {
	const limit = Number(quota?.limit);
	if (!Number.isFinite(limit)) return t('home_connect.quota_title_unknown', 'Your plan is at its limit for homes.');
	// One home and many homes are two catalog keys, not an English "s".
	return plural('home_connect.quota_title_n', limit, 'Your plan covers {{count}} home.', 'Your plan covers {{count}} homes.');
}

/**
 * Back to the connect card, optionally prefilled.
 *
 * Reconnecting a house that is already on the account carries its label and URL
 * across, because the only thing that changed is the token: making someone
 * retype an address the platform already stored is asking them to re-solve a
 * problem it knows the answer to. The token is never prefilled, because it is
 * never held anywhere this code can reach.
 */
function showConnectCard(notice, values) {
	const prefilled = values && (values.label || values.baseUrl);
	render(STATE.EMPTY, {
		...(notice ? { notice } : prefilled ? {
			notice: {
				tone: 'info',
				title: `Reconnecting ${values.label || values.baseUrl}.`,
				body: `Paste a fresh long-lived access token below. Everything else is already filled in. Create one under ${TOKEN_PATH}.`,
			},
		} : {}),
		...(prefilled ? { values: { label: values.label || '', baseUrl: values.baseUrl || '' }, focus: 'token' } : {}),
	});
}

// ── Reachability, decided here, before the network ──────────────────────────

/**
 * The whole point of running this in the browser: a LAN address is unreachable
 * by definition, and telling someone that in the same keystroke beats timing out
 * fifteen seconds later with a vaguer version of the same sentence.
 */
export function checkReachable(input) {
	const raw = String(input || '').trim();
	if (!raw) return { ok: true, short: '' };

	// Parse WITHOUT requireSecure first, then diagnose in order of usefulness.
	// The order matters more than it looks: the single most common thing a person
	// pastes is "http://192.168.1.10:8123", which is both plain http AND a LAN
	// address. Checking the scheme first answers it with "use https", which sends
	// them off to configure TLS on a machine we still would not be able to reach.
	// The LAN diagnosis is the true one and the actionable one, so it goes first.
	let parsed;
	try {
		parsed = normalizeBaseUrl(raw);
	} catch (err) {
		return {
			ok: false,
			short: t('home_connect.not_a_url_short', 'That is not a web address we can use.'),
			notice: {
				tone: 'error',
				title: t('home_connect.bad_url_title', 'That address does not look right.'),
				body: err?.message || t('home_connect.bad_url_body', 'Use the full https URL of your Home Assistant.'),
			},
		};
	}

	const host = new URL(parsed.http).hostname;
	if (isPrivateHost(host) && !parsed.loopback) {
		return {
			ok: false,
			// The host is what they typed. It is echoed back, never translated.
			short: t('home_connect.private_host_short', '{{host}} is only on your home network.', { host }),
			notice: {
				tone: 'warn',
				title: t('home_connect.private_host_title', '{{host}} is an address on your home network.', { host }),
				body: t('home_connect.private_host_body', 'three.ws runs on the public internet, so it cannot reach an address that only exists inside your house. There are two real ways round it.'),
				bullets: [
					t('home_connect.private_host_bullet_1', 'Use your remote https address instead. Home Assistant Cloud gives you one, and so does your own reverse proxy. That works today, with the token you already have.'),
					t('home_connect.private_host_bullet_2', 'Or let your house dial out to three.ws instead, with the button below. One small integration inside Home Assistant, no port forwarded, and no Home Assistant token stored here at all.'),
				],
				action: { label: t('home_connect.private_host_action', 'Connect a home that is only on my network'), onClick: () => render(STATE.PAIRING) },
			},
		};
	}

	// Past the LAN check, the same rule the server applies with
	// `requireSecure`: a page on https cannot open a plain-http connection, and
	// loopback is exempt so a local instance still works in development.
	if (!parsed.secure && !parsed.loopback) {
		return {
			ok: false,
			short: t('home_connect.insecure_short', 'A plain http address cannot be reached from this page.'),
			notice: {
				tone: 'warn',
				title: t('home_connect.insecure_title', 'That is a plain http address.'),
				body: t('home_connect.insecure_body', 'This page is served over https, and a browser will not open an unencrypted connection from it. Use the https address for your house.'),
			},
		};
	}

	return { ok: true, short: '' };
}

// ── API ─────────────────────────────────────────────────────────────────────

/** @returns {Promise<object[]|null>} null when there is no session at all. */
async function listHomes() {
	const res = await fetch('/api/home', { credentials: 'include', headers: { accept: 'application/json' } });
	if (res.status === 401) return null;
	const body = await readJson(res);
	if (!res.ok) throw apiError(body, res);
	return Array.isArray(body?.homes) ? body.homes : [];
}

async function connectHome({ label, baseUrl, token }, signal) {
	const res = await fetch('/api/home', {
		method: 'POST',
		credentials: 'include',
		signal,
		headers: { 'content-type': 'application/json', accept: 'application/json', ...(await csrfHeader()) },
		body: JSON.stringify({ label, baseUrl, token }),
	});
	const body = await readJson(res);
	if (!res.ok) throw apiError(body, res);
	return body?.home || body;
}

async function disconnect(home) {
	const res = await fetch(`/api/home/${encodeURIComponent(home.id)}`, {
		method: 'DELETE',
		credentials: 'include',
		headers: { accept: 'application/json', ...(await csrfHeader()) },
	});
	const body = await readJson(res);
	if (!res.ok) throw apiError(body, res);

	// State 10: say plainly what happened to the stored credential.
	const homes = await listHomes();
	const notice = {
		tone: 'ok',
		title: t('home_connect.disconnected_title', '{{home}} is disconnected.', { home: home.label }),
		body: t('home_connect.disconnected_body', 'The access token we held has been erased. Delete the token in Home Assistant too if you want it gone on both sides, under {{path}}.', { path: TOKEN_PATH }),
	};
	if (homes && homes.length) render(listState(homes), { homes, notice });
	else render(STATE.REVOKED, { notice });
}

async function csrfHeader() {
	if (csrfToken) {
		const header = { 'x-csrf-token': csrfToken };
		csrfToken = '';
		return header;
	}
	try {
		const res = await fetch('/api/csrf-token', { credentials: 'include' });
		if (!res.ok) return {};
		const body = await res.json();
		const token = body?.token || body?.data?.token;
		return token ? { 'x-csrf-token': token } : {};
	} catch {
		return {};
	}
}

async function readJson(res) {
	try {
		return await res.json();
	} catch {
		return null;
	}
}

/**
 * The API's coded failure, as an Error the render layer can branch on. The
 * message is whatever the server said, because the server is the only thing
 * that knows whether the token was wrong or the house was asleep.
 */
function apiError(body, res) {
	const err = new Error(body?.message || body?.error_description || body?.error || `Request failed (${res.status}).`);
	err.code = body?.code || (res.status === 404 ? 'not_found' : 'call_failed');
	err.status = res.status;
	// A plan limit answers with a `quota` block naming the dimension, the ceiling
	// and where to lift it. Carrying it here is what lets the card offer the
	// upgrade instead of a dead end.
	if (body?.quota) err.quota = body.quota;
	return err;
}

function messageOf(err) {
	return err?.message || 'Something went wrong reaching your home.';
}

// ── DOM helpers: text only, never innerHTML ─────────────────────────────────

/**
 * Everything rendered through here is `textContent`. Entity names, area names
 * and labels are strings a stranger or a compromised integration can control,
 * and the other end of this page is a physical actuator.
 */
export function el(tag, className, text) {
	const node = document.createElement(tag);
	if (className) node.className = className;
	if (text != null) node.textContent = String(text);
	return node;
}

export function clear(node) {
	while (node.firstChild) node.removeChild(node.firstChild);
}

export function noticeEl({ tone = 'info', title, body, bullets, action } = {}) {
	const wrap = el('div', `hm-notice hm-notice-${tone}`);
	wrap.setAttribute('role', tone === 'error' ? 'alert' : 'status');

	const icon = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
	icon.setAttribute('class', 'hm-notice-icon');
	icon.setAttribute('viewBox', '0 0 16 16');
	icon.setAttribute('aria-hidden', 'true');
	icon.setAttribute('fill', 'currentColor');
	const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
	path.setAttribute('d', tone === 'ok'
		? 'M8 0a8 8 0 100 16A8 8 0 008 0zm3.7 5.9l-4.2 5.3a.8.8 0 01-1.2.05L3.9 8.8a.8.8 0 111.2-1l1.8 2 3.6-4.6a.8.8 0 011.2 1z'
		: 'M8 0a8 8 0 100 16A8 8 0 008 0zm0 3.4a1 1 0 011 1v4.2a1 1 0 11-2 0V4.4a1 1 0 011-1zm0 7.3a1.1 1.1 0 110 2.2 1.1 1.1 0 010-2.2z');
	icon.append(path);

	const content = el('div');
	if (title) content.append(el('p', 'hm-notice-title', title));
	if (body) content.append(el('p', 'hm-notice-body', body));
	if (bullets?.length) {
		const ul = el('ul');
		for (const line of bullets) ul.append(el('li', '', line));
		content.append(ul);
	}
	// An explanation that names a way out should carry the way out. Telling
	// somebody their house is unreachable and then leaving them to find the fix
	// on their own is the difference between a diagnosis and a product.
	if (action?.label && typeof action.onClick === 'function') {
		const button = el('button', 'hm-btn hm-btn-primary hm-notice-action', action.label);
		button.type = 'button';
		button.addEventListener('click', action.onClick);
		content.append(button);
	}
	wrap.append(icon, content);
	return wrap;
}

function field({ id, label, hint, value, attrs = {} }) {
	const wrap = el('div', 'hm-field');
	const labelEl = el('label', 'hm-label', label);
	labelEl.htmlFor = id;
	const input = el('input', 'hm-input');
	input.id = id;
	for (const [key, val] of Object.entries(attrs)) input.setAttribute(key, val);
	input.value = value || '';
	const hintEl = el('p', 'hm-hint', hint);
	hintEl.id = `${id}-hint`;
	// The hint is where inline validation speaks, so it announces its own
	// changes. Without this a screen reader user types a LAN address, gets
	// `aria-invalid` and no reason, and has to go looking for the sentence
	// everybody else can see.
	hintEl.setAttribute('aria-live', 'polite');
	input.setAttribute('aria-describedby', hintEl.id);
	wrap.append(labelEl, input, hintEl);
	return { wrap, input, hint: hintEl, baseHint: hint };
}

/**
 * Inline, per-field validation text. Replaces the hint rather than stacking, and
 * marks itself with an attribute rather than a colour: colour alone is not a
 * message, and `[data-error]` is what both the stylesheet and a test can read.
 */
function setInlineError(f, message) {
	f.hint.textContent = message || f.baseHint;
	if (message) f.hint.dataset.error = 'true';
	else delete f.hint.dataset.error;
}

/**
 * The token field: a password input with a reveal toggle, no autocomplete, and
 * no path to storage. It is never read back from anywhere but this element.
 */
function tokenField(value) {
	const wrap = el('div', 'hm-field');
	const labelEl = el('label', 'hm-label', t('home_connect.token_label', 'Long-lived access token'));
	labelEl.htmlFor = 'hm-token';

	const shell = el('div', 'hm-secret');
	const input = el('input', 'hm-input');
	input.id = 'hm-token';
	input.type = 'password';
	input.value = value || '';
	input.setAttribute('autocomplete', 'off');
	input.setAttribute('autocapitalize', 'off');
	input.setAttribute('autocorrect', 'off');
	input.setAttribute('spellcheck', 'false');
	input.setAttribute('placeholder', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');

	const toggle = el('button', 'hm-reveal', t('home_connect.token_show', 'Show'));
	toggle.type = 'button';
	toggle.setAttribute('aria-pressed', 'false');
	toggle.addEventListener('click', () => {
		const revealed = input.type === 'text';
		input.type = revealed ? 'password' : 'text';
		toggle.textContent = revealed ? t('home_connect.token_show', 'Show') : t('home_connect.token_hide', 'Hide');
		toggle.setAttribute('aria-pressed', String(!revealed));
		input.focus();
	});

	shell.append(input, toggle);
	const hintEl = el('p', 'hm-hint', t('home_connect.token_hint', 'Sent to three.ws once, encrypted at rest, and never returned to this page or saved in this browser.'));
	hintEl.id = 'hm-token-hint';
	input.setAttribute('aria-describedby', hintEl.id);
	wrap.append(labelEl, shell, hintEl);
	return { wrap, input };
}