Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

.github/copilot-instructions.md

@@ -25,7 +25,8 @@ yarn lint          # ESLint + Prettier + TypeScript + Lit
 yarn format        # Auto-fix ESLint + Prettier
 yarn lint:types    # TypeScript compiler (run WITHOUT file arguments)
 yarn test          # Vitest
-script/develop     # Development server
+yarn dev           # Dev server (app; --background/--status/--stop/--logs)
+yarn dev:serve     # Dev server with serve (-c core URL, -p port; --background/--status/--stop/--logs)
 ```
 
 > **WARNING:** Never run `tsc` or `yarn lint:types` with file arguments (e.g., `yarn lint:types src/file.ts`). When `tsc` receives file arguments, it ignores `tsconfig.json` and emits `.js` files into `src/`, polluting the codebase. Always run `yarn lint:types` without arguments. For individual file type checking, rely on IDE diagnostics. If `.js` files are accidentally generated, clean up with `git clean -fd src/`.
@@ -495,6 +496,26 @@ this.hass.localize("ui.panel.config.updates.update_available", {
 4. **Test**: `yarn test` - Add and run tests
 5. **Build**: `script/build_frontend` - Test production build
 
+### Dev servers
+
+`yarn dev` builds and watches the app, served by a running Home Assistant core (`development_repo` setting). `yarn dev:serve` also serves it locally (`-c` core URL, `-p` port, default 8124).
+
+These and the e2e dev servers below take `--background`, `--status`, `--stop`, and `--logs [--follow]`.
+
+### End-to-end (e2e) tests
+
+Each Playwright suite has a dev server on its own port. Playwright reuses a server already on the port (`reuseExistingServer` locally); otherwise it does a slow full build. The rspack watcher recompiles on save, so re-runs need no restart.
+
+Start the suite's dev server, then run the suite:
+
+- **App** (8095): `yarn test:e2e:app:dev`, then `yarn test:e2e:app`
+- **Demo** (8090): `yarn dev:demo`, then `yarn test:e2e:demo`
+- **Gallery** (8100): `yarn dev:gallery`, then `yarn test:e2e:gallery`
+
+Server reuse and `--stop` key off a `/__ha_dev_status` health check, so starting or stopping twice is harmless. The app suite uses a stripped-down harness built only for e2e; demo and gallery use their normal dev servers.
+
+Add `-g "<title>" --project=chromium` to narrow a run; `yarn test:e2e` runs all three. Run the suite directly, since piping through `tail`/`head` hides progress and truncates results.
+
 ### Gallery
 
 For Gallery-specific structure, page/demo naming, sidebar behavior, content standards, and commands, see [`gallery/AGENTS.md`](gallery/AGENTS.md).

build-scripts/dev-server.mjs

@@ -0,0 +1,678 @@
+// Manage a Home Assistant frontend dev server with an agent-friendly interface.
+//
+//   node build-scripts/dev-server.mjs --suite <suite> [mode] [extra args]
+//
+//   (no mode)          Run in the foreground.
+//   --background       Start detached, wait until it is ready, print the URL
+//                      (when it has one) and pid, then exit and leave it running.
+//   --status           Report whether the suite's dev server is running.
+//   --stop             Stop a running background dev server.
+//   --logs [--follow]  Print (or follow) the background dev server log.
+//
+// Extra args (for example -p or -c on app-serve) are forwarded to the underlying
+// script. Suites use one of two liveness models:
+//
+//   health   demo, gallery, e2e-app: a fixed port plus the /__ha_dev_status
+//            endpoint each dev server exposes (see runDevServer in
+//            build-scripts/gulp/rspack.js). The port is the source of truth and
+//            the pid is found from it; no state file.
+//   process  app (yarn dev) and app-serve (yarn dev:serve): the app watcher has
+//            no health endpoint, and plain yarn dev has no port at all, so these
+//            track a pidfile and treat the first "Build done" log line as ready.
+
+import { spawn, execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+const gulpBin = path.join(repoRoot, "node_modules", ".bin", "gulp");
+const developAndServeScript = path.join(
+  repoRoot,
+  "script",
+  "develop_and_serve"
+);
+const logDir = path.join(repoRoot, "node_modules", ".cache", "ha-dev-server");
+
+// Each suite names its yarn alias (for hints), a liveness model, and how to
+// spawn it. health suites carry a fixed port; process suites carry the log line
+// that means "ready" and, for app-serve, forward extra args to the script.
+const SUITES = {
+  "e2e-app": {
+    alias: "test:e2e:app:dev",
+    liveness: "health",
+    port: 8095,
+    spawn: { cmd: gulpBin, args: ["develop-e2e-test-app"] },
+  },
+  demo: {
+    alias: "dev:demo",
+    liveness: "health",
+    port: 8090,
+    spawn: { cmd: gulpBin, args: ["develop-demo"] },
+  },
+  gallery: {
+    alias: "dev:gallery",
+    liveness: "health",
+    port: 8100,
+    spawn: { cmd: gulpBin, args: ["develop-gallery"] },
+  },
+  app: {
+    alias: "dev",
+    liveness: "process",
+    readyLog: /Build done @/,
+    spawn: { cmd: gulpBin, args: ["develop-app"] },
+  },
+  "app-serve": {
+    alias: "dev:serve",
+    liveness: "process",
+    acceptsArgs: true,
+    readyLog: /Build done @/,
+    spawn: { cmd: developAndServeScript, args: [] },
+  },
+};
+
+// Cover a cold build on a slow machine before the server starts listening.
+// Override with HA_DEV_SERVER_TIMEOUT (seconds).
+const READY_TIMEOUT_MS =
+  Number(process.env.HA_DEV_SERVER_TIMEOUT || "180") * 1000;
+
+// Detect a coding agent from a small set of environment markers set by common
+// agent CLIs (env-only; no process-ancestry detection).
+const detectAgent = () => {
+  const env = process.env;
+  const has = (name) => Boolean(env[name]);
+  const eq = (name, value) => env[name] === value;
+  const signals = {
+    opencode: () =>
+      [
+        "OPENCODE",
+        "OPENCODE_BIN_PATH",
+        "OPENCODE_SERVER",
+        "OPENCODE_APP_INFO",
+      ].some(has),
+    "claude-code": () => has("CLAUDECODE"),
+    cursor: () => has("CURSOR_TRACE_ID"),
+    "github-copilot": () =>
+      eq("TERM_PROGRAM", "vscode") && eq("GIT_PAGER", "cat"),
+    // Convention shared by several agents (Crush, Amp, ...).
+    generic: () => has("AGENT") || has("AI_AGENT"),
+  };
+  return Object.keys(signals).find((id) => signals[id]());
+};
+
+const usage = () => {
+  const suites = Object.keys(SUITES).join("|");
+  process.stderr.write(
+    `Usage: node build-scripts/dev-server.mjs --suite <${suites}> ` +
+      `[--background | --status | --stop | --logs [--follow]]\n`
+  );
+};
+
+const parseArgs = (argv) => {
+  const args = {
+    mode: "foreground",
+    follow: false,
+    suite: undefined,
+    passthrough: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--suite":
+        args.suite = argv[++i];
+        break;
+      case "--background":
+        args.mode = "background";
+        break;
+      case "--status":
+        args.mode = "status";
+        break;
+      case "--stop":
+        args.mode = "stop";
+        break;
+      case "--logs":
+        args.mode = "logs";
+        break;
+      case "--follow":
+        args.follow = true;
+        break;
+      default:
+        // Anything unrecognised is forwarded to the underlying script.
+        args.passthrough.push(arg);
+    }
+  }
+  return args;
+};
+
+const sleep = (ms) =>
+  new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+const logFileFor = (suite) => path.join(logDir, `${suite}.log`);
+const pidFileFor = (suite) => path.join(logDir, `${suite}.pid`);
+
+const hints = (suite) => {
+  const alias = `yarn ${SUITES[suite].alias}`;
+  return (
+    `  Stop:   ${alias} --stop\n` +
+    `  Status: ${alias} --status\n` +
+    `  Logs:   ${alias} --logs\n`
+  );
+};
+
+// --- shared spawning and lifecycle ------------------------------------------
+
+// Signal the whole process group (the background server is its group leader),
+// falling back to the bare pid if that is not permitted.
+const killProcessTree = (pid, sig) => {
+  try {
+    process.kill(-pid, sig);
+  } catch {
+    try {
+      process.kill(pid, sig);
+    } catch {
+      // Already gone.
+    }
+  }
+};
+
+const urlSuffix = (port) => (port ? ` at http://localhost:${port}` : "");
+
+// Run a server in the foreground, inheriting stdio; resolve with its exit code.
+const spawnInherit = (cmd, args) =>
+  new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd: repoRoot, stdio: "inherit" });
+    child.on("exit", (code) => resolve(code ?? 0));
+  });
+
+// Spawn a detached server that writes stdout and stderr to the suite's log file.
+const spawnDetachedToLog = (suite, cmd, args) => {
+  fs.mkdirSync(logDir, { recursive: true });
+  const logFile = logFileFor(suite);
+  const fd = fs.openSync(logFile, "w");
+  const child = spawn(cmd, args, {
+    cwd: repoRoot,
+    detached: true,
+    stdio: ["ignore", fd, fd],
+  });
+  fs.closeSync(fd);
+  child.unref();
+  return { child, logFile };
+};
+
+// Poll until the server is ready, the child exits, or we time out. Prints the
+// progress dots and outcome; returns 0 when ready, 1 otherwise. onExit runs if
+// the child dies before it is ready (used to clear a stale pidfile).
+const awaitReady = async ({ suite, child, logFile, port, isReady, onExit }) => {
+  let childExited = false;
+  child.on("exit", () => {
+    childExited = true;
+  });
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  process.stdout.write(`Starting ${suite} dev server`);
+  /* eslint-disable no-await-in-loop -- poll until the server is ready */
+  while (Date.now() < deadline) {
+    if (childExited) {
+      process.stdout.write("\n");
+      process.stderr.write(
+        `Dev server (${suite}) exited before it was ready. See ${logFile}\n`
+      );
+      onExit?.();
+      return 1;
+    }
+    if (await isReady()) {
+      process.stdout.write("\n");
+      process.stdout.write(
+        `Dev server (${suite}) running${urlSuffix(port)} ` +
+          `(pid ${child.pid})\n${hints(suite)}`
+      );
+      return 0;
+    }
+    process.stdout.write(".");
+    await sleep(1000);
+  }
+  /* eslint-enable no-await-in-loop */
+  process.stdout.write("\n");
+  process.stderr.write(
+    `Dev server (${suite}) did not become ready within ${
+      READY_TIMEOUT_MS / 1000
+    }s. See ${logFile}\n`
+  );
+  return 1;
+};
+
+// Stop a running background server: SIGTERM, wait for it to go, then SIGKILL.
+// isStopped reports when it is gone; onStopped runs on success (pidfile cleanup).
+const terminate = async (suite, pid, isStopped, onStopped) => {
+  killProcessTree(pid, "SIGTERM");
+  const deadline = Date.now() + 10_000;
+  /* eslint-disable no-await-in-loop -- poll until the server is gone */
+  while (Date.now() < deadline) {
+    await sleep(300);
+    if (await isStopped()) {
+      onStopped?.();
+      process.stdout.write(`Stopped dev server (${suite}) (pid ${pid}).\n`);
+      return 0;
+    }
+  }
+  /* eslint-enable no-await-in-loop */
+  // Escalate if it is still up.
+  killProcessTree(pid, "SIGKILL");
+  await sleep(300);
+  if (!(await isStopped())) {
+    process.stderr.write(
+      `Failed to stop dev server (${suite}) (pid ${pid}). Stop it manually.\n`
+    );
+    return 1;
+  }
+  onStopped?.();
+  process.stdout.write(`Stopped dev server (${suite}) (pid ${pid}).\n`);
+  return 0;
+};
+
+// --- health liveness (port + /__ha_dev_status) ------------------------------
+
+/**
+ * Probe the health endpoint. Dev servers bind IPv4 or IPv6 localhost depending
+ * on the OS, so try each; the port is "free" only if every address refuses.
+ * @returns {Promise<{state: "ours" | "foreign" | "free", suite?: string}>}
+ */
+const PROBE_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+
+const probe = async (port, timeoutMs = 1000) => {
+  let sawResponse = false;
+  /* eslint-disable no-await-in-loop -- probe localhost addresses in order, stopping at the first that answers */
+  for (const host of PROBE_HOSTS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(`http://${host}:${port}/__ha_dev_status`, {
+        signal: controller.signal,
+      });
+      sawResponse = true;
+      if (res.ok) {
+        const body = await res.json().catch(() => null);
+        if (body && body.server === "ha-frontend-dev") {
+          return { state: "ours", suite: body.suite };
+        }
+      }
+    } catch {
+      // Try the next address.
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /* eslint-enable no-await-in-loop */
+  return sawResponse ? { state: "foreign" } : { state: "free" };
+};
+
+// Find the pid listening on a port via the first available tool (no state file).
+const pidFromPort = (port) => {
+  const attempts = [
+    [
+      "lsof",
+      ["-ti", `tcp:${port}`, "-sTCP:LISTEN"],
+      (out) => out.trim().split("\n")[0],
+    ],
+    [
+      "ss",
+      ["-ltnpH", `sport = :${port}`],
+      (out) => out.match(/pid=(\d+)/)?.[1],
+    ],
+    ["fuser", [`${port}/tcp`], (out) => out.trim().split(/\s+/)[0]],
+  ];
+  for (const [cmd, cmdArgs, extract] of attempts) {
+    try {
+      const out = execFileSync(cmd, cmdArgs, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      const pid = Number(extract(out));
+      if (Number.isInteger(pid) && pid > 0) {
+        return pid;
+      }
+    } catch {
+      // Try the next tool.
+    }
+  }
+  return undefined;
+};
+
+const runForegroundHealth = async (suite, cfg) => {
+  const { port } = cfg;
+  const status = await probe(port);
+  if (status.state === "ours" && status.suite === suite) {
+    process.stdout.write(
+      `Dev server (${suite}) is already running at http://localhost:${port}\n`
+    );
+    return 0;
+  }
+  if (status.state === "foreign") {
+    process.stderr.write(
+      `Port ${port} is in use by another process; not the ${suite} dev server.\n`
+    );
+    return 1;
+  }
+  return spawnInherit(cfg.spawn.cmd, cfg.spawn.args);
+};
+
+const runBackgroundHealth = async (suite, cfg) => {
+  const { port } = cfg;
+  const preflight = await probe(port);
+  if (preflight.state === "ours" && preflight.suite === suite) {
+    const pid = pidFromPort(port);
+    process.stdout.write(
+      `Dev server (${suite}) already running at http://localhost:${port}` +
+        `${pid ? ` (pid ${pid})` : ""}\n${hints(suite)}`
+    );
+    return 0;
+  }
+  if (preflight.state === "foreign") {
+    process.stderr.write(
+      `Port ${port} is in use by another process; not the ${suite} dev server.\n`
+    );
+    return 1;
+  }
+
+  const { child, logFile } = spawnDetachedToLog(
+    suite,
+    cfg.spawn.cmd,
+    cfg.spawn.args
+  );
+  return awaitReady({
+    suite,
+    child,
+    logFile,
+    port,
+    isReady: async () => {
+      const status = await probe(port, 1000);
+      return status.state === "ours" && status.suite === suite;
+    },
+  });
+};
+
+const runStatusHealth = async (suite, cfg) => {
+  const { port } = cfg;
+  const status = await probe(port);
+  if (status.state === "ours" && status.suite === suite) {
+    const pid = pidFromPort(port);
+    process.stdout.write(
+      `Dev server (${suite}) running at http://localhost:${port}` +
+        `${pid ? ` (pid ${pid})` : ""}\n`
+    );
+  } else if (status.state === "ours") {
+    process.stdout.write(
+      `Port ${port} is serving a different Home Assistant frontend dev server (suite ${status.suite ?? "unknown"}); not ${suite}.\n`
+    );
+  } else if (status.state === "foreign") {
+    process.stdout.write(
+      `Port ${port} is in use by another process; not the ${suite} dev server.\n`
+    );
+  } else {
+    process.stdout.write(`Dev server (${suite}) not running.\n`);
+  }
+  return 0;
+};
+
+const runStopHealth = async (suite, cfg) => {
+  const { port } = cfg;
+  const status = await probe(port);
+  if (!(status.state === "ours" && status.suite === suite)) {
+    // Idempotent: stopping something that is not running is a success.
+    process.stdout.write(`Dev server (${suite}) not running.\n`);
+    return 0;
+  }
+  const pid = pidFromPort(port);
+  if (!pid) {
+    process.stderr.write(
+      `Dev server (${suite}) is running but its pid could not be found ` +
+        `(no lsof/ss/fuser?). Stop it manually.\n`
+    );
+    return 1;
+  }
+  return terminate(
+    suite,
+    pid,
+    async () => (await probe(port, 800)).state === "free"
+  );
+};
+
+// --- process liveness (pidfile + log-readiness) -----------------------------
+
+const isAlive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but is owned by someone else.
+    return err.code === "EPERM";
+  }
+};
+
+const readPidFile = (suite) => {
+  try {
+    const data = JSON.parse(fs.readFileSync(pidFileFor(suite), "utf8"));
+    if (data && Number.isInteger(data.pid)) {
+      return data;
+    }
+  } catch {
+    // Missing or corrupt.
+  }
+  return undefined;
+};
+
+const writePidFile = (suite, data) => {
+  fs.mkdirSync(logDir, { recursive: true });
+  fs.writeFileSync(pidFileFor(suite), JSON.stringify(data));
+};
+
+const removePidFile = (suite) => {
+  try {
+    fs.rmSync(pidFileFor(suite));
+  } catch {
+    // Already gone.
+  }
+};
+
+const logIsReady = (logFile, readyLog) => {
+  try {
+    return readyLog.test(fs.readFileSync(logFile, "utf8"));
+  } catch {
+    return false;
+  }
+};
+
+// app-serve serves on 8124 by default (8123 in a devcontainer), or whatever -p
+// the caller passed. Used only to show a URL; liveness comes from the pidfile.
+const resolveServePort = (passthrough) => {
+  const i = passthrough.indexOf("-p");
+  if (i !== -1) {
+    const port = Number(passthrough[i + 1]);
+    if (Number.isInteger(port) && port > 0) {
+      return port;
+    }
+  }
+  return process.env.DEVCONTAINER ? 8123 : 8124;
+};
+
+const spawnArgs = (cfg, passthrough) => [
+  ...cfg.spawn.args,
+  ...(cfg.acceptsArgs ? passthrough : []),
+];
+
+const runForegroundProcess = async (suite, cfg, passthrough) => {
+  const existing = readPidFile(suite);
+  if (existing && isAlive(existing.pid)) {
+    process.stdout.write(
+      `Dev server (${suite}) already running in the background ` +
+        `(pid ${existing.pid}). Stop it with yarn ${cfg.alias} --stop.\n`
+    );
+    return 0;
+  }
+  if (existing) {
+    removePidFile(suite);
+  }
+  return spawnInherit(cfg.spawn.cmd, spawnArgs(cfg, passthrough));
+};
+
+const runBackgroundProcess = async (suite, cfg, passthrough) => {
+  const existing = readPidFile(suite);
+  if (existing && isAlive(existing.pid)) {
+    process.stdout.write(
+      `Dev server (${suite}) already running${urlSuffix(existing.port)} ` +
+        `(pid ${existing.pid})\n${hints(suite)}`
+    );
+    return 0;
+  }
+  if (existing) {
+    removePidFile(suite);
+  }
+
+  const { child, logFile } = spawnDetachedToLog(
+    suite,
+    cfg.spawn.cmd,
+    spawnArgs(cfg, passthrough)
+  );
+
+  const port = cfg.acceptsArgs ? resolveServePort(passthrough) : cfg.port;
+  writePidFile(suite, { pid: child.pid, port });
+
+  return awaitReady({
+    suite,
+    child,
+    logFile,
+    port,
+    isReady: () => logIsReady(logFile, cfg.readyLog),
+    onExit: () => removePidFile(suite),
+  });
+};
+
+const runStatusProcess = async (suite) => {
+  const existing = readPidFile(suite);
+  if (existing && isAlive(existing.pid)) {
+    process.stdout.write(
+      `Dev server (${suite}) running${urlSuffix(existing.port)} ` +
+        `(pid ${existing.pid})\n`
+    );
+  } else {
+    if (existing) {
+      removePidFile(suite);
+    }
+    process.stdout.write(`Dev server (${suite}) not running.\n`);
+  }
+  return 0;
+};
+
+const runStopProcess = async (suite) => {
+  const existing = readPidFile(suite);
+  if (!existing || !isAlive(existing.pid)) {
+    // Idempotent: stopping something that is not running is a success.
+    if (existing) {
+      removePidFile(suite);
+    }
+    process.stdout.write(`Dev server (${suite}) not running.\n`);
+    return 0;
+  }
+  const { pid } = existing;
+  return terminate(
+    suite,
+    pid,
+    () => !isAlive(pid),
+    () => removePidFile(suite)
+  );
+};
+
+// --- shared -----------------------------------------------------------------
+
+const runLogs = (suite, follow) => {
+  const logFile = logFileFor(suite);
+  if (!fs.existsSync(logFile)) {
+    process.stdout.write(
+      `No log for the ${suite} dev server yet (${logFile}).\n`
+    );
+    return Promise.resolve(0);
+  }
+  if (!follow) {
+    process.stdout.write(fs.readFileSync(logFile, "utf8"));
+    return Promise.resolve(0);
+  }
+  return new Promise((resolve) => {
+    const tail = spawn("tail", ["-f", logFile], { stdio: "inherit" });
+    tail.on("error", () => {
+      // No tail available; fall back to a one-shot dump.
+      process.stdout.write(fs.readFileSync(logFile, "utf8"));
+      resolve(0);
+    });
+    tail.on("exit", (code) => resolve(code ?? 0));
+  });
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv.slice(2));
+  const cfg = SUITES[args.suite];
+  if (!cfg) {
+    usage();
+    return 1;
+  }
+  if (args.passthrough.length && !cfg.acceptsArgs) {
+    process.stderr.write(
+      `Ignoring unexpected arguments: ${args.passthrough.join(" ")}\n`
+    );
+  }
+
+  // A plain dev:<suite> under a coding agent backgrounds itself; explicit modes
+  // are untouched.
+  let { mode } = args;
+  if (
+    mode === "foreground" &&
+    !["0", "false"].includes(process.env.HA_DEV_BACKGROUND)
+  ) {
+    const agent = detectAgent();
+    if (agent) {
+      process.stdout.write(
+        `Detected coding agent (${agent}); starting in the background. ` +
+          `Set HA_DEV_BACKGROUND=0 to force foreground.\n`
+      );
+      mode = "background";
+    }
+  }
+
+  const health = cfg.liveness === "health";
+  switch (mode) {
+    case "background":
+      return health
+        ? runBackgroundHealth(args.suite, cfg)
+        : runBackgroundProcess(args.suite, cfg, args.passthrough);
+    case "status":
+      return health
+        ? runStatusHealth(args.suite, cfg)
+        : runStatusProcess(args.suite);
+    case "stop":
+      return health
+        ? runStopHealth(args.suite, cfg)
+        : runStopProcess(args.suite);
+    case "logs":
+      return runLogs(args.suite, args.follow);
+    default:
+      return health
+        ? runForegroundHealth(args.suite, cfg)
+        : runForegroundProcess(args.suite, cfg, args.passthrough);
+  }
+};
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`${err?.stack || err}\n`);
+    process.exitCode = 1;
+  }
+);

