Add the Lit card toolchain and auto-register the Lovelace bundle

.gitignore

@@ -4,3 +4,4 @@ __pycache__/
 .venv/
 .pytest_cache/
 *.metadata.json
+frontend/node_modules/

README.md

@@ -172,6 +172,20 @@ To set up the development environment and install dependencies:
 uv sync
 ```
 
+### Frontend cards
+
+The Lovelace cards live in `frontend/` (TypeScript + Lit) and build to a
+single bundle at `custom_components/nestquest/www/nestquest-cards.js`. The
+integration registers that bundle as a Lovelace resource automatically on
+setup — do not add it by hand. Card YAML is documented in
+`design/ENTITIES-AND-SERVICES.md` §4.
+
+```bash
+cd frontend
+npm install
+npm run build
+```
+
 ### Running Tests
 
 Run the test suite with `pytest`:

custom_components/nestquest/__init__.py

@@ -28,6 +28,7 @@ from .const import (
     LOGGER,
     PLATFORMS,
 )
+from .frontend import async_register_frontend
 from .coordinator import NestQuestCoordinator
 from .db import NestQuestDatabase
 from .materialize import materialize as _materialize_run
@@ -410,11 +411,13 @@ def _deregister_services(hass: HomeAssistant) -> None:
 
 async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool:
     """Set up the NestQuest integration. YAML configuration is not used, returns True."""
+    await async_register_frontend(hass)
     return True
 
 
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up NestQuest from a config entry."""
+    await async_register_frontend(hass)
     hass.data.setdefault(DOMAIN, {})
     existing = hass.data[DOMAIN].get(entry.entry_id)
     if existing is not None:

custom_components/nestquest/frontend.py

@@ -0,0 +1,35 @@
+"""Lovelace card bundle registration for NestQuest."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from homeassistant.components.frontend import add_extra_js_url
+from homeassistant.components.http import StaticPathConfig
+from homeassistant.core import HomeAssistant
+
+WWW_DIR = Path(__file__).parent / "www"
+FRONTEND_URL_BASE = "/nestquest-static"
+BUNDLE_FILENAME = "nestquest-cards.js"
+BUNDLE_URL = f"{FRONTEND_URL_BASE}/{BUNDLE_FILENAME}"
+_REGISTERED_ATTR = "_nestquest_frontend_registered"
+
+
+async def async_register_frontend(hass: HomeAssistant) -> None:
+    """Serve the card bundle and inject it into every Lovelace page.
+
+    Idempotent across config entries: static paths and extra JS URLs are
+    process-global, so a second entry must not register them again.
+    """
+    if getattr(hass, _REGISTERED_ATTR, False):
+        return
+    await hass.http.async_register_static_paths(
+        [
+            StaticPathConfig(
+                FRONTEND_URL_BASE,
+                str(WWW_DIR),
+                cache_headers=False,
+            )
+        ]
+    )
+    add_extra_js_url(hass, BUNDLE_URL)
+    setattr(hass, _REGISTERED_ATTR, True)

custom_components/nestquest/manifest.json

@@ -5,6 +5,10 @@
     "@overseer"
   ],
   "config_flow": true,
+  "dependencies": [
+    "frontend",
+    "http"
+  ],
   "documentation": "https://github.com/talon2king/NestQuest",
   "integration_type": "hub",
   "iot_class": "local_polling",

custom_components/nestquest/www/nestquest-cards.js

@@ -0,0 +1,572 @@
+const U = globalThis, k = U.ShadowRoot && (U.ShadyCSS === void 0 || U.ShadyCSS.nativeShadow) && "adoptedStyleSheets" in Document.prototype && "replace" in CSSStyleSheet.prototype, Y = /* @__PURE__ */ Symbol(), I = /* @__PURE__ */ new WeakMap();
+let nt = class {
+  constructor(t, e, s) {
+    if (this._$cssResult$ = !0, s !== Y) throw Error("CSSResult is not constructable. Use `unsafeCSS` or `css` instead.");
+    this.cssText = t, this.t = e;
+  }
+  get styleSheet() {
+    let t = this.o;
+    const e = this.t;
+    if (k && t === void 0) {
+      const s = e !== void 0 && e.length === 1;
+      s && (t = I.get(e)), t === void 0 && ((this.o = t = new CSSStyleSheet()).replaceSync(this.cssText), s && I.set(e, t));
+    }
+    return t;
+  }
+  toString() {
+    return this.cssText;
+  }
+};
+const ot = (r) => new nt(typeof r == "string" ? r : r + "", void 0, Y), ht = (r, t) => {
+  if (k) r.adoptedStyleSheets = t.map((e) => e instanceof CSSStyleSheet ? e : e.styleSheet);
+  else for (const e of t) {
+    const s = document.createElement("style"), i = U.litNonce;
+    i !== void 0 && s.setAttribute("nonce", i), s.textContent = e.cssText, r.appendChild(s);
+  }
+}, q = k ? (r) => r : (r) => r instanceof CSSStyleSheet ? ((t) => {
+  let e = "";
+  for (const s of t.cssRules) e += s.cssText;
+  return ot(e);
+})(r) : r;
+const { is: at, defineProperty: lt, getOwnPropertyDescriptor: ct, getOwnPropertyNames: dt, getOwnPropertySymbols: pt, getPrototypeOf: ut } = Object, H = globalThis, Q = H.trustedTypes, $t = Q ? Q.emptyScript : "", _t = H.reactiveElementPolyfillSupport, b = (r, t) => r, R = { toAttribute(r, t) {
+  switch (t) {
+    case Boolean:
+      r = r ? $t : null;
+      break;
+    case Object:
+    case Array:
+      r = r == null ? r : JSON.stringify(r);
+  }
+  return r;
+}, fromAttribute(r, t) {
+  let e = r;
+  switch (t) {
+    case Boolean:
+      e = r !== null;
+      break;
+    case Number:
+      e = r === null ? null : Number(r);
+      break;
+    case Object:
+    case Array:
+      try {
+        e = JSON.parse(r);
+      } catch {
+        e = null;
+      }
+  }
+  return e;
+} }, tt = (r, t) => !at(r, t), W = { attribute: !0, type: String, converter: R, reflect: !1, useDefault: !1, hasChanged: tt };
+Symbol.metadata ??= /* @__PURE__ */ Symbol("metadata"), H.litPropertyMetadata ??= /* @__PURE__ */ new WeakMap();
+let y = class extends HTMLElement {
+  static addInitializer(t) {
+    this._$Ei(), (this.l ??= []).push(t);
+  }
+  static get observedAttributes() {
+    return this.finalize(), this._$Eh && [...this._$Eh.keys()];
+  }
+  static createProperty(t, e = W) {
+    if (e.state && (e.attribute = !1), this._$Ei(), this.prototype.hasOwnProperty(t) && ((e = Object.create(e)).wrapped = !0), this.elementProperties.set(t, e), !e.noAccessor) {
+      const s = /* @__PURE__ */ Symbol(), i = this.getPropertyDescriptor(t, s, e);
+      i !== void 0 && lt(this.prototype, t, i);
+    }
+  }
+  static getPropertyDescriptor(t, e, s) {
+    const { get: i, set: n } = ct(this.prototype, t) ?? { get() {
+      return this[e];
+    }, set(o) {
+      this[e] = o;
+    } };
+    return { get: i, set(o) {
+      const l = i?.call(this);
+      n?.call(this, o), this.requestUpdate(t, l, s);
+    }, configurable: !0, enumerable: !0 };
+  }
+  static getPropertyOptions(t) {
+    return this.elementProperties.get(t) ?? W;
+  }
+  static _$Ei() {
+    if (this.hasOwnProperty(b("elementProperties"))) return;
+    const t = ut(this);
+    t.finalize(), t.l !== void 0 && (this.l = [...t.l]), this.elementProperties = new Map(t.elementProperties);
+  }
+  static finalize() {
+    if (this.hasOwnProperty(b("finalized"))) return;
+    if (this.finalized = !0, this._$Ei(), this.hasOwnProperty(b("properties"))) {
+      const e = this.properties, s = [...dt(e), ...pt(e)];
+      for (const i of s) this.createProperty(i, e[i]);
+    }
+    const t = this[Symbol.metadata];
+    if (t !== null) {
+      const e = litPropertyMetadata.get(t);
+      if (e !== void 0) for (const [s, i] of e) this.elementProperties.set(s, i);
+    }
+    this._$Eh = /* @__PURE__ */ new Map();
+    for (const [e, s] of this.elementProperties) {
+      const i = this._$Eu(e, s);
+      i !== void 0 && this._$Eh.set(i, e);
+    }
+    this.elementStyles = this.finalizeStyles(this.styles);
+  }
+  static finalizeStyles(t) {
+    const e = [];
+    if (Array.isArray(t)) {
+      const s = new Set(t.flat(1 / 0).reverse());
+      for (const i of s) e.unshift(q(i));
+    } else t !== void 0 && e.push(q(t));
+    return e;
+  }
+  static _$Eu(t, e) {
+    const s = e.attribute;
+    return s === !1 ? void 0 : typeof s == "string" ? s : typeof t == "string" ? t.toLowerCase() : void 0;
+  }
+  constructor() {
+    super(), this._$Ep = void 0, this.isUpdatePending = !1, this.hasUpdated = !1, this._$Em = null, this._$Ev();
+  }
+  _$Ev() {
+    this._$ES = new Promise((t) => this.enableUpdating = t), this._$AL = /* @__PURE__ */ new Map(), this._$E_(), this.requestUpdate(), this.constructor.l?.forEach((t) => t(this));
+  }
+  addController(t) {
+    (this._$EO ??= /* @__PURE__ */ new Set()).add(t), this.renderRoot !== void 0 && this.isConnected && t.hostConnected?.();
+  }
+  removeController(t) {
+    this._$EO?.delete(t);
+  }
+  _$E_() {
+    const t = /* @__PURE__ */ new Map(), e = this.constructor.elementProperties;
+    for (const s of e.keys()) this.hasOwnProperty(s) && (t.set(s, this[s]), delete this[s]);
+    t.size > 0 && (this._$Ep = t);
+  }
+  createRenderRoot() {
+    const t = this.shadowRoot ?? this.attachShadow(this.constructor.shadowRootOptions);
+    return ht(t, this.constructor.elementStyles), t;
+  }
+  connectedCallback() {
+    this.renderRoot ??= this.createRenderRoot(), this.enableUpdating(!0), this._$EO?.forEach((t) => t.hostConnected?.());
+  }
+  enableUpdating(t) {
+  }
+  disconnectedCallback() {
+    this._$EO?.forEach((t) => t.hostDisconnected?.());
+  }
+  attributeChangedCallback(t, e, s) {
+    this._$AK(t, s);
+  }
+  _$ET(t, e) {
+    const s = this.constructor.elementProperties.get(t), i = this.constructor._$Eu(t, s);
+    if (i !== void 0 && s.reflect === !0) {
+      const n = (s.converter?.toAttribute !== void 0 ? s.converter : R).toAttribute(e, s.type);
+      this._$Em = t, n == null ? this.removeAttribute(i) : this.setAttribute(i, n), this._$Em = null;
+    }
+  }
+  _$AK(t, e) {
+    const s = this.constructor, i = s._$Eh.get(t);
+    if (i !== void 0 && this._$Em !== i) {
+      const n = s.getPropertyOptions(i), o = typeof n.converter == "function" ? { fromAttribute: n.converter } : n.converter?.fromAttribute !== void 0 ? n.converter : R;
+      this._$Em = i;
+      const l = o.fromAttribute(e, n.type);
+      this[i] = l ?? this._$Ej?.get(i) ?? l, this._$Em = null;
+    }
+  }
+  requestUpdate(t, e, s, i = !1, n) {
+    if (t !== void 0) {
+      const o = this.constructor;
+      if (i === !1 && (n = this[t]), s ??= o.getPropertyOptions(t), !((s.hasChanged ?? tt)(n, e) || s.useDefault && s.reflect && n === this._$Ej?.get(t) && !this.hasAttribute(o._$Eu(t, s)))) return;
+      this.C(t, e, s);
+    }
+    this.isUpdatePending === !1 && (this._$ES = this._$EP());
+  }
+  C(t, e, { useDefault: s, reflect: i, wrapped: n }, o) {
+    s && !(this._$Ej ??= /* @__PURE__ */ new Map()).has(t) && (this._$Ej.set(t, o ?? e ?? this[t]), n !== !0 || o !== void 0) || (this._$AL.has(t) || (this.hasUpdated || s || (e = void 0), this._$AL.set(t, e)), i === !0 && this._$Em !== t && (this._$Eq ??= /* @__PURE__ */ new Set()).add(t));
+  }
+  async _$EP() {
+    this.isUpdatePending = !0;
+    try {
+      await this._$ES;
+    } catch (e) {
+      Promise.reject(e);
+    }
+    const t = this.scheduleUpdate();
+    return t != null && await t, !this.isUpdatePending;
+  }
+  scheduleUpdate() {
+    return this.performUpdate();
+  }
+  performUpdate() {
+    if (!this.isUpdatePending) return;
+    if (!this.hasUpdated) {
+      if (this.renderRoot ??= this.createRenderRoot(), this._$Ep) {
+        for (const [i, n] of this._$Ep) this[i] = n;
+        this._$Ep = void 0;
+      }
+      const s = this.constructor.elementProperties;
+      if (s.size > 0) for (const [i, n] of s) {
+        const { wrapped: o } = n, l = this[i];
+        o !== !0 || this._$AL.has(i) || l === void 0 || this.C(i, void 0, n, l);
+      }
+    }
+    let t = !1;
+    const e = this._$AL;
+    try {
+      t = this.shouldUpdate(e), t ? (this.willUpdate(e), this._$EO?.forEach((s) => s.hostUpdate?.()), this.update(e)) : this._$EM();
+    } catch (s) {
+      throw t = !1, this._$EM(), s;
+    }
+    t && this._$AE(e);
+  }
+  willUpdate(t) {
+  }
+  _$AE(t) {
+    this._$EO?.forEach((e) => e.hostUpdated?.()), this.hasUpdated || (this.hasUpdated = !0, this.firstUpdated(t)), this.updated(t);
+  }
+  _$EM() {
+    this._$AL = /* @__PURE__ */ new Map(), this.isUpdatePending = !1;
+  }
+  get updateComplete() {
+    return this.getUpdateComplete();
+  }
+  getUpdateComplete() {
+    return this._$ES;
+  }
+  shouldUpdate(t) {
+    return !0;
+  }
+  update(t) {
+    this._$Eq &&= this._$Eq.forEach((e) => this._$ET(e, this[e])), this._$EM();
+  }
+  updated(t) {
+  }
+  firstUpdated(t) {
+  }
+};
+y.elementStyles = [], y.shadowRootOptions = { mode: "open" }, y[b("elementProperties")] = /* @__PURE__ */ new Map(), y[b("finalized")] = /* @__PURE__ */ new Map(), _t?.({ ReactiveElement: y }), (H.reactiveElementVersions ??= []).push("2.1.2");
+const L = globalThis, V = (r) => r, O = L.trustedTypes, K = O ? O.createPolicy("lit-html", { createHTML: (r) => r }) : void 0, et = "$lit$", _ = `lit$${Math.random().toFixed(9).slice(2)}$`, st = "?" + _, ft = `<${st}>`, g = document, w = () => g.createComment(""), C = (r) => r === null || typeof r != "object" && typeof r != "function", z = Array.isArray, At = (r) => z(r) || typeof r?.[Symbol.iterator] == "function", T = `[ 	
+\f\r]`, S = /<(?:(!--|\/[^a-zA-Z])|(\/?[a-zA-Z][^>\s]*)|(\/?$))/g, Z = /-->/g, J = />/g, f = RegExp(`>|${T}(?:([^\\s"'>=/]+)(${T}*=${T}*(?:[^ 	
+\f\r"'\`<>=]|("|')|))|$)`, "g"), F = /'/g, G = /"/g, it = /^(?:script|style|textarea|title)$/i, mt = (r) => (t, ...e) => ({ _$litType$: r, strings: t, values: e }), j = mt(1), v = /* @__PURE__ */ Symbol.for("lit-noChange"), d = /* @__PURE__ */ Symbol.for("lit-nothing"), X = /* @__PURE__ */ new WeakMap(), A = g.createTreeWalker(g, 129);
+function rt(r, t) {
+  if (!z(r) || !r.hasOwnProperty("raw")) throw Error("invalid template strings array");
+  return K !== void 0 ? K.createHTML(t) : t;
+}
+const gt = (r, t) => {
+  const e = r.length - 1, s = [];
+  let i, n = t === 2 ? "<svg>" : t === 3 ? "<math>" : "", o = S;
+  for (let l = 0; l < e; l++) {
+    const h = r[l];
+    let c, p, a = -1, u = 0;
+    for (; u < h.length && (o.lastIndex = u, p = o.exec(h), p !== null); ) u = o.lastIndex, o === S ? p[1] === "!--" ? o = Z : p[1] !== void 0 ? o = J : p[2] !== void 0 ? (it.test(p[2]) && (i = RegExp("</" + p[2], "g")), o = f) : p[3] !== void 0 && (o = f) : o === f ? p[0] === ">" ? (o = i ?? S, a = -1) : p[1] === void 0 ? a = -2 : (a = o.lastIndex - p[2].length, c = p[1], o = p[3] === void 0 ? f : p[3] === '"' ? G : F) : o === G || o === F ? o = f : o === Z || o === J ? o = S : (o = f, i = void 0);
+    const $ = o === f && r[l + 1].startsWith("/>") ? " " : "";
+    n += o === S ? h + ft : a >= 0 ? (s.push(c), h.slice(0, a) + et + h.slice(a) + _ + $) : h + _ + (a === -2 ? l : $);
+  }
+  return [rt(r, n + (r[e] || "<?>") + (t === 2 ? "</svg>" : t === 3 ? "</math>" : "")), s];
+};
+class P {
+  constructor({ strings: t, _$litType$: e }, s) {
+    let i;
+    this.parts = [];
+    let n = 0, o = 0;
+    const l = t.length - 1, h = this.parts, [c, p] = gt(t, e);
+    if (this.el = P.createElement(c, s), A.currentNode = this.el.content, e === 2 || e === 3) {
+      const a = this.el.content.firstChild;
+      a.replaceWith(...a.childNodes);
+    }
+    for (; (i = A.nextNode()) !== null && h.length < l; ) {
+      if (i.nodeType === 1) {
+        if (i.hasAttributes()) for (const a of i.getAttributeNames()) if (a.endsWith(et)) {
+          const u = p[o++], $ = i.getAttribute(a).split(_), N = /([.?@])?(.*)/.exec(u);
+          h.push({ type: 1, index: n, name: N[2], strings: $, ctor: N[1] === "." ? vt : N[1] === "?" ? Et : N[1] === "@" ? St : M }), i.removeAttribute(a);
+        } else a.startsWith(_) && (h.push({ type: 6, index: n }), i.removeAttribute(a));
+        if (it.test(i.tagName)) {
+          const a = i.textContent.split(_), u = a.length - 1;
+          if (u > 0) {
+            i.textContent = O ? O.emptyScript : "";
+            for (let $ = 0; $ < u; $++) i.append(a[$], w()), A.nextNode(), h.push({ type: 2, index: ++n });
+            i.append(a[u], w());
+          }
+        }
+      } else if (i.nodeType === 8) if (i.data === st) h.push({ type: 2, index: n });
+      else {
+        let a = -1;
+        for (; (a = i.data.indexOf(_, a + 1)) !== -1; ) h.push({ type: 7, index: n }), a += _.length - 1;
+      }
+      n++;
+    }
+  }
+  static createElement(t, e) {
+    const s = g.createElement("template");
+    return s.innerHTML = t, s;
+  }
+}
+function E(r, t, e = r, s) {
+  if (t === v) return t;
+  let i = s !== void 0 ? e._$Co?.[s] : e._$Cl;
+  const n = C(t) ? void 0 : t._$litDirective$;
+  return i?.constructor !== n && (i?._$AO?.(!1), n === void 0 ? i = void 0 : (i = new n(r), i._$AT(r, e, s)), s !== void 0 ? (e._$Co ??= [])[s] = i : e._$Cl = i), i !== void 0 && (t = E(r, i._$AS(r, t.values), i, s)), t;
+}
+class yt {
+  constructor(t, e) {
+    this._$AV = [], this._$AN = void 0, this._$AD = t, this._$AM = e;
+  }
+  get parentNode() {
+    return this._$AM.parentNode;
+  }
+  get _$AU() {
+    return this._$AM._$AU;
+  }
+  u(t) {
+    const { el: { content: e }, parts: s } = this._$AD, i = (t?.creationScope ?? g).importNode(e, !0);
+    A.currentNode = i;
+    let n = A.nextNode(), o = 0, l = 0, h = s[0];
+    for (; h !== void 0; ) {
+      if (o === h.index) {
+        let c;
+        h.type === 2 ? c = new x(n, n.nextSibling, this, t) : h.type === 1 ? c = new h.ctor(n, h.name, h.strings, this, t) : h.type === 6 && (c = new bt(n, this, t)), this._$AV.push(c), h = s[++l];
+      }
+      o !== h?.index && (n = A.nextNode(), o++);
+    }
+    return A.currentNode = g, i;
+  }
+  p(t) {
+    let e = 0;
+    for (const s of this._$AV) s !== void 0 && (s.strings !== void 0 ? (s._$AI(t, s, e), e += s.strings.length - 2) : s._$AI(t[e])), e++;
+  }
+}
+class x {
+  get _$AU() {
+    return this._$AM?._$AU ?? this._$Cv;
+  }
+  constructor(t, e, s, i) {
+    this.type = 2, this._$AH = d, this._$AN = void 0, this._$AA = t, this._$AB = e, this._$AM = s, this.options = i, this._$Cv = i?.isConnected ?? !0;
+  }
+  get parentNode() {
+    let t = this._$AA.parentNode;
+    const e = this._$AM;
+    return e !== void 0 && t?.nodeType === 11 && (t = e.parentNode), t;
+  }
+  get startNode() {
+    return this._$AA;
+  }
+  get endNode() {
+    return this._$AB;
+  }
+  _$AI(t, e = this) {
+    t = E(this, t, e), C(t) ? t === d || t == null || t === "" ? (this._$AH !== d && this._$AR(), this._$AH = d) : t !== this._$AH && t !== v && this._(t) : t._$litType$ !== void 0 ? this.$(t) : t.nodeType !== void 0 ? this.T(t) : At(t) ? this.k(t) : this._(t);
+  }
+  O(t) {
+    return this._$AA.parentNode.insertBefore(t, this._$AB);
+  }
+  T(t) {
+    this._$AH !== t && (this._$AR(), this._$AH = this.O(t));
+  }
+  _(t) {
+    this._$AH !== d && C(this._$AH) ? this._$AA.nextSibling.data = t : this.T(g.createTextNode(t)), this._$AH = t;
+  }
+  $(t) {
+    const { values: e, _$litType$: s } = t, i = typeof s == "number" ? this._$AC(t) : (s.el === void 0 && (s.el = P.createElement(rt(s.h, s.h[0]), this.options)), s);
+    if (this._$AH?._$AD === i) this._$AH.p(e);
+    else {
+      const n = new yt(i, this), o = n.u(this.options);
+      n.p(e), this.T(o), this._$AH = n;
+    }
+  }
+  _$AC(t) {
+    let e = X.get(t.strings);
+    return e === void 0 && X.set(t.strings, e = new P(t)), e;
+  }
+  k(t) {
+    z(this._$AH) || (this._$AH = [], this._$AR());
+    const e = this._$AH;
+    let s, i = 0;
+    for (const n of t) i === e.length ? e.push(s = new x(this.O(w()), this.O(w()), this, this.options)) : s = e[i], s._$AI(n), i++;
+    i < e.length && (this._$AR(s && s._$AB.nextSibling, i), e.length = i);
+  }
+  _$AR(t = this._$AA.nextSibling, e) {
+    for (this._$AP?.(!1, !0, e); t !== this._$AB; ) {
+      const s = V(t).nextSibling;
+      V(t).remove(), t = s;
+    }
+  }
+  setConnected(t) {
+    this._$AM === void 0 && (this._$Cv = t, this._$AP?.(t));
+  }
+}
+class M {
+  get tagName() {
+    return this.element.tagName;
+  }
+  get _$AU() {
+    return this._$AM._$AU;
+  }
+  constructor(t, e, s, i, n) {
+    this.type = 1, this._$AH = d, this._$AN = void 0, this.element = t, this.name = e, this._$AM = i, this.options = n, s.length > 2 || s[0] !== "" || s[1] !== "" ? (this._$AH = Array(s.length - 1).fill(new String()), this.strings = s) : this._$AH = d;
+  }
+  _$AI(t, e = this, s, i) {
+    const n = this.strings;
+    let o = !1;
+    if (n === void 0) t = E(this, t, e, 0), o = !C(t) || t !== this._$AH && t !== v, o && (this._$AH = t);
+    else {
+      const l = t;
+      let h, c;
+      for (t = n[0], h = 0; h < n.length - 1; h++) c = E(this, l[s + h], e, h), c === v && (c = this._$AH[h]), o ||= !C(c) || c !== this._$AH[h], c === d ? t = d : t !== d && (t += (c ?? "") + n[h + 1]), this._$AH[h] = c;
+    }
+    o && !i && this.j(t);
+  }
+  j(t) {
+    t === d ? this.element.removeAttribute(this.name) : this.element.setAttribute(this.name, t ?? "");
+  }
+}
+class vt extends M {
+  constructor() {
+    super(...arguments), this.type = 3;
+  }
+  j(t) {
+    this.element[this.name] = t === d ? void 0 : t;
+  }
+}
+class Et extends M {
+  constructor() {
+    super(...arguments), this.type = 4;
+  }
+  j(t) {
+    this.element.toggleAttribute(this.name, !!t && t !== d);
+  }
+}
+class St extends M {
+  constructor(t, e, s, i, n) {
+    super(t, e, s, i, n), this.type = 5;
+  }
+  _$AI(t, e = this) {
+    if ((t = E(this, t, e, 0) ?? d) === v) return;
+    const s = this._$AH, i = t === d && s !== d || t.capture !== s.capture || t.once !== s.once || t.passive !== s.passive, n = t !== d && (s === d || i);
+    i && this.element.removeEventListener(this.name, this, s), n && this.element.addEventListener(this.name, this, t), this._$AH = t;
+  }
+  handleEvent(t) {
+    typeof this._$AH == "function" ? this._$AH.call(this.options?.host ?? this.element, t) : this._$AH.handleEvent(t);
+  }
+}
+class bt {
+  constructor(t, e, s) {
+    this.element = t, this.type = 6, this._$AN = void 0, this._$AM = e, this.options = s;
+  }
+  get _$AU() {
+    return this._$AM._$AU;
+  }
+  _$AI(t) {
+    E(this, t);
+  }
+}
+const wt = L.litHtmlPolyfillSupport;
+wt?.(P, x), (L.litHtmlVersions ??= []).push("3.3.3");
+const Ct = (r, t, e) => {
+  const s = e?.renderBefore ?? t;
+  let i = s._$litPart$;
+  if (i === void 0) {
+    const n = e?.renderBefore ?? null;
+    s._$litPart$ = i = new x(t.insertBefore(w(), n), n, void 0, e ?? {});
+  }
+  return i._$AI(r), i;
+};
+const D = globalThis;
+class m extends y {
+  constructor() {
+    super(...arguments), this.renderOptions = { host: this }, this._$Do = void 0;
+  }
+  createRenderRoot() {
+    const t = super.createRenderRoot();
+    return this.renderOptions.renderBefore ??= t.firstChild, t;
+  }
+  update(t) {
+    const e = this.render();
+    this.hasUpdated || (this.renderOptions.isConnected = this.isConnected), super.update(t), this._$Do = Ct(e, this.renderRoot, this.renderOptions);
+  }
+  connectedCallback() {
+    super.connectedCallback(), this._$Do?.setConnected(!0);
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback(), this._$Do?.setConnected(!1);
+  }
+  render() {
+    return v;
+  }
+}
+m._$litElement$ = !0, m.finalized = !0, D.litElementHydrateSupport?.({ LitElement: m });
+const Pt = D.litElementPolyfillSupport;
+Pt?.({ LitElement: m });
+(D.litElementVersions ??= []).push("4.2.2");
+function B(r) {
+  window.customCards = window.customCards ?? [], window.customCards.push(r);
+}
+class xt extends m {
+  static properties = {
+    hass: { attribute: !1 },
+    _config: { state: !0 }
+  };
+  hass;
+  _config;
+  setConfig(t) {
+    if (!t || typeof t != "object")
+      throw new Error("Invalid configuration");
+    this._config = t;
+  }
+  getCardSize() {
+    return 6;
+  }
+  render() {
+    return j`<div>NestQuest Party Board</div>`;
+  }
+}
+customElements.define("nestquest-party-board-card", xt);
+B({
+  type: "nestquest-party-board-card",
+  name: "NestQuest Party Board",
+  description: "Kids' attract screen for present and away adventurers."
+});
+class Nt extends m {
+  static properties = {
+    hass: { attribute: !1 },
+    _config: { state: !0 }
+  };
+  hass;
+  _config;
+  setConfig(t) {
+    if (!t || typeof t != "object")
+      throw new Error("Invalid configuration");
+    this._config = t;
+  }
+  getCardSize() {
+    return 8;
+  }
+  render() {
+    return j`<div>NestQuest Quest Log</div>`;
+  }
+}
+customElements.define("nestquest-quest-log-card", Nt);
+B({
+  type: "nestquest-quest-log-card",
+  name: "NestQuest Quest Log",
+  description: "One child's daily quests, grouped by window."
+});
+class Ut extends m {
+  static properties = {
+    hass: { attribute: !1 },
+    _config: { state: !0 }
+  };
+  hass;
+  _config;
+  setConfig(t) {
+    if (!t || typeof t != "object")
+      throw new Error("Invalid configuration");
+    this._config = t;
+  }
+  getCardSize() {
+    return 8;
+  }
+  render() {
+    return j`<div>NestQuest Admin</div>`;
+  }
+}
+customElements.define("nestquest-admin-card", Ut);
+B({
+  type: "nestquest-admin-card",
+  name: "NestQuest Admin",
+  description: "Parent phone view for today, tasks, schedule, and history."
+});

frontend/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "nestquest-cards",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build"
+  },
+  "dependencies": {
+    "lit": "^3.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "vite": "^7.1.5"
+  }
+}

frontend/src/cards/admin.ts

@@ -0,0 +1,35 @@
+import { LitElement, html } from "lit";
+
+import { registerCustomCard, type CardConfig, type HassLike } from "../types";
+
+export class NestQuestAdminCard extends LitElement {
+  static properties = {
+    hass: { attribute: false },
+    _config: { state: true },
+  };
+
+  hass?: HassLike;
+  _config?: CardConfig;
+
+  setConfig(config: CardConfig): void {
+    if (!config || typeof config !== "object") {
+      throw new Error("Invalid configuration");
+    }
+    this._config = config;
+  }
+
+  getCardSize(): number {
+    return 8;
+  }
+
+  render() {
+    return html`<div>NestQuest Admin</div>`;
+  }
+}
+
+customElements.define("nestquest-admin-card", NestQuestAdminCard);
+registerCustomCard({
+  type: "nestquest-admin-card",
+  name: "NestQuest Admin",
+  description: "Parent phone view for today, tasks, schedule, and history.",
+});

frontend/src/cards/party-board.ts

@@ -0,0 +1,35 @@
+import { LitElement, html } from "lit";
+
+import { registerCustomCard, type CardConfig, type HassLike } from "../types";
+
+export class NestQuestPartyBoardCard extends LitElement {
+  static properties = {
+    hass: { attribute: false },
+    _config: { state: true },
+  };
+
+  hass?: HassLike;
+  _config?: CardConfig;
+
+  setConfig(config: CardConfig): void {
+    if (!config || typeof config !== "object") {
+      throw new Error("Invalid configuration");
+    }
+    this._config = config;
+  }
+
+  getCardSize(): number {
+    return 6;
+  }
+
+  render() {
+    return html`<div>NestQuest Party Board</div>`;
+  }
+}
+
+customElements.define("nestquest-party-board-card", NestQuestPartyBoardCard);
+registerCustomCard({
+  type: "nestquest-party-board-card",
+  name: "NestQuest Party Board",
+  description: "Kids' attract screen for present and away adventurers.",
+});

frontend/src/cards/quest-log.ts

@@ -0,0 +1,35 @@
+import { LitElement, html } from "lit";
+
+import { registerCustomCard, type CardConfig, type HassLike } from "../types";
+
+export class NestQuestQuestLogCard extends LitElement {
+  static properties = {
+    hass: { attribute: false },
+    _config: { state: true },
+  };
+
+  hass?: HassLike;
+  _config?: CardConfig;
+
+  setConfig(config: CardConfig): void {
+    if (!config || typeof config !== "object") {
+      throw new Error("Invalid configuration");
+    }
+    this._config = config;
+  }
+
+  getCardSize(): number {
+    return 8;
+  }
+
+  render() {
+    return html`<div>NestQuest Quest Log</div>`;
+  }
+}
+
+customElements.define("nestquest-quest-log-card", NestQuestQuestLogCard);
+registerCustomCard({
+  type: "nestquest-quest-log-card",
+  name: "NestQuest Quest Log",
+  description: "One child's daily quests, grouped by window.",
+});

frontend/src/nestquest-cards.ts

@@ -0,0 +1,3 @@
+import "./cards/party-board";
+import "./cards/quest-log";
+import "./cards/admin";

frontend/src/types.ts

@@ -0,0 +1,20 @@
+export type HassLike = Record<string, unknown>;
+
+export type CardConfig = Record<string, unknown>;
+
+export type CustomCardInfo = {
+  type: string;
+  name: string;
+  description: string;
+};
+
+declare global {
+  interface Window {
+    customCards?: CustomCardInfo[];
+  }
+}
+
+export function registerCustomCard(info: CustomCardInfo): void {
+  window.customCards = window.customCards ?? [];
+  window.customCards.push(info);
+}

frontend/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true
+  },
+  "include": ["src"]
+}

