@rahmantech/litedesign 0.1.0 → 0.2.0

package/README.md

@@ -44,21 +44,36 @@ litedesign mcp                # MCP server (stdio)
 
 ## Tools
 
-| Tool                   | What it returns                                             |
-| ---------------------- | ----------------------------------------------------------- |
-| `capabilities`         | version, drivers, mode, connected pages, valid rules        |
-| `inspect`              | tree summary; opens the page; no image by default           |
-| `await_page`           | wait for the page from `inspect` to connect                 |
-| `measure`              | box model, computed styles, gaps for one selector           |
-| `find_issues`          | rule violations with selector, actual, expected, severity   |
-| `screenshot`           | PNG of the viewport or one element                          |
-| `screenshot_annotated` | PNG with grid, guides, gaps, and issue labels               |
-| `overlay`              | shows or hides the layers; answers with what the page shows |
+| Tool                   | What it returns                                          |
+| ---------------------- | -------------------------------------------------------- |
+| `capabilities`         | version, drivers, mode, connected pages, valid rules     |
+| `inspect`              | tree summary; opens the page; no image by default        |
+| `await_page`           | wait for the page from `inspect` to connect              |
+| `measure`              | box model, computed styles, gaps for one selector        |
+| `find_issues`          | findings with kind, selector, actual, expected, severity |
+| `screenshot`           | PNG of the viewport or one element                       |
+| `screenshot_annotated` | PNG with grid, guides, gaps, and issue labels            |
+| `overlay`              | shows or hides layers, spotlights one component          |
+| `labels`               | names the human pinned in the toolbar, with selectors    |
 
 Call `inspect` first. It opens the page and keeps it alive for the other tools.
 It returns no image unless you pass `screenshot: true`; use the `screenshot` or
 `screenshot_annotated` tools when you actually need to see the page.
 
+`overflow` and `contrast` findings are measured facts (`kind: "violation"`);
+spacing, alignment, and radius findings are heuristics (`kind: "candidate"`)
+that can be false positives. Verify a candidate with `measure` before changing
+code.
+
+`overlay` also takes `focus`: the same selector `measure` returns. The rest of
+the page dims, the target is outlined and scrolled into view; `focus: null`
+clears it. Focusing scrolls the page, so a capture made afterwards records the
+scrolled viewport.
+
+`labels` returns the names the human pinned onto parts of the page through the
+toolbar. When the human refers to a part by name, look it up there instead of
+guessing a selector. Labels are read-only for the agent.
+
 ## Drivers
 
 The server prefers Playwright when `playwright-core` is installed. It launches

package/dist/extension/content.js

@@ -1,5 +1,73 @@
 "use strict";
 (() => {
+  // packages/extension/src/labels.ts
+  var STORE_KEY = "litedesign-labels";
+  function pageKey() {
+    return `${location.origin}${location.pathname}`;
+  }
+  function hasStorage() {
+    return typeof chrome !== "undefined" && chrome.storage?.local !== void 0;
+  }
+  function sanitize(value) {
+    if (!Array.isArray(value)) return [];
+    const labels = [];
+    for (const entry of value) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const record = entry;
+      if (typeof record.id !== "string" || record.id === "") continue;
+      if (typeof record.text !== "string" || record.text.trim() === "") continue;
+      if (typeof record.selector !== "string" || record.selector === "") continue;
+      labels.push({ id: record.id, text: record.text, selector: record.selector });
+    }
+    return labels;
+  }
+  async function readStore() {
+    if (!hasStorage()) return {};
+    try {
+      const stored = await chrome.storage.local.get(STORE_KEY);
+      const pages = stored[STORE_KEY];
+      return typeof pages === "object" && pages !== null ? pages : {};
+    } catch (error) {
+      console.warn("[litedesign] could not read labels", error);
+      return {};
+    }
+  }
+  async function writeStore(store) {
+    if (!hasStorage()) return;
+    try {
+      await chrome.storage.local.set({ [STORE_KEY]: store });
+    } catch (error) {
+      console.warn("[litedesign] could not save labels", error);
+    }
+  }
+  async function loadLabels() {
+    const store = await readStore();
+    return sanitize(store[pageKey()]);
+  }
+  async function replaceOnPage(next) {
+    const store = await readStore();
+    store[pageKey()] = next;
+    await writeStore(store);
+    return next;
+  }
+  async function addLabel(text, selector) {
+    const labels = await loadLabels();
+    const label = {
+      id: crypto.randomUUID(),
+      text: text.trim(),
+      selector
+    };
+    return replaceOnPage([...labels, label]);
+  }
+  async function removeLabel(id) {
+    const labels = await loadLabels();
+    return replaceOnPage(labels.filter((label) => label.id !== id));
+  }
+  async function renameLabel(id, text) {
+    const labels = await loadLabels();
+    return replaceOnPage(labels.map((label) => label.id === id ? { ...label, text } : label));
+  }
+
   // packages/extension/src/observer.ts
   var DEFAULT_DEBOUNCE = 150;
   function observeChanges(options) {
@@ -44,6 +112,8 @@
     guide: true,
     gap: true,
     issue: true,
+    dim: true,
+    focus: true,
     hover: true
   };
   var LAYERS = Object.keys(LAYER_NAMES);
@@ -51,45 +121,61 @@
     "grid",
     "guide",
     "gap",
-    "issue"
+    "issue",
+    "dim",
+    "focus"
   ];