build-scripts/gulp/rspack.js

@@ -37,6 +37,7 @@ const isWsl =
  *   listenHost?: string,
  *   open?: boolean,
  *   logUrlAfterFirstBuild?: boolean,
+ *   suite?: string,
  * }}
  */
 const runDevServer = async ({
@@ -47,6 +48,7 @@ const runDevServer = async ({
   open = true,
   logUrlAfterFirstBuild = false,
   proxy = undefined,
+  suite = undefined,
 }) => {
   if (listenHost === undefined) {
     // For dev container, we need to listen on all hosts
@@ -81,6 +83,19 @@ const runDevServer = async ({
             !error?.message?.includes("ResizeObserver loop"),
         },
       },
+      setupMiddlewares: (middlewares) => {
+        // Status endpoint so the dev-server manager can confirm this is our
+        // server for the expected suite. Unshifted to beat the static handler.
+        middlewares.unshift({
+          name: "ha-dev-status",
+          path: "/__ha_dev_status",
+          middleware: (_req, res) => {
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ server: "ha-frontend-dev", suite, port }));
+          },
+        });
+        return middlewares;
+      },
       proxy,
     },
     compiler
@@ -152,6 +167,8 @@ gulp.task("rspack-dev-server-demo", () =>
     ),
     contentBase: paths.demo_output_root,
     port: 8090,