frontend/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  build: {
+    outDir: "../custom_components/nestquest/www",
+    emptyOutDir: false,
+    sourcemap: false,
+    lib: {
+      entry: "src/nestquest-cards.ts",
+      formats: ["es"],
+      fileName: () => "nestquest-cards.js",
+    },
+    rollupOptions: {
+      output: {
+        inlineDynamicImports: true,
+      },
+    },
+  },
+});

tests/conftest.py

@@ -51,6 +51,8 @@ _HA_MODULES = (
     "homeassistant.components",
     "homeassistant.components.sensor",
     "homeassistant.components.binary_sensor",
+    "homeassistant.components.http",
+    "homeassistant.components.frontend",
 )
 
 def _find_spec(name: str):
@@ -96,6 +98,8 @@ for _parent, _child in (
     ("homeassistant", "components"),
     ("homeassistant.components", "sensor"),
     ("homeassistant.components", "binary_sensor"),
+    ("homeassistant.components", "http"),
+    ("homeassistant.components", "frontend"),
 ):
     setattr(sys.modules[_parent], _child, sys.modules[f"{_parent}.{_child}"])
 
@@ -429,6 +433,28 @@ _sensor_mock.SensorStateClass = SensorStateClass
 _binary_sensor_mock = _ha_mock("homeassistant.components.binary_sensor")
 _binary_sensor_mock.BinarySensorEntity = BinarySensorEntity
 