+  var GRID_STEPS = [8, 12, 16, 24, 32, 48, 64, 96, 128];
 
   // packages/extension/src/store.ts
   var STORAGE_KEY = "litedesign";
   var DEFAULT_LAYERS = [...LAYERS];
+  var DEFAULT_GRID = { step: 8, axis: "both" };
+  var AXES = ["vertical", "horizontal", "both"];
   function defaultLayers() {
     return [...DEFAULT_LAYERS];
   }
   async function loadState() {
-    if (!hasStorage()) return { enabled: false, layers: defaultLayers() };
+    if (!hasStorage2())
+      return { enabled: false, layers: defaultLayers(), focus: null, grid: DEFAULT_GRID };
     try {
       const stored = await chrome.storage.local.get(STORAGE_KEY);
       return parseState(stored[STORAGE_KEY]);
     } catch (error) {
       console.warn("[litedesign] could not read preferences", error);
-      return { enabled: false, layers: defaultLayers() };
+      return { enabled: false, layers: defaultLayers(), focus: null, grid: DEFAULT_GRID };
     }
   }
   async function saveState(state) {
-    if (!hasStorage()) return;
+    if (!hasStorage2()) return;
     try {
       await chrome.storage.local.set({ [STORAGE_KEY]: state });
     } catch (error) {
       console.warn("[litedesign] could not save preferences", error);
     }
   }
