@rahmantech/litedesign 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,2088 @@
+#!/usr/bin/env node
+
+// packages/cli/src/commands/doctor.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { readFile as readFile3 } from "node:fs/promises";
+import path2 from "node:path";
+
+// packages/cli/src/config.ts
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+// packages/cli/src/paths.ts
+import os from "node:os";
+import path from "node:path";
+var HOME = path.join(os.homedir(), ".litedesign");
+var EXT_DIR = path.join(HOME, "extension");
+var CONFIG = path.join(HOME, "config.json");
+var DEFAULT_PORT = 8787;
+function wsState(port) {
+  return path.join(HOME, `ws-${port}.json`);
+}
+var BUNDLED_EXTENSION = new URL("./extension/", import.meta.url);
+
+// packages/cli/src/config.ts
+var MODES = ["auto", "playwright", "extension"];
+var FALLBACK = { port: DEFAULT_PORT, mode: "auto" };
+async function readConfig() {
+  if (!existsSync(CONFIG)) return { ...FALLBACK };
+  try {
+    const raw = JSON.parse(await readFile(CONFIG, "utf8"));
+    return {
+      port: isPort(raw.port) ? raw.port : FALLBACK.port,
+      mode: typeof raw.mode === "string" && isMode(raw.mode) ? raw.mode : FALLBACK.mode
+    };
+  } catch {
+    return { ...FALLBACK };
+  }
+}
+function isPort(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value < 65536;
+}
+function isMode(value) {
+  return MODES.includes(value);
+}
+
+// packages/cli/src/version.ts
+var VERSION = "0.1.0";
+
+// packages/cli/src/ws.ts
+import { spawn } from "node:child_process";
+import { existsSync as existsSync2 } from "node:fs";
+import { readFile as readFile2, rm, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
+
+// packages/cli/src/hub.ts
+import { randomUUID } from "node:crypto";
+import { WebSocket, WebSocketServer } from "ws";
+
+// packages/cli/src/mcp/handoff.ts
+function handoffMessage(url) {
+  return [
+    `Open ${url} in Chrome and keep it in the active tab.`,
+    "",
+    "The extension attaches by itself, so there is nothing to click.",
+    "If nothing connects:",
+    "- make sure the extension is loaded unpacked at chrome://extensions",
+    "- make sure Chrome is running",
+    "",
+    "I am waiting for that page to connect."
+  ].join("\n");
+}
+function mismatchMessage(expected, actual) {
+  return [
+    `The active tab is ${actual}, but I am waiting for ${expected}.`,
+    "",
+    `Switch to ${expected} and call await_page,`,
+    "or call inspect again with the URL you actually have open."
+  ].join("\n");
+}
+
+// packages/cli/src/mcp/errors.ts
+var ToolError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ToolError";
+  }
+};
+var AwaitingUserError = class extends ToolError {
+  url;
+  constructor(url) {
+    super(`the page ${url} is not connected. Open it and keep it in the active tab.`);
+    this.name = "AwaitingUserError";
+    this.url = url;
+  }
+};
+var MismatchError = class extends ToolError {
+  expected;
+  actual;
+  constructor(expected, actual) {
+    super(mismatchMessage(expected, actual));
+    this.name = "MismatchError";
+    this.expected = expected;
+    this.actual = actual;
+  }
+};
+
+// packages/cli/src/hub.ts
+var PING_INTERVAL = 2e4;
+var Hub = class _Hub {
+  #server;
+  #clients = /* @__PURE__ */ new Map();
+  #socketTab = /* @__PURE__ */ new Map();
+  #sockets = /* @__PURE__ */ new Set();
+  #controllers = /* @__PURE__ */ new Set();
+  #pending = /* @__PURE__ */ new Map();
+  #waiters = /* @__PURE__ */ new Set();
+  #ping;
+  #closed = false;
+  constructor(server) {
+    this.#server = server;
+  }
+  static start(port) {
+    return new Promise((resolve, reject) => {
+      const server = new WebSocketServer({ host: "127.0.0.1", port });
+      const hub = new _Hub(server);
+      const onError = (error) => {
+        server.off("listening", onListening);
+        reject(error);
+      };
+      const onListening = () => {
+        server.off("error", onError);
+        server.on("connection", (socket) => hub.#accept(socket));
+        hub.#ping = setInterval(() => hub.#broadcastPing(), PING_INTERVAL);
+        resolve(hub);
+      };
+      server.once("error", onError);
+      server.once("listening", onListening);
+    });
+  }
+  /** Bound port. Useful for tests, which start the hub on port 0. */
+  get port() {
+    const address = this.#server.address();
+    return typeof address === "object" && address !== null ? address.port : 0;
+  }
+  pages() {
+    return [...this.#clients.values()].map(({ socket: _socket, ...page }) => page);
+  }
+  find(url) {
+    for (const client of this.#clients.values()) {
+      if (sameUrl(client.url, url)) return client;
+    }
+    return void 0;
+  }
+  async request(tabId, action, payload, timeoutMs = 3e4) {
+    const client = this.#clients.get(tabId);
+    if (client === void 0) {
+      throw new ToolError("the page is no longer connected. Call inspect again.");
+    }
+    return this.#ask(client.socket, action, payload, timeoutMs);
+  }
+  /**
+   * Asks any connected worker, not a specific tab. This is how the server
+   * attaches to a page: the worker picks the tab the human is looking at.
+   */
+  async requestAny(action, payload, timeoutMs = 3e4) {
+    const socket = this.#firstSocket();
+    if (socket === void 0) {
+      throw new ToolError(
+        "the extension is not connected. Is Chrome open with the extension loaded?"
+      );
+    }
+    return this.#ask(socket, action, payload, timeoutMs);
+  }
+  /** True when at least one extension worker is connected. */
+  hasClient() {
+    return this.#firstSocket() !== void 0;
+  }
+  /** Number of connected extension workers, with or without an attached page. */
+  clientCount() {
+    let count = 0;
+    for (const socket of this.#sockets) {
+      if (socket.readyState === WebSocket.OPEN) count += 1;
+    }
+    return count;
+  }
+  #firstSocket() {
+    for (const socket of this.#sockets) {
+      if (socket.readyState === WebSocket.OPEN) return socket;
+    }
+    return void 0;
+  }
+  #ask(socket, action, payload, timeoutMs) {
+    const id = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(
+          new ToolError(
+            `the extension did not answer "${action}" within ${Math.round(timeoutMs / 1e3)}s`
+          )
+        );
+      }, timeoutMs);
+      this.#pending.set(id, {
+        resolve,
+        reject,
+        timer,
+        socket,
+        action
+      });
+      socket.send(JSON.stringify({ type: "request", id, action, payload }));
+    });
+  }
+  /**
+   * Resolves on the next `hello`, or immediately when a matching page is
+   * already connected. A page that connects with another URL resolves as
+   * `mismatch` so the agent can tell the user exactly what is wrong.
+   */
+  waitForPage(url, timeoutMs) {
+    const existing = this.find(url);
+    if (existing !== void 0) return Promise.resolve({ status: "ready", page: existing });
+    return new Promise((resolve) => {
+      const waiter = {
+        url,
+        resolve: (outcome) => {
+          clearTimeout(timer);
+          resolve(outcome);
+        }
+      };
+      const timer = setTimeout(() => {
+        this.#waiters.delete(waiter);
+        resolve({ status: "timeout" });
+      }, timeoutMs);
+      this.#waiters.add(waiter);
+    });
+  }
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#ping !== void 0) clearInterval(this.#ping);
+    this.#ping = void 0;
+    for (const waiter of [...this.#waiters]) waiter.resolve({ status: "timeout" });
+    this.#waiters.clear();
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new ToolError("the extension bridge is shutting down"));
+    }
+    this.#pending.clear();
+    const sockets = [...this.#sockets];
+    for (const socket of sockets) socket.close(1001, "litedesign server closing");
+    for (const socket of this.#controllers) socket.close(1001, "litedesign server closing");
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        for (const socket of sockets) socket.terminate();
+        resolve();
+      }, 500);
+      this.#server.close(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+  #accept(socket) {
+    this.#sockets.add(socket);
+    this.#broadcast({ type: "extensions", count: this.clientCount() });
+    socket.on("message", (data) => this.#receive(socket, data.toString()));
+    socket.on("close", () => this.#drop(socket));
+    socket.on("error", () => this.#drop(socket));
+  }
+  #receive(socket, raw) {
+    let message;
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed !== "object" || parsed === null) return;
+      message = parsed;
+    } catch {
+      return;
+    }
+    switch (message.type) {
+      case "hello":
+        if (message.role === "mcp") this.#controllerHello(socket);
+        else this.#hello(socket, message);
+        return;
+      case "request":
+        this.#controllerRequest(socket, message);
+        return;
+      case "response":
+        this.#response(message);
+        return;
+      case "bye":
+        this.#drop(socket);
+        socket.close();
+        return;
+      default:
+        return;
+    }
+  }
+  #controllerHello(socket) {
+    this.#sockets.delete(socket);
+    this.#controllers.add(socket);
+    this.#broadcast({ type: "extensions", count: this.clientCount() });
+    socket.send(
+      JSON.stringify({ type: "pages", pages: this.pages(), extensions: this.clientCount() })
+    );
+  }
+  /**
+   * An MCP client asks the daemon to run something. The daemon forwards to the
+   * right extension socket and routes the answer back.
+   */
+  #controllerRequest(socket, message) {
+    const { id, action } = message;
+    if (typeof id !== "string" || typeof action !== "string") return;
+    if (action === "pages") {
+      this.#reply(socket, id, true, this.pages());
+      return;
+    }
+    if (action === "has-client") {
+      this.#reply(socket, id, true, this.hasClient());
+      return;
+    }
+    const tabId = typeof message.tabId === "number" ? message.tabId : void 0;
+    const target = tabId === void 0 ? this.#firstSocket() : this.#clients.get(tabId)?.socket;
+    if (target === void 0 || target.readyState !== WebSocket.OPEN) {
+      this.#reply(
+        socket,
+        id,
+        false,
+        void 0,
+        tabId === void 0 ? "the extension is not connected. Is Chrome open with the extension loaded?" : "the page is no longer connected. Call inspect again."
+      );
+      return;
+    }
+    const forwardId = randomUUID();
+    const timer = setTimeout(() => {
+      this.#pending.delete(forwardId);
+      this.#reply(
+        socket,
+        id,
+        false,
+        void 0,
+        `the extension did not answer "${action}" within 30s`
+      );
+    }, 3e4);
+    this.#pending.set(forwardId, {
+      resolve: () => void 0,
+      reject: () => void 0,
+      timer,
+      socket: target,
+      action,
+      controller: socket,
+      controllerId: id
+    });
+    target.send(
+      JSON.stringify({ type: "request", id: forwardId, action, payload: message.payload })
+    );
+  }
+  #reply(socket, id, ok, result, error) {
+    if (socket.readyState !== WebSocket.OPEN) return;
+    socket.send(JSON.stringify({ type: "response", id, ok, result, error }));
+  }
+  #hello(socket, message) {
+    const { tabId, url } = message;
+    if (typeof tabId !== "number" || !Number.isInteger(tabId) || typeof url !== "string" || url === "") {
+      return;
+    }
+    const page = {
+      tabId,
+      url,
+      title: typeof message.title === "string" ? message.title : "",
+      version: typeof message.version === "string" ? message.version : ""
+    };
+    const previous = this.#socketTab.get(socket);
+    if (previous !== void 0 && previous !== tabId) {
+      const old = this.#clients.get(previous);
+      if (old?.socket === socket) this.#clients.delete(previous);
+    }
+    this.#clients.set(tabId, { ...page, socket });
+    this.#socketTab.set(socket, tabId);
+    this.#broadcast({ type: "page", page });
+    this.#broadcast({ type: "extensions", count: this.clientCount() });
+    for (const waiter of [...this.#waiters]) {
+      this.#waiters.delete(waiter);
+      waiter.resolve(
+        sameUrl(page.url, waiter.url) ? { status: "ready", page } : { status: "mismatch", page }
+      );
+    }
+  }
+  #response(message) {
+    const { id } = message;
+    if (typeof id !== "string") return;
+    const pending = this.#pending.get(id);
+    if (pending === void 0) return;
+    this.#pending.delete(id);
+    clearTimeout(pending.timer);
+    if (pending.controller !== void 0) {
+      const ok = message.ok === true;
+      this.#reply(
+        pending.controller,
+        pending.controllerId ?? "",
+        ok,
+        message.result,
+        typeof message.error === "string" && message.error !== "" ? message.error : `the extension failed to run "${pending.action}"`
+      );
+      return;
+    }
+    if (message.ok === true) {
+      pending.resolve(message.result);
+      return;
+    }
+    pending.reject(
+      new ToolError(
+        typeof message.error === "string" && message.error !== "" ? message.error : `the extension failed to run "${pending.action}"`
+      )
+    );
+  }
+  #broadcast(message) {
+    const raw = JSON.stringify(message);
+    for (const socket of this.#controllers) {
+      if (socket.readyState === WebSocket.OPEN) socket.send(raw);
+    }
+  }
+  #drop(socket) {
+    const tabId = this.#socketTab.get(socket);
+    this.#socketTab.delete(socket);
+    this.#sockets.delete(socket);
+    this.#controllers.delete(socket);
+    if (tabId !== void 0 && this.#clients.get(tabId)?.socket === socket) {
+      this.#clients.delete(tabId);
+      this.#broadcast({ type: "page-gone", tabId });
+    }
+    this.#broadcast({ type: "extensions", count: this.clientCount() });
+    for (const [id, pending] of this.#pending) {
+      if (pending.socket !== socket) continue;
+      this.#pending.delete(id);
+      clearTimeout(pending.timer);
+      if (pending.controller !== void 0) {
+        this.#reply(
+          pending.controller,
+          pending.controllerId ?? "",
+          false,
+          void 0,
+          "the page disconnected before it answered"
+        );
+      } else {
+        pending.reject(new ToolError("the page disconnected before it answered"));
+      }
+    }
+  }
+  #broadcastPing() {
+    for (const socket of this.#sockets) {
+      if (socket.readyState === WebSocket.OPEN) {
+        socket.send(JSON.stringify({ type: "ping" }));
+      }
+    }
+  }
+};
+function sameUrl(a, b) {
+  return normalize(a) === normalize(b);
+}
+function normalize(url) {
+  try {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    return parsed.href;
+  } catch {
+    return url;
+  }
+}
+var current = null;
+var currentError = null;
+function setHub(hub) {
+  current = hub;
+  currentError = null;
+}
+function setHubError(message) {
+  current = null;
+  currentError = message;
+}
+function getHub() {
+  return current;
+}
+function getHubError() {
+  return currentError;
+}
+
+// packages/cli/src/hub-client.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { WebSocket as WebSocket2 } from "ws";
+var DEFAULT_TIMEOUT = 3e4;
+var HubClient = class _HubClient {
+  #socket;
+  #pages = /* @__PURE__ */ new Map();
+  #pending = /* @__PURE__ */ new Map();
+  #waiters = /* @__PURE__ */ new Set();
+  #extensions = 0;
+  #closed = false;
+  constructor(socket) {
+    this.#socket = socket;
+  }
+  static connect(port, timeoutMs = 2e3) {
+    return new Promise((resolve, reject) => {
+      const socket = new WebSocket2(`ws://127.0.0.1:${port}`);
+      const client = new _HubClient(socket);
+      const timer = setTimeout(() => {
+        socket.terminate();
+        reject(new ToolError(`the bridge on port ${port} did not answer`));
+      }, timeoutMs);
+      socket.once("open", () => {
+        socket.send(JSON.stringify({ type: "hello", role: "mcp" }));
+      });
+      socket.once("error", (error) => {
+        clearTimeout(timer);
+        reject(error instanceof Error ? error : new ToolError(String(error)));
+      });
+      client.#listen(() => {
+        clearTimeout(timer);
+        resolve(client);
+      });
+    });
+  }
+  pages() {
+    return [...this.#pages.values()];
+  }
+  find(url) {
+    for (const page of this.#pages.values()) {
+      if (sameUrl(page.url, url)) return page;
+    }
+    return void 0;
+  }
+  hasClient() {
+    return this.#extensions > 0;
+  }
+  clientCount() {
+    return this.#extensions;
+  }
+  async request(tabId, action, payload, timeoutMs = DEFAULT_TIMEOUT) {
+    return this.#ask({ tabId, action, payload }, action, timeoutMs);
+  }
+  async requestAny(action, payload, timeoutMs = DEFAULT_TIMEOUT) {
+    return this.#ask({ action, payload }, action, timeoutMs);
+  }
+  waitForPage(url, timeoutMs) {
+    const existing = this.find(url);
+    if (existing !== void 0) return Promise.resolve({ status: "ready", page: existing });
+    return new Promise((resolve) => {
+      const waiter = {
+        url,
+        resolve: (outcome) => {
+          clearTimeout(timer);
+          resolve(outcome);
+        }
+      };
+      const timer = setTimeout(() => {
+        this.#waiters.delete(waiter);
+        resolve({ status: "timeout" });
+      }, timeoutMs);
+      this.#waiters.add(waiter);
+    });
+  }
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const waiter of [...this.#waiters]) waiter.resolve({ status: "timeout" });
+    this.#waiters.clear();
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new ToolError("the bridge client is closing"));
+    }
+    this.#pending.clear();
+    this.#socket.close(1e3, "mcp session ended");
+  }
+  #ask(message, action, timeoutMs) {
+    if (this.#closed || this.#socket.readyState !== WebSocket2.OPEN) {
+      return Promise.reject(
+        new ToolError("the bridge is not running. Start it with `litedesign ws start`.")
+      );
+    }
+    const id = randomUUID2();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(
+          new ToolError(
+            `the extension did not answer "${action}" within ${Math.round(timeoutMs / 1e3)}s`
+          )
+        );
+      }, timeoutMs);
+      this.#pending.set(id, {
+        resolve,
+        reject,
+        timer
+      });
+      this.#socket.send(JSON.stringify({ type: "request", id, ...message }));
+    });
+  }
+  #listen(ready) {
+    this.#socket.on("message", (data) => {
+      let message;
+      try {
+        const parsed = JSON.parse(data.toString());
+        if (typeof parsed !== "object" || parsed === null) return;
+        message = parsed;
+      } catch {
+        return;
+      }
+      switch (message.type) {
+        case "pages":
+          this.#takePages(message);
+          ready();
+          return;
+        case "page":
+          this.#takePage(message.page);
+          return;
+        case "page-gone":
+          if (typeof message.tabId === "number") this.#pages.delete(message.tabId);
+          return;
+        case "extensions":
+          if (typeof message.count === "number") this.#extensions = message.count;
+          return;
+        case "response":
+          this.#response(message);
+          return;
+        default:
+          return;
+      }
+    });
+    this.#socket.on("close", () => {
+      this.#closed = true;
+      for (const waiter of [...this.#waiters]) waiter.resolve({ status: "timeout" });
+      this.#waiters.clear();
+      for (const pending of this.#pending.values()) {
+        clearTimeout(pending.timer);
+        pending.reject(new ToolError("the bridge stopped running"));
+      }
+      this.#pending.clear();
+    });
+  }
+  #takePages(message) {
+    if (typeof message.extensions === "number") this.#extensions = message.extensions;
+    if (!Array.isArray(message.pages)) return;
+    this.#pages.clear();
+    for (const page of message.pages) this.#takePage(page);
+  }
+  #takePage(value) {
+    if (typeof value !== "object" || value === null) return;
+    const page = value;
+    if (typeof page.tabId !== "number" || typeof page.url !== "string") return;
+    this.#pages.set(page.tabId, page);
+    for (const waiter of [...this.#waiters]) {
+      this.#waiters.delete(waiter);
+      waiter.resolve(
+        sameUrl(page.url, waiter.url) ? { status: "ready", page } : { status: "mismatch", page }
+      );
+    }
+  }
+  #response(message) {
+    const { id } = message;
+    if (typeof id !== "string") return;
+    const pending = this.#pending.get(id);
+    if (pending === void 0) return;
+    this.#pending.delete(id);
+    clearTimeout(pending.timer);
+    if (message.ok === true) {
+      pending.resolve(message.result);
+      return;
+    }
+    pending.reject(
+      new ToolError(
+        typeof message.error === "string" && message.error !== "" ? message.error : "the extension failed to run the request"
+      )
+    );
+  }
+};
+
+// packages/cli/src/ws.ts
+var START_TIMEOUT = 5e3;
+function portOpen(port, timeoutMs = 400) {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    const done = (value) => {
+      socket.destroy();
+      resolve(value);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+async function readState(port) {
+  const file = wsState(port);
+  if (!existsSync2(file)) return void 0;
+  try {
+    const raw = JSON.parse(await readFile2(file, "utf8"));
+    if (typeof raw.pid !== "number" || typeof raw.port !== "number") return void 0;
+    return { pid: raw.pid, port: raw.port };
+  } catch {
+    return void 0;
+  }
+}
+async function writeState(state) {
+  await writeFile(wsState(state.port), `${JSON.stringify(state, null, 2)}
+`);
+}
+async function clearState(port) {
+  await rm(wsState(port), { force: true });
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function runDaemon(port) {
+  let hub;
+  try {
+    hub = await Hub.start(port);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new ToolError(`could not listen on port ${port}: ${detail}`);
+  }
+  await writeState({ pid: process.pid, port: hub.port });
+  console.log(`  bridge ws://127.0.0.1:${hub.port} \xB7 pid ${process.pid} \xB7 Ctrl+C to stop`);
+  const stop = () => {
+    void (async () => {
+      await clearState(port);
+      await hub.close();
+      process.exit(0);
+    })();
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+}
+async function startDaemon(port) {
+  if (await portOpen(port)) {
+    const state2 = await readState(port);
+    return state2 ?? { pid: 0, port };
+  }
+  const script = process.argv[1];
+  if (script === void 0) {
+    throw new ToolError("could not find the litedesign entry point to start the bridge");
+  }
+  const child = spawn(process.execPath, [script, "ws", "run", "--port", String(port)], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env
+  });
+  child.unref();
+  const started = await waitFor(async () => portOpen(port), START_TIMEOUT);
+  if (!started) {
+    throw new ToolError(
+      `the bridge did not start on port ${port}. Run "litedesign ws run" to see the error.`
+    );
+  }
+  const state = await waitForValue(() => readState(port), 2e3);
+  return state ?? { pid: 0, port };
+}
+async function ensureBridge(port) {
+  try {
+    return await HubClient.connect(port, 500);
+  } catch {
+  }
+  await startDaemon(port);
+  try {
+    return await HubClient.connect(port, 3e3);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new ToolError(`the bridge started but did not accept a connection: ${detail}`);
+  }
+}
+async function stopDaemon(port) {
+  const state = await readState(port);
+  if (state === void 0) {
+    await clearState(port);
+    return false;
+  }
+  if (isAlive(state.pid)) {
+    process.kill(state.pid, "SIGTERM");
+    const stopped = await waitFor(async () => !isAlive(state.pid), 3e3);
+    if (!stopped) throw new ToolError(`the bridge (pid ${state.pid}) did not stop`);
+  }
+  await clearState(port);
+  return true;
+}
+async function wsStatus(port) {
+  const state = await readState(port);
+  const listening = await portOpen(port);
+  if (!listening) {
+    if (state !== void 0) await clearState(port);
+    return { running: false, port };
+  }
+  let extensions;
+  let pages;
+  try {
+    const client = await HubClient.connect(port, 1e3);
+    extensions = client.clientCount();
+    pages = client.pages();
+    await client.close();
+  } catch {
+  }
+  return {
+    running: true,
+    port,
+    ...state !== void 0 ? { pid: state.pid } : {},
+    ...extensions !== void 0 ? { extensions } : {},
+    ...pages !== void 0 ? { pages } : {}
+  };
+}
+async function waitFor(check, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await check()) return true;
+    await delay(100);
+  }
+  return check();
+}
+async function waitForValue(read, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await read();
+    if (value !== void 0) return value;
+    await delay(100);
+  }
+  return read();
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// packages/cli/src/commands/doctor.ts
+function line(status, label, detail) {
+  const mark = status === "ok" ? "ok  " : status === "warn" ? "warn" : "fail";
+  console.log(`  ${mark}  ${label.padEnd(12)} ${detail}`);
+}
+async function doctor() {
+  console.log(`
+  litedesign doctor \xB7 v${VERSION}
+`);
+  const major = Number(process.versions.node.split(".")[0]);
+  line(major >= 20 ? "ok" : "fail", "node", `v${process.versions.node} (requires >= 20)`);
+  const manifestPath = path2.join(EXT_DIR, "manifest.json");
+  if (existsSync3(manifestPath)) {
+    const manifest = JSON.parse(await readFile3(manifestPath, "utf8"));
+    line("ok", "extension", `${EXT_DIR} (v${manifest.version ?? "?"})`);
+  } else {
+    line("fail", "extension", `missing at ${EXT_DIR} \u2014 run: litedesign setup`);
+  }
+  const { port, mode } = await readConfig();
+  if (existsSync3(CONFIG)) {
+    line("ok", "config", `port ${port}, mode ${mode}`);
+  } else {
+    line("warn", "config", "missing \u2014 run: litedesign setup");
+  }
+  const status = await wsStatus(port);
+  line(
+    status.running ? "ok" : "warn",
+    "bridge",
+    status.running ? `running on ${port} \xB7 ${status.extensions ?? 0} extension(s) \xB7 ${status.pages?.length ?? 0} page(s)` : `stopped \u2014 run: litedesign ws start`
+  );
+  console.log("");
+}
+
+// packages/cli/src/commands/setup.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { cp, mkdir, writeFile as writeFile2 } from "node:fs/promises";
+import path3 from "node:path";
+import { fileURLToPath } from "node:url";
+async function setup() {
+  const source = fileURLToPath(BUNDLED_EXTENSION);
+  if (!existsSync4(source)) {
+    throw new Error(
+      "extension assets missing from the package. Reinstall: npm i -g @rahmantech/litedesign"
+    );
+  }
+  await mkdir(HOME, { recursive: true });
+  await cp(source, EXT_DIR, { recursive: true, force: true });
+  let configCreated = false;
+  if (!existsSync4(CONFIG)) {
+    await writeFile2(
+      CONFIG,
+      `${JSON.stringify({ port: DEFAULT_PORT, mode: "auto" }, null, 2)}
+`,
+      "utf8"
+    );
+    configCreated = true;
+  }
+  const config = await readConfig();
+  await writeFile2(
+    path3.join(EXT_DIR, "config.json"),
+    `${JSON.stringify({ port: config.port }, null, 2)}
+`,
+    "utf8"
+  );
+  console.log(`
+  litedesign setup
+
+  [1/3] extension   -> ${EXT_DIR}
+  [2/3] config      -> ${CONFIG}${configCreated ? "" : " (already exists)"}
+  [3/3] done
+
+  One manual step:
+
+    1. open chrome://extensions
+    2. enable Developer mode
+    3. Load unpacked -> ${EXT_DIR}
+
+  Register with your MCP client:
+
+  {
+    "mcpServers": {
+      "litedesign": {
+        "command": "litedesign",
+        "args": ["mcp"]
+      }
+    }
+  }
+
+  port ${config.port} \xB7 mode ${config.mode}
+`);
+}
+
+// packages/cli/src/commands/extension.ts
+async function extensionCommand(args) {
+  const sub = args[0];
+  if (sub === "path") {
+    console.log(EXT_DIR);
+    return;
+  }
+  if (sub === "update") {
+    await setup();
+    return;
+  }
+  throw new Error("usage: litedesign extension <path|update>");
+}
+
+// packages/cli/src/commands/ws.ts
+var HELP = `
+  Usage:
+    litedesign ws start      start the bridge in the background
+    litedesign ws stop       stop the bridge
+    litedesign ws status     show whether it runs and what is connected
+    litedesign ws run        run it in the foreground (used by start)
+`;
+async function wsCommand(argv) {
+  const [action, ...rest] = argv;
+  const port = portFrom(rest) ?? (await readConfig()).port;
+  switch (action) {
+    case void 0:
+    case "help":
+    case "--help":
+      console.log(HELP);
+      return;
+    case "run":
+      await runDaemon(port);
+      return;
+    case "start": {
+      const state = await startDaemon(port);
+      const pid = state.pid > 0 ? ` \xB7 pid ${state.pid}` : "";
+      console.log(`  bridge running \xB7 ws://127.0.0.1:${state.port}${pid}`);
+      return;
+    }
+    case "stop": {
+      const stopped = await stopDaemon(port);
+      console.log(stopped ? "  bridge stopped" : "  bridge was not running");
+      return;
+    }
+    case "status":
+      await printStatus(port);
+      return;
+    default:
+      throw new Error(`unknown ws command: ${action}. Try: litedesign ws --help`);
+  }
+}
+async function printStatus(port) {
+  const status = await wsStatus(port);
+  if (!status.running) {
+    console.log(`  bridge stopped \xB7 port ${port}`);
+    return;
+  }
+  const pid = status.pid === void 0 ? "" : ` \xB7 pid ${status.pid}`;
+  const extensions = status.extensions ?? 0;
+  const pages = status.pages?.length ?? 0;
+  console.log(
+    `  bridge running \xB7 ws://127.0.0.1:${status.port}${pid} \xB7 ${extensions} extension(s) \xB7 ${pages} page(s)`
+  );
+  for (const page of status.pages ?? []) {
+    console.log(`    tab ${page.tabId}  ${page.url}`);
+  }
+}
+function portFrom(args) {
+  const index = args.indexOf("--port");
+  if (index === -1) return void 0;
+  const value = Number(args[index + 1]);
+  return Number.isInteger(value) && value > 0 && value < 65536 ? value : void 0;
+}
+
+// packages/core/dist/core.js
+function right(rect) {
+  return rect.x + rect.w;
+}
+function bottom(rect) {
+  return rect.y + rect.h;
+}
+function centerX(rect) {
+  return rect.x + rect.w / 2;
+}
+function centerY(rect) {
+  return rect.y + rect.h / 2;
+}
+var EDGES = [
+  { axis: "x", edge: "left", value: (rect) => rect.x },
+  { axis: "x", edge: "right", value: right },
+  { axis: "x", edge: "center", value: centerX },
+  { axis: "y", edge: "top", value: (rect) => rect.y },
+  { axis: "y", edge: "bottom", value: bottom },
+  { axis: "y", edge: "center", value: centerY }
+];
+function parseColor(value) {
+  const text = value.trim().toLowerCase();
+  if (text === "" || text === "transparent") return null;
+  if (text.startsWith("#")) return parseHex(text);
+  const match = text.match(/^rgba?\(([^)]+)\)$/);
+  if (match === null) return null;
+  const body = match[1];
+  if (body === void 0) return null;
+  const parts = body.split(/[,/\s]+/).filter((part) => part !== "");
+  if (parts.length < 3) return null;
+  const [r, g, b, a] = parts;
+  return {
+    r: Number(r),
+    g: Number(g),
+    b: Number(b),
+    a: a === void 0 ? 1 : parseAlpha(a)
+  };
+}
+function parseAlpha(value) {
+  if (value.endsWith("%")) return Number(value.slice(0, -1)) / 100;
+  return Number(value);
+}
+function parseHex(text) {
+  const hex = text.slice(1);
+  if (hex.length === 3 || hex.length === 4) {
+    const [r, g, b, a] = hex.split("");
+    if (r === void 0 || g === void 0 || b === void 0) return null;
+    return {
+      r: Number.parseInt(r + r, 16),
+      g: Number.parseInt(g + g, 16),
+      b: Number.parseInt(b + b, 16),
+      a: a === void 0 ? 1 : Number.parseInt(a + a, 16) / 255
+    };
+  }
+  if (hex.length === 6 || hex.length === 8) {
+    return {
+      r: Number.parseInt(hex.slice(0, 2), 16),
+      g: Number.parseInt(hex.slice(2, 4), 16),
+      b: Number.parseInt(hex.slice(4, 6), 16),
+      a: hex.length === 8 ? Number.parseInt(hex.slice(6, 8), 16) / 255 : 1
+    };
+  }
+  return null;
+}
+function blend(source, destination) {
+  const a = source.a + destination.a * (1 - source.a);
+  if (a === 0) return { r: 0, g: 0, b: 0, a: 0 };
+  const mix = (src, dst) => (src * source.a + dst * destination.a * (1 - source.a)) / a;
+  return {
+    r: mix(source.r, destination.r),
+    g: mix(source.g, destination.g),
+    b: mix(source.b, destination.b),
+    a
+  };
+}
+function luminance(color) {
+  const channel = (value) => {
+    const s = value / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(color.r) + 0.7152 * channel(color.g) + 0.0722 * channel(color.b);
+}
+function contrastRatio(a, b) {
+  const first = luminance(a);
+  const second = luminance(b);
+  const lighter = Math.max(first, second);
+  const darker = Math.min(first, second);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+var SPACING_SCALE = 4;
+function defineRule(id, run2) {
+  return Object.assign(run2, { id });
+}
+function issue(input) {
+  const suffix = input.key === void 0 ? "" : `:${input.key}`;
+  return {
+    id: `${input.rule}:${input.selector}${suffix}`,
+    selector: input.selector,
+    rule: input.rule,
+    severity: input.severity,
+    actual: input.actual,
+    expected: input.expected,
+    autoFix: input.autoFix
+  };
+}
+var TOLERANCE2 = 2;
+var WINDOW = 4;
+var alignmentNearMiss = defineRule("alignment-near-miss", (graph) => {
+  const issues = [];
+  for (const spec of EDGES) {
+    const items = graph.nodes.filter((node) => node.parent !== null).map((node) => ({ node, value: spec.value(node.rect) })).sort((a, b) => a.value - b.value);
+    let start = 0;
+    for (let i = 1; i <= items.length; i++) {
+      const previous = items[i - 1];
+      const current2 = items[i];
+      const breaks = current2 === void 0 || previous === void 0 || current2.value - previous.value > WINDOW;
+      if (!breaks) continue;
+      const cluster = items.slice(start, i);
+      start = i;
+      if (cluster.length < 2) continue;
+      const first = cluster[0];
+      const last = cluster[cluster.length - 1];
+      if (first === void 0 || last === void 0) continue;
+      if (last.value - first.value <= TOLERANCE2) continue;
+      const target = cluster[Math.floor(cluster.length / 2)];
+      if (target === void 0) continue;
+      let worst = cluster[0];
+      if (worst === void 0) continue;
+      for (const item of cluster) {
+        if (Math.abs(item.value - target.value) > Math.abs(worst.value - target.value)) worst = item;
+      }
+      issues.push(
+        issue({
+          rule: "alignment-near-miss",
+          selector: worst.node.id,
+          key: spec.edge,
+          severity: "P2",
+          actual: `${Math.round(worst.value * 10) / 10}px`,
+          expected: `${Math.round(target.value * 10) / 10}px`,
+          autoFix: false
+        })
+      );
+    }
+  }
+  return issues;
+});
+var WHITE = { r: 255, g: 255, b: 255, a: 1 };
+var NORMAL_MINIMUM = 4.5;
+var LARGE_MINIMUM = 3;
+var contrastMinimum = defineRule("contrast", (graph) => {
+  const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+  const issues = [];
+  for (const node of graph.nodes) {
+    if (node.text === "") continue;
+    const foreground = parseColor(node.styles.color);
+    if (foreground === null) continue;
+    const background = backgroundOf(node, byId);
+    const ratio = contrastRatio(blend(foreground, background), background);
+    const minimum = isLargeText(node) ? LARGE_MINIMUM : NORMAL_MINIMUM;
+    if (ratio >= minimum) continue;
+    issues.push(
+      issue({
+        rule: "contrast",
+        selector: node.id,
+        severity: "P1",
+        actual: `${Math.round(ratio * 100) / 100}:1`,
+        expected: `>= ${minimum}:1`,
+        autoFix: false
+      })
+    );
+  }
+  return issues;
+});
+function isLargeText(node) {
+  const size = Number.parseFloat(node.styles.fontSize);
+  const weight = Number.parseInt(node.styles.fontWeight, 10);
+  if (!Number.isFinite(size)) return false;
+  return size >= 24 || size >= 18.66 && weight >= 700;
+}
+function backgroundOf(node, byId) {
+  const layers = [];
+  let current2 = node;
+  while (current2 !== void 0) {
+    const color = parseColor(current2.styles.backgroundColor);
+    if (color !== null && color.a > 0) {
+      layers.push(color);
+      if (color.a === 1) break;
+    }
+    current2 = current2.parent === null ? void 0 : byId.get(current2.parent);
+  }
+  let background = WHITE;
+  for (let i = layers.length - 1; i >= 0; i--) {
+    const layer = layers[i];
+    if (layer === void 0) continue;
+    background = blend(layer, background);
+  }
+  return background;
+}
+var SLACK = 1;
+var overflowClipped = defineRule("overflow", (graph) => {
+  const issues = [];
+  for (const node of graph.nodes) {
+    if (node.styles.display.startsWith("inline")) continue;
+    if (node.box.clientW === 0 && node.box.clientH === 0) continue;
+    if (node.box.scrollW > node.box.clientW + SLACK) {
+      issues.push(
+        issue({
+          rule: "overflow",
+          selector: node.id,
+          key: "x",
+          severity: "P2",
+          actual: `${node.box.scrollW}px content in ${node.box.clientW}px`,
+          expected: "content fits horizontally",
+          autoFix: false
+        })
+      );
+    }
+    if (node.box.scrollH > node.box.clientH + SLACK) {
+      issues.push(
+        issue({
+          rule: "overflow",
+          selector: node.id,
+          key: "y",
+          severity: "P2",
+          actual: `${node.box.scrollH}px content in ${node.box.clientH}px`,
+          expected: "content fits vertically",
+          autoFix: false
+        })
+      );
+    }
+  }
+  return issues;
+});
+var MIN_SAMPLES = 4;
+var radiusConsistency = defineRule("radius-consistency", (graph) => {
+  const groups = /* @__PURE__ */ new Map();
+  for (const node of graph.nodes) {
+    const radius = normalizeRadius(node.styles.borderRadius);
+    if (radius === null) continue;
+    const group = groups.get(radius);
+    if (group) group.push(node);
+    else groups.set(radius, [node]);
+  }
+  if (groups.size < 2) return [];
+  const total = [...groups.values()].reduce((sum, group) => sum + group.length, 0);
+  if (total < MIN_SAMPLES) return [];
+  const ranked = [...groups.entries()].sort((a, b) => b[1].length - a[1].length);
+  const expected = ranked[0];
+  if (expected === void 0) return [];
+  const [expectedValue, expectedNodes] = expected;
+  const issues = [];
+  for (const [value, nodes] of ranked.slice(1)) {
+    if (nodes.length >= expectedNodes.length) continue;
+    for (const node of nodes) {
+      if (isPill(node)) continue;
+      issues.push(
+        issue({
+          rule: "radius-consistency",
+          selector: node.id,
+          severity: "P3",
+          actual: value,
+          expected: expectedValue,
+          autoFix: true
+        })
+      );
+    }
+  }
+  return issues;
+});
+function normalizeRadius(value) {
+  const text = value.trim();
+  if (text === "" || text === "0px" || text === "0") return null;
+  const parts = text.split(/\s+/);
+  const unique = [...new Set(parts)];
+  if (unique.length === 1) return unique[0] ?? null;
+  return parts.join(" ");
+}
+function isPill(node) {
+  const text = node.styles.borderRadius;
+  if (text.includes("%")) return true;
+  const radius = Number.parseFloat(text);
+  if (!Number.isFinite(radius)) return false;
+  return radius >= Math.min(node.rect.w, node.rect.h) / 2;
+}
+var spacingScale = defineRule("spacing-scale", (graph) => {
+  const issues = [];
+  for (const gap of graph.gaps) {
+    if (gap.kind !== "sibling") continue;
+    const actual = Math.round(gap.distance);
+    if (actual <= 0 || actual % SPACING_SCALE === 0) continue;
+    issues.push(
+      issue({
+        rule: "spacing-scale",
+        selector: gap.a,
+        key: `${gap.axis}:${gap.b}`,
+        severity: "P2",
+        actual: `${actual}px`,
+        expected: `${Math.round(actual / SPACING_SCALE) * SPACING_SCALE}px`,
+        autoFix: true
+      })
+    );
+  }
+  return issues;
+});
+var defaultRules = [
+  spacingScale,
+  alignmentNearMiss,
+  radiusConsistency,
+  overflowClipped,
+  contrastMinimum
+];
+var RULE_IDS = defaultRules.map((rule) => rule.id);
+var LAYERS = ["grid", "guide", "gap", "issue", "hover"];
+
+// packages/cli/src/drivers/extension.ts
+var ExtensionDriver = class {
+  #hub;
+  #target;
+  constructor(hub) {
+    this.#hub = hub;
+  }
+  async open(url) {
+    this.#target = url;
+    if (this.#hub.find(url) !== void 0) return;
+    if (!this.#hub.hasClient()) throw new AwaitingUserError(url);
+    const page = await this.#hub.requestAny("attach");
+    if (!sameUrl(page.url, url)) throw new MismatchError(url, page.url);
+    this.#target = page.url;
+  }
+  async waitForPage(url, timeoutMs) {
+    const outcome = await this.#hub.waitForPage(url, timeoutMs);
+    if (outcome.status === "timeout") return { status: "timeout" };
+    if (outcome.status === "mismatch") return { status: "mismatch", url: outcome.page.url };
+    this.#target = outcome.page.url;
+    return { status: "ready", url: outcome.page.url };
+  }
+  async graph() {
+    return this.#request("graph");
+  }
+  async issues(rules) {
+    const graph = await this.graph();
+    if (rules === void 0 || rules.length === 0) return graph.issues;
+    const wanted = new Set(rules);
+    return graph.issues.filter((issue2) => wanted.has(issue2.rule));
+  }
+  async measure(selector) {
+    return this.#request("measure", { selector });
+  }
+  async screenshot(options = {}) {
+    return decode(await this.#request("screenshot", options));
+  }
+  async annotate(options = {}) {
+    return decode(await this.#request("annotate", options));
+  }
+  async overlay(options) {
+    const result = await this.#request("overlay", options);
+    if (result === void 0) {
+      throw new ToolError(
+        "the extension did not report the overlay state. Reload the litedesign extension at chrome://extensions, then try again."
+      );
+    }
+    return result;
+  }
+  async close() {
+  }
+  #request(action, payload) {
+    const page = this.#require();
+    return this.#hub.request(page.tabId, action, payload);
+  }
+  #require() {
+    if (this.#target === void 0) {
+      throw new ToolError("no page is open. Call inspect with a url first");
+    }
+    const page = this.#hub.find(this.#target);
+    if (page === void 0) {
+      throw new ToolError("the page is no longer connected. Open it and call inspect again.");
+    }
+    return page;
+  }
+};
+function decode(payload) {
+  if (typeof payload?.data !== "string" || payload.data === "") {
+    throw new ToolError("the extension returned an empty screenshot");
+  }
+  return Buffer.from(payload.data, "base64");
+}
+
+// packages/cli/src/drivers/playwright.ts
+import { existsSync as existsSync5 } from "node:fs";
+import path4 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var DEFAULT_VIEWPORT = { width: 1280, height: 800 };
+var PlaywrightDriver = class {
+  #playwright;
+  #corePath;
+  #browser;
+  #context;
+  #page;
+  constructor(playwright, options = {}) {
+    this.#playwright = playwright;
+    this.#corePath = resolveCorePath(options.corePath);
+  }
+  async open(url, viewport) {
+    const page = await this.#ensurePage();
+    await page.setViewportSize(
+      viewport === void 0 ? DEFAULT_VIEWPORT : { width: viewport.w, height: viewport.h }
+    );
+    await page.goto(url, { waitUntil: "load" });
+    await this.#inject(page);
+  }
+  async graph() {
+    const page = await this.#requirePage();
+    await this.#inject(page);
+    return page.evaluate(() => {
+      const core = window.__litedesign;
+      return core.buildGraph(document.body);
+    });
+  }
+  async issues(rules) {
+    const graph = await this.graph();
+    if (rules === void 0 || rules.length === 0) return graph.issues;
+    const wanted = new Set(rules);
+    return graph.issues.filter((issue2) => wanted.has(issue2.rule));
+  }
+  async measure(selector) {
+    const page = await this.#requirePage();
+    await this.#inject(page);
+    const found = await page.evaluate((target) => {
+      const core = window.__litedesign;
+      const graph = core.buildGraph(document.body);
+      const node = core.resolveNode(graph, target);
+      if (node === null) return null;
+      const id = node.id;
+      const gaps = graph.gaps.filter((gap) => gap.a === id || gap.b === id).map((gap) => ({
+        to: gap.a === id ? gap.b : gap.a,
+        axis: gap.axis,
+        distance: gap.distance,
+        kind: gap.kind
+      }));
+      return { node, gaps };
+    }, selector);
+    if (found === null) {
+      throw new ToolError(`selector "${selector}" did not match any element on the page`);
+    }
+    return {
+      id: found.node.id,
+      selector: found.node.selector,
+      tag: found.node.tag,
+      rect: found.node.rect,
+      styles: found.node.styles,
+      gaps: found.gaps
+    };
+  }
+  async screenshot(options = {}) {
+    const page = await this.#requirePage();
+    if (options.selector !== void 0) {
+      const locator = page.locator(options.selector).first();
+      if (await locator.count() === 0) {
+        throw new ToolError(`selector "${options.selector}" did not match any element on the page`);
+      }
+      return locator.screenshot({ type: "png" });
+    }
+    return page.screenshot({ type: "png", fullPage: options.fullPage ?? false });
+  }
+  async annotate(options = {}) {
+    const page = await this.#requirePage();
+    await this.#inject(page);
+    if (options.selector !== void 0) {
+      const locator = page.locator(options.selector).first();
+      if (await locator.count() === 0) {
+        throw new ToolError(`selector "${options.selector}" did not match any element on the page`);
+      }
+      await locator.scrollIntoViewIfNeeded();
+    }
+    await page.evaluate(
+      (input) => {
+        const target = window;
+        target.__litedesign_handle__?.destroy();
+        let graph = target.__litedesign.buildGraph(document.body);
+        if (input.rules !== void 0 && input.rules.length > 0) {
+          const wanted = new Set(input.rules);
+          graph = {
+            ...graph,
+            issues: graph.issues.filter((issue2) => wanted.has(issue2.rule))
+          };
+        }
+        target.__litedesign_handle__ = target.__litedesign.render(graph, { layers: input.layers });
+      },
+      { layers: ["grid", "guide", "gap", "issue"], rules: options.rules }
+    );
+    await page.evaluate(
+      () => new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+      })
+    );
+    return page.screenshot({ type: "png" });
+  }
+  async overlay(options) {
+    const page = await this.#requirePage();
+    await this.#inject(page);
+    const layers = options.enabled ? options.layers ?? [...LAYERS] : [];
+    await page.evaluate(
+      (input) => {
+        const target = window;
+        target.__litedesign_handle__?.destroy();
+        target.__litedesign_handle__ = void 0;
+        if (!input.enabled) return;
+        const graph = target.__litedesign.buildGraph(document.body);
+        target.__litedesign_handle__ = target.__litedesign.render(graph, { layers: input.layers });
+      },
+      { enabled: options.enabled, layers }
+    );
+    return { enabled: options.enabled, layers };
+  }
+  async close() {
+    await this.#context?.close().catch(() => void 0);
+    await this.#browser?.close().catch(() => void 0);
+    this.#context = void 0;
+    this.#browser = void 0;
+    this.#page = void 0;
+  }
+  async #ensurePage() {
+    if (this.#page !== void 0 && !this.#page.isClosed()) return this.#page;
+    const browser = await this.#ensureBrowser();
+    const context = await browser.newContext({
+      viewport: DEFAULT_VIEWPORT,
+      // Injected measurement code must run even on pages with a strict CSP.
+      bypassCSP: true
+    });
+    const page = await context.newPage();
+    this.#context = context;
+    this.#page = page;
+    return page;
+  }
+  async #ensureBrowser() {
+    if (this.#browser?.isConnected() === true) return this.#browser;
+    let last;
+    for (const options of launchCandidates(this.#playwright)) {
+      try {
+        this.#browser = await this.#playwright.chromium.launch({
+          ...options,
+          args: ["--no-sandbox"]
+        });
+        return this.#browser;
+      } catch (error) {
+        last = error;
+      }
+    }
+    const detail = last instanceof Error ? `: ${last.message}` : "";
+    throw new ToolError(`could not launch Chrome for Playwright${detail}`);
+  }
+  async #requirePage() {
+    if (this.#page === void 0 || this.#page.isClosed()) {
+      throw new ToolError("no page is open. Call inspect with a url first");
+    }
+    return this.#page;
+  }
+  async #inject(page) {
+    const ready = await page.evaluate(
+      () => typeof window.__litedesign !== "undefined"
+    );
+    if (ready) return;
+    try {
+      await page.addScriptTag({ path: this.#corePath });
+    } catch (error) {
+      const detail = error instanceof Error ? `: ${error.message}` : "";
+      throw new ToolError(`could not inject the measurement core${detail}`);
+    }
+  }
+};
+function launchCandidates(playwright) {
+  const candidates = [];
+  if (process.env.CHROME_PATH !== void 0) {
+    candidates.push({ executablePath: process.env.CHROME_PATH });
+  }
+  candidates.push({ channel: "chrome" });
+  const bundled = playwright.chromium.executablePath();
+  if (existsSync5(bundled)) candidates.push({ executablePath: bundled });
+  for (const candidate of [
+    "/usr/bin/google-chrome",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser"
+  ]) {
+    if (existsSync5(candidate)) candidates.push({ executablePath: candidate });
+  }
+  return candidates;
+}
+function resolveCorePath(explicit) {
+  const candidates = [
+    explicit,
+    process.env.LITEDESIGN_CORE,
+    fileURLToPath2(new URL("./extension/core.iife.js", import.meta.url)),
+    path4.resolve(
+      path4.dirname(fileURLToPath2(import.meta.url)),
+      "../../../../core/dist/core.iife.js"
+    )
+  ].filter((value) => value !== void 0);
+  for (const candidate of candidates) {
+    if (existsSync5(candidate)) return candidate;
+  }
+  throw new ToolError(
+    "measurement core not found. Run `litedesign setup` or set LITEDESIGN_CORE to core.iife.js"
+  );
+}
+
+// packages/cli/src/drivers/index.ts
+async function loadPlaywright() {
+  try {
+    return await import("playwright-core");
+  } catch {
+    return null;
+  }
+}
+async function detectPlaywright() {
+  return await loadPlaywright() !== null;
+}
+async function selectDriver(mode) {
+  if (mode === "extension") return extensionDriver();
+  const playwright = await loadPlaywright();
+  if (playwright !== null) return new PlaywrightDriver(playwright);
+  if (mode === "playwright") {
+    throw new ToolError(
+      "Playwright is not installed. Install it with `npm i -D playwright` (or `pnpm add -D playwright`) and restart the MCP server."
+    );
+  }
+  return extensionDriver();
+}
+function extensionDriver() {
+  const hub = getHub();
+  if (hub === null) {
+    const reason = getHubError() ?? "the WebSocket hub is not running";
+    throw new ToolError(
+      `the extension bridge is unavailable: ${reason}. Free the port, or install Playwright.`
+    );
+  }
+  return new ExtensionDriver(hub);
+}
+
+// packages/cli/src/mcp/result.ts
+function textResult(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function imageResult(value, image) {
+  return {
+    content: [
+      { type: "text", text: JSON.stringify(value, null, 2) },
+      { type: "image", data: image.toString("base64"), mimeType: "image/png" }
+    ]
+  };
+}
+function errorResult(error) {
+  const message = error instanceof Error && error.message !== "" ? error.message : typeof error === "string" && error !== "" ? error : "unexpected error";
+  return { isError: true, content: [{ type: "text", text: message }] };
+}
+
+// packages/cli/src/mcp/session.ts
+var session = null;
+async function openPage(mode, url, viewport) {
+  if (session === null) {
+    session = { driver: await selectDriver(mode), url, ready: false };
+  }
+  session.url = url;
+  await session.driver.open(url, viewport);
+  session.ready = true;
+  return session.driver;
+}
+function requirePage() {
+  if (session === null || !session.ready) {
+    throw new ToolError("no page is open. Call inspect with a url first");
+  }
+  return session.driver;
+}
+async function waitForPage(timeoutMs) {
+  if (session === null || session.url === "") {
+    throw new ToolError("no page is requested. Call inspect with a url first");
+  }
+  const expected = session.url;
+  const driver = session.driver;
+  if (driver.waitForPage === void 0) {
+    return { status: "ready", url: expected, expected };
+  }
+  const result = await driver.waitForPage(expected, timeoutMs);
+  if (result.status === "ready") {
+    session.ready = true;
+    return { status: "ready", url: result.url, expected };
+  }
+  if (result.status === "timeout") return { status: "timeout", expected };
+  return { status: "mismatch", url: result.url, expected };
+}
+async function closeSession() {
+  if (session === null) return;
+  const current2 = session;
+  session = null;
+  await current2.driver.close();
+}
+
+// packages/cli/src/mcp/tools/await-page.ts
+var DEFAULT_TIMEOUT2 = 12e4;
+var MAX_TIMEOUT = 6e5;
+async function awaitPageTool(input) {
+  const timeoutMs = Math.min(
+    Math.max(Math.round(input.timeoutMs ?? DEFAULT_TIMEOUT2), 1e3),
+    MAX_TIMEOUT
+  );
+  const result = await waitForPage(timeoutMs);
+  if (result.status === "ready") {
+    return textResult({
+      status: "ready",
+      url: result.url,
+      message: "The page is connected. Call inspect to read it."
+    });
+  }
+  if (result.status === "timeout") {
+    return textResult({
+      status: "timeout",
+      url: result.expected,
+      message: handoffMessage(result.expected)
+    });
+  }
+  return textResult({
+    status: "mismatch",
+    expected: result.expected,
+    actual: result.url,
+    message: mismatchMessage(result.expected, result.url)
+  });
+}
+
+// packages/cli/src/mcp/format.ts
+var MAX_TREE_LINES = 200;
+var MAX_DEPTH_INDENT = 12;
+var MAX_TEXT = 48;
+function formatTree(graph, maxLines = MAX_TREE_LINES) {
+  const lines = [];
+  for (const node of graph.nodes) {
+    if (lines.length >= maxLines) break;
+    const indent = "  ".repeat(Math.min(node.depth, MAX_DEPTH_INDENT));
+    const size = `${Math.round(node.rect.w)}\xD7${Math.round(node.rect.h)}`;
+    const text = node.text === "" ? "" : ` ${clip(node.text)}`;
+    lines.push(`${indent}${node.tag} ${size}${text}`);
+  }
+  if (graph.nodes.length > maxLines) {
+    lines.push(`\u2026 ${graph.nodes.length - maxLines} more nodes`);
+  }
+  return lines.join("\n");
+}
+function issuePayload(issues, limit) {
+  return {
+    issues: issues.slice(0, limit).map((issue2) => ({
+      selector: issue2.selector,
+      rule: issue2.rule,
+      severity: issue2.severity,
+      actual: issue2.actual,
+      expected: issue2.expected,
+      autoFix: issue2.autoFix
+    })),
+    total: issues.length,
+    truncated: issues.length > limit
+  };
+}
+function pngSize(buffer) {
+  if (buffer.length < 24 || buffer.toString("ascii", 1, 4) !== "PNG") {
+    return { width: 0, height: 0 };
+  }
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+function clip(text) {
+  return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT - 1)}\u2026` : text;
+}
+
+// packages/cli/src/mcp/rules.ts
+function validateRules(rules) {
+  const unknown = rules.filter((rule) => !RULE_IDS.includes(rule));
+  if (unknown.length > 0) {
+    const label = unknown.length === 1 ? "rule" : "rules";
+    throw new ToolError(
+      `unknown ${label}: ${unknown.join(", ")}. Valid rules: ${RULE_IDS.join(", ")}`
+    );
+  }
+  return rules.length === 0 ? void 0 : rules;
+}
+
+// packages/cli/src/mcp/tools/find-issues.ts
+var DEFAULT_LIMIT = 50;
+var MAX_LIMIT = 200;
+async function findIssuesTool(input) {
+  const rules = validateRules(input.rules ?? []);
+  const limit = clamp(input.limit ?? DEFAULT_LIMIT, 1, MAX_LIMIT);
+  const issues = await requirePage().issues(rules);
+  return textResult(issuePayload(issues, limit));
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(Math.round(value), min), max);
+}
+
+// packages/cli/src/mcp/tools/inspect.ts
+async function inspectTool(input) {
+  const config = await readConfig();
+  let driver;
+  try {
+    driver = await openPage(config.mode, input.url, input.viewport);
+  } catch (error) {
+    if (error instanceof AwaitingUserError) {
+      return textResult({
+        status: "awaiting_user",
+        url: input.url,
+        next: "await_page",
+        message: handoffMessage(input.url)
+      });
+    }
+    if (error instanceof MismatchError) {
+      return textResult({
+        status: "mismatch",
+        expected: error.expected,
+        actual: error.actual,
+        next: "await_page",
+        message: error.message
+      });
+    }
+    throw error;
+  }
+  const graph = await driver.graph();
+  const payload = {
+    status: "ready",
+    url: graph.url,
+    viewport: graph.viewport,
+    summary: {
+      nodes: graph.nodes.length,
+      issues: graph.issues.length,
+      truncated: graph.truncated
+    },
+    tree: formatTree(graph)
+  };
+  if (input.screenshot !== true) return textResult(payload);
+  const image = await driver.screenshot();
+  return imageResult(payload, image);
+}
+
+// packages/cli/src/mcp/tools/measure.ts
+async function measureTool(input) {
+  const measured = await requirePage().measure(input.selector);
+  return textResult(measured);
+}
+
+// packages/cli/src/mcp/tools/overlay.ts
+async function overlayTool(input) {
+  const driver = requirePage();
+  const enabled = input.enabled !== false;
+  const layers = parseLayers(input.layers);
+  const result = await driver.overlay({ enabled, layers });
+  return textResult({
+    status: result.enabled ? "shown" : "hidden",
+    layers: result.layers
+  });
+}
+function parseLayers(requested) {
+  if (requested === void 0 || requested.length === 0) return void 0;
+  const valid = new Set(LAYERS);
+  const unknown = requested.filter((name) => !valid.has(name));
+  if (unknown.length > 0) {
+    throw new ToolError(`unknown layer: ${unknown.join(", ")}. Valid layers: ${LAYERS.join(", ")}`);
+  }
+  return requested;
+}
+
+// packages/cli/src/mcp/tools/screenshot.ts
+async function screenshotTool(input) {
+  const image = await requirePage().screenshot(input);
+  return imageResult({ ...pngSize(image), bytes: image.length }, image);
+}
+
+// packages/cli/src/mcp/tools/screenshot-annotated.ts
+async function screenshotAnnotatedTool(input) {
+  const rules = validateRules(input.rules ?? []);
+  const image = await requirePage().annotate({
+    selector: input.selector,
+    rules
+  });
+  return imageResult({ ...pngSize(image), bytes: image.length }, image);
+}
+
+// packages/cli/src/mcp/server.ts
+async function guard(run2) {
+  try {
+    return await run2();
+  } catch (error) {
+    if (error instanceof ToolError) return errorResult(error);
+    console.error("[litedesign] unexpected tool error:", error);
+    return errorResult(error);
+  }
+}
+async function runMcpServer() {
+  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const { z } = await import("zod");
+  const config = await readConfig();
+  try {
+    setHub(await ensureBridge(config.port));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    setHubError(reason);
+    console.error(`[litedesign] extension bridge disabled: ${reason}`);
+  }
+  const server = new McpServer({ name: "litedesign", version: VERSION });
+  const viewport = z.object({
+    w: z.number().int().positive().describe("Viewport width in CSS pixels"),
+    h: z.number().int().positive().describe("Viewport height in CSS pixels")
+  }).optional();
+  server.registerTool(
+    "capabilities",
+    {
+      title: "Capabilities",
+      description: "Server version, available drivers, active mode, connected extension pages, and valid rule names.",
+      inputSchema: {}
+    },
+    async () => {
+      const playwright = await detectPlaywright();
+      const hub = getHub();
+      return textResult({
+        version: VERSION,
+        drivers: { playwright, extension: hub !== null },
+        mode: config.mode,
+        port: config.port,
+        rules: RULE_IDS,
+        extension: {
+          connected: hub?.clientCount() ?? 0,
+          pages: hub?.pages() ?? [],
+          error: getHubError()
+        }
+      });
+    }
+  );
+  server.registerTool(
+    "inspect",
+    {
+      title: "Inspect page",
+      description: 'Open a page and return a tree summary. Call this before measure, find_issues, overlay, screenshot, or screenshot_annotated. No image by default: the numbers the agent needs come from the DOM, so set screenshot to true only when you really need to see the page. With the extension driver this attaches to the active tab by itself; returns "awaiting_user" when no extension is connected and "mismatch" when the active tab is a different page.',
+      inputSchema: {
+        url: z.string().url(),
+        viewport,
+        screenshot: z.boolean().optional().describe(
+          "Set true to also return a viewport PNG. Off by default: ask for it only when visual context is essential."
+        )
+      }
+    },
+    async (input) => guard(() => inspectTool(input))
+  );
+  server.registerTool(
+    "await_page",
+    {
+      title: "Await page",
+      description: "Block until the page from the last inspect call connects through the extension. Use this after inspect returns awaiting_user. Returns ready, timeout, or mismatch; timeout is not an error.",
+      inputSchema: {
+        timeoutMs: z.number().int().min(1e3).max(6e5).optional().describe("How long to wait in milliseconds (default 120000)")
+      }
+    },
+    async (input) => guard(() => awaitPageTool(input))
+  );
+  server.registerTool(
+    "measure",
+    {
+      title: "Measure element",
+      description: "Return the box model, computed styles, and gaps to neighbours for one element. Accepts a CSS selector or a structural selector returned by find_issues. Call inspect first.",
+      inputSchema: {
+        selector: z.string().min(1).describe("CSS selector or a structural selector returned by find_issues")
+      }
+    },
+    async (input) => guard(() => measureTool(input))
+  );
+  server.registerTool(
+    "find_issues",
+    {
+      title: "Find issues",
+      description: "Run the rule engine on the open page and return violations with selector, actual, expected, severity, and autoFix. Call inspect first.",
+      inputSchema: {
+        rules: z.array(z.string()).optional().describe(`Rules to run. Default: all. Valid: ${RULE_IDS.join(", ")}`),
+        limit: z.number().int().min(1).max(200).optional().describe("Maximum issues to return (default 50)")
+      }
+    },
+    async (input) => guard(() => findIssuesTool(input))
+  );
+  server.registerTool(
+    "overlay",
+    {
+      title: "Overlay",
+      description: "Show or hide the measurement overlay in the page the human is looking at: grid, guides, gap labels, and issue boxes. Use it to let the human see spacing without clicking anything. Call inspect first.",
+      inputSchema: {
+        enabled: z.boolean().optional().describe("false hides the overlay (default true)"),
+        layers: z.array(z.string()).optional().describe(`Layers to draw. Default: all. Valid: ${LAYERS.join(", ")}`)
+      }
+    },
+    async (input) => guard(() => overlayTool(input))
+  );
+  server.registerTool(
+    "screenshot",
+    {
+      title: "Screenshot",
+      description: "Capture a PNG of the viewport or of one element. Call inspect first.",
+      inputSchema: {
+        selector: z.string().min(1).optional().describe("Capture only this element"),
+        fullPage: z.boolean().optional().describe("Capture the full scrollable page (ignored when selector is set)")
+      }
+    },
+    async (input) => guard(() => screenshotTool(input))
+  );
+  server.registerTool(
+    "screenshot_annotated",
+    {
+      title: "Annotated screenshot",
+      description: "Render the measurement overlay (grid, guides, gaps, issue boxes with severity and actual \u2192 expected labels) and capture a viewport PNG. Call inspect first.",
+      inputSchema: {
+        selector: z.string().min(1).optional().describe("Scroll this element into view before capturing"),
+        rules: z.array(z.string()).optional().describe("Annotate only these rules. Default: all")
+      }
+    },
+    async (input) => guard(() => screenshotAnnotatedTool(input))
+  );
+  let closing = false;
+  const shutdown = () => {
+    if (closing) return;
+    closing = true;
+    void closeSession().catch(() => void 0).finally(() => getHub()?.close()).finally(() => process.exit(0));
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  process.stdin.once("end", shutdown);
+  process.stdin.once("close", shutdown);
+  await server.connect(new StdioServerTransport());
+  console.error(`[litedesign] MCP server v${VERSION} ready (stdio)`);
+}
+
+// packages/cli/src/cli.ts
+var HELP2 = `
+  litedesign v${VERSION}
+
+  Usage:
+    litedesign setup              scaffold extension + config
+    litedesign extension path     print the folder to load unpacked
+    litedesign extension update   re-copy after an upgrade
+    litedesign doctor             check node, extension, and port
+    litedesign ws start           start the bridge in the background
+    litedesign ws stop            stop the bridge
+    litedesign ws status          show the bridge and connected pages
+    litedesign mcp                start the MCP server (stdio)
+
+  Options:
+    -h, --help                    show this help
+    -v, --version                 show the version
+`;
+async function run(argv) {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case void 0:
+    case "help":
+    case "-h":
+    case "--help":
+      console.log(HELP2);
+      return;
+    case "-v":
+    case "--version":
+      console.log(VERSION);
+      return;
+    case "setup":
+      await setup();
+      return;
+    case "extension":
+      await extensionCommand(rest);
+      return;
+    case "doctor":
+      await doctor();
+      return;
+    case "ws":
+      await wsCommand(rest);
+      return;
+    case "mcp":
+      await runMcpServer();
+      return;
+    default:
+      throw new Error(`unknown command: ${command}. Try: litedesign --help`);
+  }
+}
+
+// packages/cli/src/index.ts
+run(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`
+  error: ${message}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map