+    open: false,
+    suite: "demo",
   })
 );
 
@@ -173,6 +190,7 @@ gulp.task("rspack-dev-server-cast", () =>
     port: 8080,
     // Accessible from the network, because that's how Cast hits it.
     listenHost: "0.0.0.0",
+    suite: "cast",
   })
 );
 
@@ -194,6 +212,7 @@ gulp.task("rspack-dev-server-gallery", () =>
     listenHost: "0.0.0.0",
     open: false,
     logUrlAfterFirstBuild: true,
+    suite: "gallery",
   })
 );
 
@@ -241,6 +260,7 @@ gulp.task("rspack-dev-server-e2e-test-app", () =>
     contentBase: paths.e2eTestApp_output_root,
     port: 8095,
     open: false,
+    suite: "e2e-app",
   })
 );
 

demo/script/develop_demo

@@ -1,9 +1,10 @@
 #!/bin/sh
-# Develop the demo
+# Develop the demo. Pass --background/--status/--stop/--logs to manage a
+# detached instance (see build-scripts/dev-server.mjs).
 
 # Stop on errors
 set -e
 
 cd "$(dirname "$0")/../.."
 
-./node_modules/.bin/gulp develop-demo
+exec node build-scripts/dev-server.mjs --suite demo "$@"

gallery/script/develop_gallery