+
+@dataclass(frozen=True)
+class StaticPathConfig:
+    """Stand-in mirroring homeassistant.components.http.StaticPathConfig."""
+
+    url_path: str
+    path: str
+    cache_headers: bool = True
+
+
+def _add_extra_js_url(hass, url, es5=False):
+    """Stand-in mirroring homeassistant.components.frontend.add_extra_js_url."""
+    urls = getattr(hass, "extra_js_urls", None)
+    if urls is None:
+        hass.extra_js_urls = []
+        urls = hass.extra_js_urls
+    urls.append(url)
+
+
+_ha_mock("homeassistant.components.http").StaticPathConfig = StaticPathConfig
+_ha_mock("homeassistant.components.frontend").add_extra_js_url = _add_extra_js_url
+
 import voluptuous as vol
 
 
@@ -549,6 +575,16 @@ def _async_track_time_change(hass, action, hour=None, minute=None, second=None):
 _ha_mock("homeassistant.helpers.event").async_track_time_change = _async_track_time_change
 
 
+class HttpRegistry:
+    """Models HA's ``hass.http`` static-path registration."""
+
+    def __init__(self):
+        self.static_paths: list[StaticPathConfig] = []
+
+    async def async_register_static_paths(self, configs):
+        self.static_paths.extend(list(configs))
+
+
 class EventBus:
     """Models HA's ``hass.bus`` event bus.
 
@@ -697,6 +733,8 @@ def make_hass() -> tuple:
     hass.time_change = TimeChangeRegistry(hass)
     hass.services = ServiceRegistry(hass)
     hass.bus = EventBus()
+    hass.http = HttpRegistry()
+    hass.extra_js_urls: list[str] = []
     # A valid IANA time zone (the day-rollover listener reads it to
     # compute "today" in HA local time).
     hass.config.time_zone = "UTC"

tests/test_frontend.py

@@ -0,0 +1,93 @@
+"""Tests for the Lovelace card toolchain and auto-registered resource."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from conftest import wire_entry_to_registry
+
+from custom_components.nestquest import async_setup, async_setup_entry
+from custom_components.nestquest.frontend import (
+    BUNDLE_FILENAME,
+    BUNDLE_URL,
+    FRONTEND_URL_BASE,
+    WWW_DIR,
+    async_register_frontend,
+)
+
+REPO_ROOT = Path(__file__).parent.parent
+FRONTEND_DIR = REPO_ROOT / "frontend"
+BUNDLE_PATH = WWW_DIR / BUNDLE_FILENAME
+CARD_TYPES = (
+    "nestquest-party-board-card",
+    "nestquest-quest-log-card",
+    "nestquest-admin-card",
+)
+
+
+def test_frontend_package_documents_vite_lit_build() -> None:
+    package = json.loads((FRONTEND_DIR / "package.json").read_text(encoding="utf-8"))
+    assert package["scripts"]["build"] == "vite build"
+    assert "lit" in package["dependencies"]
+    assert "typescript" in package["devDependencies"]
+    assert "vite" in package["devDependencies"]
+
+
+def test_card_modules_exist_as_separate_sources() -> None:
+    src = FRONTEND_DIR / "src"
+    assert (src / "nestquest-cards.ts").is_file()
+    assert (src / "cards" / "party-board.ts").is_file()
+    assert (src / "cards" / "quest-log.ts").is_file()
+    assert (src / "cards" / "admin.ts").is_file()
+    entry = (src / "nestquest-cards.ts").read_text(encoding="utf-8")
+    assert "./cards/party-board" in entry
+    assert "./cards/quest-log" in entry
+    assert "./cards/admin" in entry
+
+
+def test_card_sources_have_no_visual_editor() -> None:
+    for path in (FRONTEND_DIR / "src" / "cards").glob("*.ts"):
+        text = path.read_text(encoding="utf-8")
+        assert "getConfigElement" not in text
+        assert "setConfig" in text
+        assert "getCardSize" in text
+
+
+def test_built_bundle_contains_all_three_cards() -> None:
+    assert BUNDLE_PATH.is_file()
+    bundle = BUNDLE_PATH.read_text(encoding="utf-8")
+    for card_type in CARD_TYPES:
+        assert card_type in bundle
+
+
+async def test_setup_registers_static_path_and_extra_js(hass, make_entry) -> None:
+    entry = wire_entry_to_registry(make_entry(), hass.registry)
+    assert await async_setup_entry(hass, entry) is True
+    assert len(hass.http.static_paths) == 1
+    registered = hass.http.static_paths[0]
+    assert registered.url_path == FRONTEND_URL_BASE
+    assert registered.path == str(WWW_DIR)
+    assert hass.extra_js_urls == [BUNDLE_URL]
+
+
+async def test_async_setup_registers_frontend_without_a_config_entry(hass) -> None:
+    assert await async_setup(hass, {}) is True
+    assert hass.extra_js_urls == [BUNDLE_URL]
+    assert hass.http.static_paths[0].url_path == FRONTEND_URL_BASE
+
+
+async def test_frontend_registration_is_idempotent(hass, make_entry) -> None:
+    await async_register_frontend(hass)
+    await async_register_frontend(hass)
+    entry_a = wire_entry_to_registry(make_entry(entry_id="a"), hass.registry)
+    entry_b = wire_entry_to_registry(make_entry(entry_id="b"), hass.registry)
+    assert await async_setup_entry(hass, entry_a) is True
+    assert await async_setup_entry(hass, entry_b) is True
+    assert len(hass.http.static_paths) == 1
+    assert hass.extra_js_urls == [BUNDLE_URL]
+
+
+def test_readme_documents_npm_build() -> None:
+    readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8")
+    assert "npm run build" in readme
+    assert "nestquest-cards.js" in readme