-  function hasStorage() {
+  function hasStorage2() {
     return typeof chrome !== "undefined" && chrome.storage?.local !== void 0;
   }
   function parseState(value) {
     if (typeof value !== "object" || value === null) {
-      return { enabled: false, layers: defaultLayers() };
+      return { enabled: false, layers: defaultLayers(), focus: null, grid: DEFAULT_GRID };
     }
     const record = value;
     return {
       // A value written before this flag existed means "not known to be on".
       enabled: record.enabled === true,
-      layers: parseLayers(record.layers)
+      layers: parseLayers(record.layers),
+      focus: typeof record.focus === "string" && record.focus !== "" ? record.focus : null,
+      grid: parseGrid(record.grid)
+    };
+  }
+  function parseGrid(value) {
+    if (typeof value !== "object" || value === null) return DEFAULT_GRID;
+    const record = value;
+    return {
+      step: GRID_STEPS.includes(record.step) ? record.step : DEFAULT_GRID.step,
+      axis: AXES.includes(record.axis) ? record.axis : DEFAULT_GRID.axis
     };
   }
   function parseLayers(value) {
@@ -156,7 +242,79 @@
     background: #404040;
     color: #ffffff;
   }
+  .grid-group {
+    display: flex;
+    align-items: center;
+    gap: 2px;
+    padding-left: 6px;
+    margin-left: 2px;
+    border-left: 1px solid #404040;
+  }
+  .grid-group button {
+    padding: 4px 5px;
+    display: inline-flex;
+    align-items: center;
+  }
+  .grid-group svg {
+    display: block;
+  }
+  .grid-step {
+    padding: 0 3px;
+    color: #a3a3a3;
+    font-variant-numeric: tabular-nums;
+    min-width: 22px;
+    text-align: center;
+  }
+  .label-popup {
+    position: fixed;
+    box-sizing: border-box;
+    width: 164px;
+    padding: 4px;
+    border: 1px solid #d97706;
+    border-radius: 8px;
+    background: rgba(17, 17, 17, 0.96);
+    box-shadow: 0 6px 20px rgba(0, 0, 0, 0.28);
+    pointer-events: auto;
+    align-items: center;
+    gap: 4px;
+    display: none;
+  }
+  .label-popup input {
+    box-sizing: border-box;
+    flex: 1;
+    min-width: 0;
+    padding: 4px 6px;
+    border: 0;
+    border-radius: 5px;
+    background: #111111;
+    color: #e5e5e5;
+    font: inherit;
+  }
+  .label-popup button {
+    padding: 4px 7px;
+    border: 0;
+    border-radius: 5px;
+    background: #262626;
+    color: #d4d4d4;
+    font: inherit;
+    cursor: pointer;
+  }
+  .label-popup button:hover {
+    background: #7f1d1d;
+    color: #ffffff;
+  }
 `;
+  var LABEL_INPUT = { width: 164, height: 34 };
+  function placeInput(rect, viewport) {
+    const margin = 8;
+    const gap = 8;
+    const left = Math.min(
+      Math.max(rect.left, margin),
+      Math.max(margin, viewport.width - LABEL_INPUT.width - margin)
+    );
+    const above = rect.top > LABEL_INPUT.height + gap * 2;
+    return { left, top: above ? rect.top - gap : rect.bottom + gap, above };
+  }
   function createToolbar(options) {
     const root2 = document.createElement("div");
     root2.dataset.litedesignUi = "";
@@ -173,6 +331,48 @@
     let enabled = new Set(options.layers);
     const isEnabled = (layer) => enabled.has(layer);
     bar.append(brand, stats);
+    const labelButton = document.createElement("button");
+    labelButton.type = "button";
+    labelButton.dataset.action = "label";
+    labelButton.textContent = "label";
+    labelButton.title = "Mark a part of the page with a name the agent can read";
+    labelButton.addEventListener("click", () => options.onLabelToggle());
+    const popup = document.createElement("div");
+    popup.className = "label-popup";
+    const input = document.createElement("input");
+    input.type = "text";
+    input.placeholder = "label name";
+    const removeButton = document.createElement("button");
+    removeButton.type = "button";
+    removeButton.textContent = "\xD7";
+    removeButton.title = "Remove this label";
+    removeButton.hidden = true;
+    let committing = false;
+    let commit;
+    let remove;
+    const closeInput = () => {
+      popup.style.display = "none";
+    };
+    removeButton.addEventListener("mousedown", (event) => event.preventDefault());
+    removeButton.addEventListener("click", () => {
+      committing = true;
+      closeInput();
+      remove?.();
+    });
+    input.addEventListener("keydown", (event) => {
+      if (event.key === "Enter") {
+        committing = true;
+        const value = input.value;
+        closeInput();
+        commit?.(value);
+      } else if (event.key === "Escape") {
+        closeInput();
+      }
+    });
+    input.addEventListener("blur", () => {
+      if (!committing) closeInput();
+      committing = false;
+    });
     const buttons = /* @__PURE__ */ new Map();
     for (const layer of TOGGLE_LAYERS) {
       const button = document.createElement("button");
@@ -184,6 +384,60 @@
       buttons.set(layer, button);
       bar.append(button);
     }
+    let grid = options.grid;
+    const gridButtons = /* @__PURE__ */ new Map();
+    const line = (d) => `<svg width="11" height="11" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.5"><path d="${d}"/></svg>`;
+    const axes = [
+      ["vertical", "M3 1v10M9 1v10", "Grid: vertical lines only"],
+      ["horizontal", "M1 3h10M1 9h10", "Grid: horizontal lines only"],
+      ["both", "M3 1v10M9 1v10M1 3h10M1 9h10", "Grid: both directions"]
+    ];
+    const gridGroup = document.createElement("span");
+    gridGroup.className = "grid-group";
+    for (const [axis, path, title] of axes) {
+      const button = document.createElement("button");
+      button.type = "button";
+      button.dataset.axis = axis;
+      button.title = title;
+      button.innerHTML = line(path);
+      button.addEventListener("click", () => {
+        grid = { ...grid, axis };
+        setGrid(grid);
+        options.onGrid(grid);
+      });
+      gridButtons.set(axis, button);
+      gridGroup.append(button);
+    }
+    const stepLabel = document.createElement("span");
+    stepLabel.className = "grid-step";
+    const stepDown = document.createElement("button");
+    stepDown.type = "button";
+    stepDown.dataset.axis = "step-down";
+    stepDown.textContent = "\u2212";
+    stepDown.title = "Smaller grid spacing";
+    stepDown.addEventListener("click", () => {
+      const index = GRID_STEPS.indexOf(grid.step);
+      if (index > 0) {
+        grid = { ...grid, step: GRID_STEPS[index - 1] ?? grid.step };
+        setGrid(grid);
+        options.onGrid(grid);
+      }
+    });
+    const stepUp = document.createElement("button");
+    stepUp.type = "button";
+    stepUp.dataset.axis = "step-up";
+    stepUp.textContent = "+";
+    stepUp.title = "Larger grid spacing";
+    stepUp.addEventListener("click", () => {
+      const index = GRID_STEPS.indexOf(grid.step);
+      if (index !== -1 && index < GRID_STEPS.length - 1) {
+        grid = { ...grid, step: GRID_STEPS[index + 1] ?? grid.step };
+        setGrid(grid);
+        options.onGrid(grid);
+      }
+    });
+    gridGroup.append(stepDown, stepLabel, stepUp);
+    bar.append(labelButton, gridGroup);
     const close = document.createElement("button");
     close.type = "button";
     close.dataset.action = "close";
@@ -192,7 +446,8 @@
     close.setAttribute("aria-label", "Close litedesign");
     close.addEventListener("click", () => options.onClose());
     bar.append(close);
-    root2.append(style, bar);
+    popup.append(input, removeButton);
+    root2.append(style, bar, popup);
     const setLayers = (layers) => {
       enabled = new Set(layers);
       for (const [layer, button] of buttons) {
@@ -201,13 +456,43 @@
         button.classList.toggle("on", on);
       }
     };
+    const setGrid = (next) => {
+      grid = next;
+      for (const [axis, button] of gridButtons) {
+        const on = axis === grid.axis;
+        button.setAttribute("aria-pressed", String(on));
+        button.classList.toggle("on", on);
+      }
+      stepLabel.textContent = String(grid.step);
+    };
     setLayers(options.layers);
+    setGrid(grid);
     return {
       element: root2,
       setStats(nodes, issues, truncated) {
         stats.textContent = `${nodes} nodes \xB7 ${issues} issues${truncated ? " \xB7 truncated" : ""}`;
       },
-      setLayers
+      setLayers,
+      setGrid,
+      setLabelMode(on) {
+        labelButton.classList.toggle("on", on);
+        labelButton.setAttribute("aria-pressed", String(on));
+        if (!on) closeInput();
+      },
+      askLabel(rect, initial, fn, onRemove) {
+        commit = fn;
+        remove = onRemove;
+        committing = false;
+        const placement = placeInput(rect, { width: window.innerWidth, height: window.innerHeight });
+        popup.style.left = `${placement.left}px`;
+        popup.style.top = `${placement.top}px`;
+        popup.style.transform = placement.above ? "translateY(-100%)" : "none";
+        removeButton.hidden = onRemove === void 0;
+        popup.style.display = "flex";
+        input.value = initial;
+        input.focus();
+        if (initial !== "") input.select();
+      }
     };
   }
 