@@ -1,9 +1,10 @@
 #!/bin/sh
-# Run the gallery
+# Run the gallery. Pass --background/--status/--stop/--logs to manage a
+# detached instance (see build-scripts/dev-server.mjs).
 
 # Stop on errors
 set -e
 
 cd "$(dirname "$0")/../.."
 
-./node_modules/.bin/gulp develop-gallery
+exec node build-scripts/dev-server.mjs --suite gallery "$@"

package.json

@@ -24,6 +24,10 @@
     "test:bench": "vitest bench --run --config test/vitest.bench.config.ts",
     "test:coverage": "vitest run --config test/vitest.config.ts --coverage",
     "check-bundlesize": "node build-scripts/check-bundle-size.cjs",
+    "dev": "node build-scripts/dev-server.mjs --suite app",
+    "dev:serve": "node build-scripts/dev-server.mjs --suite app-serve",
+    "dev:demo": "demo/script/develop_demo",
+    "dev:gallery": "gallery/script/develop_gallery",
     "test:e2e": "node test/e2e/run-suites.mjs demo app gallery",
     "test:e2e:show-report": "yarn playwright show-report test/e2e/reports/combined",
     "test:e2e:demo": "playwright test --config test/e2e/playwright.demo.config.ts",
@@ -102,7 +106,7 @@
     "gulp-zopfli-green": "7.0.0",
     "hls.js": "1.6.16",
     "home-assistant-js-websocket": "9.6.0",
-    "idb-keyval": "6.2.5",
+    "idb-keyval": "6.2.6",
     "intl-messageformat": "11.2.9",
     "js-yaml": "5.2.0",
     "leaflet": "1.9.4",
@@ -147,7 +151,7 @@
     "@octokit/plugin-retry": "8.1.0",
     "@octokit/rest": "22.0.1",
     "@playwright/test": "1.61.1",
-    "@rsdoctor/rspack-plugin": "1.5.16",
+    "@rsdoctor/rspack-plugin": "1.5.17",
     "@rspack/core": "2.1.1",
     "@rspack/dev-server": "2.1.0",
     "@types/babel__plugin-transform-runtime": "7.9.5",

src/components/ha-service-control.ts

@@ -525,10 +525,10 @@ export class HaServiceControl extends LitElement {
                 this._manifest
                   ? html` <a
                       href=${
-                        this._manifest.is_built_in
+                        this._manifest.is_built_in && this._value?.action
                           ? documentationUrl(
                               this.hass,
-                              `/integrations/${this._manifest.domain}`
+                              `/actions/${this._value.action}`
                             )
                           : this._manifest.documentation
                       }

src/panels/config/automation/condition/types/ha-automation-condition-platform.ts

@@ -195,7 +195,7 @@ export class HaPlatformCondition extends LitElement {
                   this._manifest.is_built_in
                     ? documentationUrl(
                         this.hass,
-                        `/integrations/${this._manifest.domain}`
+                        `/conditions/${this.condition.condition}`
                       )
                     : this._manifest.documentation
                 }

src/panels/config/automation/trigger/types/ha-automation-trigger-platform.ts

@@ -190,7 +190,7 @@ export class HaPlatformTrigger extends LitElement {
                   this._manifest.is_built_in
                     ? documentationUrl(
                         this.hass,
-                        `/integrations/${this._manifest.domain}`
+                        `/triggers/${this.trigger.trigger}`
                       )
                     : this._manifest.documentation
                 }

src/panels/config/developer-tools/template/developer-tools-template.ts

@@ -4,6 +4,7 @@ import { css, html, LitElement, nothing } from "lit";
 import { customElement, property, query, state } from "lit/decorators";
 import { classMap } from "lit/directives/class-map";
 import type { HASSDomEvent } from "../../../../common/dom/fire_event";
+import type { LocalizeKeys } from "../../../../common/translations/localize";
 import { debounce } from "../../../../common/util/debounce";
 import "../../../../components/ha-alert";
 import "../../../../components/ha-button";
@@ -40,6 +41,15 @@ For loop example getting entity values in the weather domain:
   {{ state.name | lower }} is {{state.state_with_unit}}
 {%- endfor %}.`;
 
+// key resolves the label/description translation keys; path is passed through
+// documentationUrl().
+const TEMPLATE_DOCS_LINKS: { key: string; path: string }[] = [
+  { key: "docs_introduction", path: "/docs/templating/introduction/" },
+  { key: "docs_states", path: "/docs/templating/states/" },
+  { key: "docs_debugging", path: "/docs/templating/debugging/" },
+  { key: "docs_functions", path: "/template-functions/" },
+];
+
 @customElement("developer-tools-template")
 class HaPanelDevTemplate extends LitElement {
   @property({ attribute: false }) public hass!: HomeAssistant;
@@ -120,31 +130,36 @@ class HaPanelDevTemplate extends LitElement {
                 "ui.panel.config.developer-tools.tabs.templates.description"
               )}
             </p>
+            <p>
+              ${this.hass.localize(
+                "ui.panel.config.developer-tools.tabs.templates.engine_info"
+              )}
+            </p>
+            <h3>
+              ${this.hass.localize(
+                "ui.panel.config.developer-tools.tabs.templates.learn_more"
+              )}
+            </h3>
             <ul>
-              <li>
-                <a
-                  href="https://jinja.palletsprojects.com/en/latest/templates/"
-                  target="_blank"
-                  rel="noreferrer"
-                  >${this.hass.localize(
-                    "ui.panel.config.developer-tools.tabs.templates.jinja_documentation"
-                  )}
-                </a>
-              </li>
-              <li>
-                <a
-                  href=${documentationUrl(
-                    this.hass,
-                    "/docs/configuration/templating/"
-                  )}
-                  target="_blank"
-                  rel="noreferrer"
-                >
-                  ${this.hass.localize(
-                    "ui.panel.config.developer-tools.tabs.templates.template_extensions"
-                  )}</a
-                >
-              </li>
+              ${TEMPLATE_DOCS_LINKS.map(
+                (link) => html`
+                  <li>
+                    <a
+                      href=${documentationUrl(this.hass, link.path)}
+                      target="_blank"
+                      rel="noreferrer"
+                      >${this.hass.localize(
+                        `ui.panel.config.developer-tools.tabs.templates.${link.key}` as LocalizeKeys
+                      )}</a
+                    >
+                    <span class="link-description"
+                      >${this.hass.localize(
+                        `ui.panel.config.developer-tools.tabs.templates.${link.key}_description` as LocalizeKeys
+                      )}</span
+                    >
+                  </li>
+                `
+              )}
             </ul>
           </div>
         </ha-expansion-panel>
@@ -441,6 +456,17 @@ ${
           margin-block-start: var(--ha-space-1);
           margin-block-end: var(--ha-space-1);
         }
+        .description > h3 {
+          font-size: var(--ha-font-size-m);
+          font-weight: var(--ha-font-weight-medium);
+          margin-block-end: var(--ha-space-1);
+        }
+        .description li {
+          margin-block-end: var(--ha-space-1);
+        }
+        .description .link-description {
+          color: var(--secondary-text-color);
+        }
 
         .render-pane .card-content {
           user-select: text;

src/translations/en.json

@@ -3904,7 +3904,9 @@
             },
             "templates": {
               "title": "Template",
-              "description": "Templates are rendered using the Jinja2 template engine with some Home Assistant specific extensions.",
+              "description": "Templates let you generate dynamic content from your Home Assistant data, such as a notification that lists which lights are on, or a sensor whose value is calculated from several other entities.",
+              "engine_info": "Home Assistant uses the Jinja templating engine, extended with functions for working with your entities, areas, devices, and more. Write a template in the editor below and its result updates live as your states change.",
+              "learn_more": "Learn more",
               "about": "About templates",
               "editor": "Template editor",
               "result": "Result",
@@ -3912,8 +3914,14 @@
               "confirm_reset": "Do you want to reset your current template back to the demo template?",
               "confirm_clear": "Do you want to clear your current template?",
               "result_type": "Result type",
-              "jinja_documentation": "Jinja2 template documentation",
-              "template_extensions": "Home Assistant template extensions",
+              "docs_introduction": "Introduction to templating",
+              "docs_introduction_description": "Start here for a step-by-step guide.",
+              "docs_states": "Working with states",
+              "docs_states_description": "Read entity states and attributes in templates.",
+              "docs_debugging": "Debugging templates",
+              "docs_debugging_description": "Find and fix problems in your templates.",
+              "docs_functions": "Template functions reference",
+              "docs_functions_description": "Search every available function, filter, and test.",
               "unknown_error_template": "Unknown error rendering template",
               "time": "This template updates at the start of each minute.",
               "all_listeners": "This template listens for all state changed events.",

test/e2e/app/script/develop_app

@@ -1,9 +1,10 @@
 #!/bin/sh
-# Develop the e2e test app
+# Develop the e2e test app. Pass --background/--status/--stop/--logs to manage a
+# detached instance (see build-scripts/dev-server.mjs).
 
 # Stop on errors
 set -e
 
 cd "$(dirname "$0")/../../../.."
 
-./node_modules/.bin/gulp develop-e2e-test-app
+exec node build-scripts/dev-server.mjs --suite e2e-app "$@"

yarn.lock

@@ -4618,22 +4618,22 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@rsdoctor/client@npm:1.5.16":
-  version: 1.5.16
-  resolution: "@rsdoctor/client@npm:1.5.16"
-  checksum: 10/dcda4e8034a296090b073102423050764e636f9801f2e5a5904e1f2744b1fe26d5f8202aed7a785c9fc809044e1aef5c4b6a16b63974caec79d1b5996ec35d34
+"@rsdoctor/client@npm:1.5.17":
+  version: 1.5.17
+  resolution: "@rsdoctor/client@npm:1.5.17"
+  checksum: 10/0eb788455390a1b41aa31d982d93ceab3dd30671776e40e8a4ea3256b4713f6441066e079ff9a14413825e21d547b9b7d4ba52059f8995644e26724ff07bbf56
   languageName: node
   linkType: hard
 
-"@rsdoctor/core@npm:1.5.16":
-  version: 1.5.16
-  resolution: "@rsdoctor/core@npm:1.5.16"
+"@rsdoctor/core@npm:1.5.17":
+  version: 1.5.17
+  resolution: "@rsdoctor/core@npm:1.5.17"
   dependencies:
     "@rsbuild/plugin-check-syntax": "npm:^1.6.1"
-    "@rsdoctor/graph": "npm:1.5.16"
-    "@rsdoctor/sdk": "npm:1.5.16"
-    "@rsdoctor/types": "npm:1.5.16"
-    "@rsdoctor/utils": "npm:1.5.16"
+    "@rsdoctor/graph": "npm:1.5.17"
+    "@rsdoctor/sdk": "npm:1.5.17"
+    "@rsdoctor/types": "npm:1.5.17"
+    "@rsdoctor/utils": "npm:1.5.17"
     "@rspack/resolver": "npm:^0.2.8"
     browserslist-load-config: "npm:^1.0.2"
     es-toolkit: "npm:^1.47.0"
@@ -4641,60 +4641,60 @@ __metadata:
     fs-extra: "npm:^11.1.1"
     semver: "npm:^7.7.4"
     source-map: "npm:^0.7.6"
-  checksum: 10/be7b03b5a5a8a9be47f94159469c35488f98046c99e2ccd7daed325c3dd2a8b21c654c12ac6d40c2775546efade373f429f630e8905cc17a5c9151978a0caaf9
+  checksum: 10/a797d5243d1d3f758d8b38cea1a3195345525c3158c4061f5e78d875fe2001198c8967587153059eb7c5ff764f27b4685ce13fd55a27dccdcfe7cd8061fb30c9
   languageName: node
   linkType: hard
 
-"@rsdoctor/graph@npm:1.5.16":
-  version: 1.5.16
-  resolution: "@rsdoctor/graph@npm:1.5.16"
+"@rsdoctor/graph@npm:1.5.17":
+  version: 1.5.17
+  resolution: "@rsdoctor/graph@npm:1.5.17"
   dependencies:
-    "@rsdoctor/types": "npm:1.5.16"
-    "@rsdoctor/utils": "npm:1.5.16"
+    "@rsdoctor/types": "npm:1.5.17"
+    "@rsdoctor/utils": "npm:1.5.17"
     es-toolkit: "npm:^1.47.0"
     path-browserify: "npm:1.0.1"
     source-map: "npm:^0.7.6"
-  checksum: 10/949e3a2cc48ccbb2d554becb2270c4df4b4fc8a6e10bd55bf9dc4d5f9a5fb2823c3e11a30dce890beaaa1b0ab0039bba1554ad0e7ddc5e2ea47641222d454633
+  checksum: 10/e58ed532ea8cc743e45dd66b678e1da3d48939fe711ebfade47834ffc581be6089d611d18c97c3e12010e2c609049cb325d07021a5dc51ef651314f8fe9f5741
   languageName: node
   linkType: hard
 
-"@rsdoctor/rspack-plugin@npm:1.5.16":
-  version: 1.5.16
-  resolution: "@rsdoctor/rspack-plugin@npm:1.5.16"
+"@rsdoctor/rspack-plugin@npm:1.5.17":
+  version: 1.5.17
+  resolution: "@rsdoctor/rspack-plugin@npm:1.5.17"
   dependencies:
-    "@rsdoctor/core": "npm:1.5.16"
-    "@rsdoctor/graph": "npm:1.5.16"
-    "@rsdoctor/sdk": "npm:1.5.16"
-    "@rsdoctor/types": "npm:1.5.16"
-    "@rsdoctor/utils": "npm:1.5.16"
+    "@rsdoctor/core": "npm:1.5.17"
+    "@rsdoctor/graph": "npm:1.5.17"
+    "@rsdoctor/sdk": "npm:1.5.17"
+    "@rsdoctor/types": "npm:1.5.17"
+    "@rsdoctor/utils": "npm:1.5.17"
   peerDependencies:
     "@rspack/core": "*"
   peerDependenciesMeta:
     "@rspack/core":
       optional: true
-  checksum: 10/2bebf2b8dfc5ffde77b46b45fedc7d5d9b96f4fe3e5e1b3762bff5de6f278d9288fe6c361fa1df5bb17926a45ae3c6038e165d4f1f5e867724df0a530590b36a
+  checksum: 10/336bd813010a7c164770033ae5a30644bf165ce0dff250b9160c7c003401c214bfd96e528c5941c09834bb21949a4815c46ecae0ca4d9200b2b946b9c3164f8a
   languageName: node
   linkType: hard
 
-"@rsdoctor/sdk@npm:1.5.16":
-  version: 1.5.16
-  resolution: "@rsdoctor/sdk@npm:1.5.16"
+"@rsdoctor/sdk@npm:1.5.17":
+  version: 1.5.17
+  resolution: "@rsdoctor/sdk@npm:1.5.17"
   dependencies:
-    "@rsdoctor/client": "npm:1.5.16"
-    "@rsdoctor/graph": "npm:1.5.16"
-    "@rsdoctor/types": "npm:1.5.16"
-    "@rsdoctor/utils": "npm:1.5.16"
+    "@rsdoctor/client": "npm:1.5.17"
+    "@rsdoctor/graph": "npm:1.5.17"
+    "@rsdoctor/types": "npm:1.5.17"
+    "@rsdoctor/utils": "npm:1.5.17"
     launch-editor: "npm:^2.13.2"
     safer-buffer: "npm:2.1.2"
     socket.io: "npm:4.8.1"
     tapable: "npm:2.3.3"
-  checksum: 10/8a845468e13c66b93f9784c7887f7040b1df24f43e9304b50c3a7258c6b172c2bc3ca5f6e5e9d15801d1634e3e48f6bc78115a7a0242890548d111ae512caf7d
+  checksum: 10/d8a146a43726d61a9d7d2cfca7e2cd48c42a7ba28c9d280353f986f1647c0a33f05ec68a45af4f22104df8a8dae7dc14d621e56a15f11c3967d78c21216be234
   languageName: node
   linkType: hard
 
-"@rsdoctor/types@npm:1.5.16":
-  version: 1.5.16
-  resolution: "@rsdoctor/types@npm:1.5.16"
+"@rsdoctor/types@npm:1.5.17":
+  version: 1.5.17
+  resolution: "@rsdoctor/types@npm:1.5.17"
   dependencies:
     "@types/connect": "npm:3.4.38"
     "@types/estree": "npm:1.0.5"
@@ -4708,16 +4708,16 @@ __metadata:
       optional: true
     webpack:
       optional: true
-  checksum: 10/f470a7047474669bd466c9cee15b5ef3e4b854d4347e3dd4f251f1d1f92bd9b7b5e6863349f5d3550485c3484497a1e8be71cefc56e883c81f8a734960d1fc5e
+  checksum: 10/4767825ae55498e25d1dfbecc0aebe2685b67701dae004617f4d95a68b85f19f29afe75f72b8efeab4fe49185bb9a3c85dcfce8f99852c49d4ee37a4f6b7d888
   languageName: node
   linkType: hard
 
-"@rsdoctor/utils@npm:1.5.16":
-  version: 1.5.16
-  resolution: "@rsdoctor/utils@npm:1.5.16"
+"@rsdoctor/utils@npm:1.5.17":
+  version: 1.5.17
+  resolution: "@rsdoctor/utils@npm:1.5.17"
   dependencies:
     "@babel/code-frame": "npm:7.26.2"
-    "@rsdoctor/types": "npm:1.5.16"
+    "@rsdoctor/types": "npm:1.5.17"
     "@types/estree": "npm:1.0.5"
     acorn: "npm:^8.10.0"
     acorn-import-attributes: "npm:^1.9.5"
@@ -4731,7 +4731,7 @@ __metadata:
     picocolors: "npm:^1.1.1"
     rslog: "npm:^2.1.2"
     strip-ansi: "npm:^6.0.1"
-  checksum: 10/d73062cc01f4e2def276d6515f2810f54bfd7f819f1d3a00dd884621f9c008eda4b31ae6e6d96efaec81d1bbad98f0f49cb77e14a028d5f53c97aca84b6b07d4
+  checksum: 10/7c9b4a3824de61f6254df50f80c5efe53df662f30cb07047afa956a9bc3917dc71bf0aa73c8edde7f73f9577a9cb051e1a81caaffa118db414a4b655223fe92a
   languageName: node
   linkType: hard
 
@@ -9771,7 +9771,7 @@ __metadata:
     "@octokit/rest": "npm:22.0.1"
     "@playwright/test": "npm:1.61.1"
     "@replit/codemirror-indentation-markers": "npm:6.5.3"
-    "@rsdoctor/rspack-plugin": "npm:1.5.16"
+    "@rsdoctor/rspack-plugin": "npm:1.5.17"
     "@rspack/core": "npm:2.1.1"
     "@rspack/dev-server": "npm:2.1.0"
     "@swc/helpers": "npm:0.5.23"
@@ -9837,7 +9837,7 @@ __metadata:
     home-assistant-js-websocket: "npm:9.6.0"
     html-minifier-terser: "npm:7.2.0"
     husky: "npm:9.1.7"
-    idb-keyval: "npm:6.2.5"
+    idb-keyval: "npm:6.2.6"
     intl-messageformat: "npm:11.2.9"
     js-yaml: "npm:5.2.0"
     jsdom: "npm:29.1.1"
@@ -10056,10 +10056,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"idb-keyval@npm:6.2.5":
-  version: 6.2.5
-  resolution: "idb-keyval@npm:6.2.5"
-  checksum: 10/ac645882b3258ff07347d085baab91b871bac7be4f46ff8e20a7c036c2df35d3f695a30050009f27237b99045203568f2a842a35295a48f9b815959ee51a347e
+"idb-keyval@npm:6.2.6":
+  version: 6.2.6
+  resolution: "idb-keyval@npm:6.2.6"
+  checksum: 10/8d0f8b9bd5eead685731a900510095dbc58936968739755bfd1de1c69a710daa5eb2b5cf185d0a7c7e9ce1daf4544fa5f58a2c7a37258a6826dd40f9e2614245
   languageName: node
   linkType: hard