@@ -226,7 +511,7 @@
     const state = await loadState();
     if (window.__litedesign_state__ !== "starting") return;
     try {
-      mount(core2, state.layers);
+      mount(core2, state.layers, state.grid);
     } catch (error) {
       window.__litedesign_state__ = void 0;
       throw error;
@@ -235,28 +520,39 @@
   async function applyOverlay(core2, options) {
     if (!options.enabled) {
       window.__litedesign_teardown__?.();
-      return { enabled: false, layers: [] };
+      return { enabled: false, layers: [], focus: null };
     }
-    const layers = options.layers ?? (await loadState()).layers;
+    const stored = await loadState();
+    const layers = options.layers ?? stored.layers;
     if (window.__litedesign_state__ === "active") {
       window.__litedesign_layers__?.(layers);
-      return { enabled: true, layers };
-    }
-    window.__litedesign_state__ = "starting";
-    try {
-      mount(core2, layers);
-    } catch (error) {
-      window.__litedesign_state__ = void 0;
-      throw error;
+    } else {
+      window.__litedesign_state__ = "starting";
+      try {
+        mount(core2, layers, stored.grid);
+      } catch (error) {
+        window.__litedesign_state__ = void 0;
+        throw error;
+      }
     }
-    return { enabled: overlayHost() !== void 0, layers };
+    if (options.focus !== void 0) window.__litedesign_set_focus__?.(options.focus);
+    return {
+      enabled: overlayHost() !== void 0,
+      layers,
+      focus: window.__litedesign_focus_selector__?.() ?? null
+    };
   }
-  function mount(core2, initial) {
+  function mount(core2, initial, initialGrid) {
     const root2 = document.body ?? document.documentElement;
     let layers = initial;
+    let grid = initialGrid;
     let graph = core2.buildGraph(root2);
     let handle;
     let observer;
+    let focusSelector = null;
+    let focusId = null;
+    let labels = [];
+    let labelMode = false;
     let toolbar;
     const teardown = () => {
       observer?.stop();
@@ -264,13 +560,24 @@
       handle = void 0;
       observer = void 0;
       mountedHost = void 0;
+      focusSelector = null;
+      focusId = null;
+      if (labelMode) document.removeEventListener("click", onLabelClick, true);
+      labelMode = false;
       window.__litedesign_teardown__ = void 0;
       window.__litedesign_layers__ = void 0;
+      window.__litedesign_set_focus__ = void 0;
+      window.__litedesign_focus_selector__ = void 0;
       window.__litedesign_state__ = void 0;
-      void saveState({ enabled: false, layers });
+      void saveState({ enabled: false, layers, focus: null, grid });
     };
     const refresh = () => {
       graph = core2.buildGraph(root2);
+      if (focusId !== null && !graph.nodes.some((node) => node.id === focusId)) {
+        focusSelector = null;
+        focusId = null;
+        handle?.setFocus(null);
+      }
       handle?.update(graph);
       toolbar.setStats(graph.nodes.length, graph.issues.length, graph.truncated);
     };
@@ -278,25 +585,118 @@
       layers = next;
       handle?.setLayers(layers);
       toolbar.setLayers(layers);
-      void saveState({ enabled: true, layers });
+      void saveState({ enabled: true, layers, focus: focusSelector, grid });
+    };
+    const setGrid = (next) => {
+      grid = next;
+      handle?.setGrid(grid);
+      toolbar.setGrid(grid);
+      void saveState({ enabled: true, layers, focus: focusSelector, grid });
+    };
+    const setFocus = (selector) => {
+      if (selector === null) {
+        focusSelector = null;
+        focusId = null;
+        handle?.setFocus(null);
+        void saveState({ enabled: true, layers, focus: null, grid });
+        return;
+      }
+      const node = core2.resolveNode(graph, selector);
+      if (node === null) {
+        focusSelector = null;
+        focusId = null;
+        handle?.setFocus(null);
+        void saveState({ enabled: true, layers, focus: null, grid });
+        return;
+      }
+      focusSelector = node.selector;
+      focusId = node.id;
+      handle?.setFocus(node.id);
+      let element = null;
+      try {
+        element = document.querySelector(node.selector);
+      } catch {
+        element = null;
+      }
+      element?.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+      void saveState({ enabled: true, layers, focus: focusSelector, grid });
+    };
+    const applyMarks = () => {
+      handle?.setMarks(labels.map((label) => ({ selector: label.selector, text: label.text })));
+    };
+    const onLabelClick = (event) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+      if (target === handle?.host) return;
+      event.preventDefault();
+      event.stopPropagation();
+      const selector = core2.pathOf(target);
+      const existing = labels.find((label) => label.selector === selector);
+      if (existing !== void 0) {
+        toolbar.askLabel(
+          target.getBoundingClientRect(),
+          existing.text,
+          (text) => {
+            const trimmed = text.trim();
+            if (trimmed === "" || trimmed === existing.text) return;
+            void renameLabel(existing.id, trimmed).then((next) => {
+              labels = next;
+              applyMarks();
+            });
+          },
+          () => {
+            void removeLabel(existing.id).then((next) => {
+              labels = next;
+              applyMarks();
+            });
+          }
+        );
+        return;
+      }
+      toolbar.askLabel(target.getBoundingClientRect(), "", (text) => {
+        const trimmed = text.trim();
+        if (trimmed === "") return;
+        void addLabel(trimmed, selector).then((next) => {
+          labels = next;
+          applyMarks();
+        });
+      });
+    };
+    const toggleLabelMode = () => {
+      labelMode = !labelMode;
+      toolbar.setLabelMode(labelMode);
+      if (labelMode) {
+        document.addEventListener("click", onLabelClick, true);
+      } else {
+        document.removeEventListener("click", onLabelClick, true);
+      }
     };
     toolbar = createToolbar({
       layers,
+      grid,
       onToggle(layer, enabled) {
         setLayers(
           enabled ? [.../* @__PURE__ */ new Set([...layers, layer])] : layers.filter((name) => name !== layer)
         );
       },
+      onLabelToggle: toggleLabelMode,
+      onGrid: setGrid,
       onClose: teardown
     });
     toolbar.setStats(graph.nodes.length, graph.issues.length, graph.truncated);
-    handle = core2.render(graph, { layers, toolbar: toolbar.element });
+    handle = core2.render(graph, { layers, toolbar: toolbar.element, grid });
     observer = observeChanges({ root: root2, onChange: refresh });
+    void loadLabels().then((next) => {
+      labels = next;
+      applyMarks();
+    });
     mountedHost = handle.host;
     window.__litedesign_layers__ = setLayers;
+    window.__litedesign_set_focus__ = setFocus;
+    window.__litedesign_focus_selector__ = () => focusSelector;
     window.__litedesign_teardown__ = teardown;
     window.__litedesign_state__ = "active";
-    void saveState({ enabled: true, layers });
+    void saveState({ enabled: true, layers, focus: focusSelector, grid });
   }
 
   // packages/extension/src/bridge.ts
@@ -331,9 +731,12 @@
           ok: true,
           result: await applyOverlay(core2, {
             enabled: payload.enabled !== false,
-            layers: payload.layers
+            layers: payload.layers,
+            focus: payload.focus
           })
         };
+      case "labels":
+        return { ok: true, result: { labels: await loadLabels() } };
       case "graph":
         return { ok: true, result: core2.buildGraph(root()) };
       case "measure":
@@ -465,7 +868,7 @@
   async function restore(core2) {
     const state = await loadState();
     if (!state.enabled) return;
-    await applyOverlay(core2, { enabled: true, layers: state.layers });
+    await applyOverlay(core2, { enabled: true, layers: state.layers, focus: state.focus });
   }
 })();
 //# sourceMappingURL=content.js.map