@rahmantech/litedesign 0.1.0 → 0.2.1

package/dist/extension/core.iife.js

@@ -396,6 +396,7 @@ var __litedesign = (() => {
       selector: input.selector,
       rule: input.rule,
       severity: input.severity,
+      kind: input.kind,
       actual: input.actual,
       expected: input.expected,
       autoFix: input.autoFix
@@ -435,6 +436,7 @@ var __litedesign = (() => {
             selector: worst.node.id,
             key: spec.edge,
             severity: "P2",
+            kind: "candidate",
             actual: `${Math.round(worst.value * 10) / 10}px`,
             expected: `${Math.round(target.value * 10) / 10}px`,
             autoFix: false
@@ -465,6 +467,7 @@ var __litedesign = (() => {
           rule: "contrast",
           selector: node.id,
           severity: "P1",
+          kind: "violation",
           actual: `${Math.round(ratio * 100) / 100}:1`,
           expected: `>= ${minimum}:1`,
           autoFix: false
@@ -513,6 +516,7 @@ var __litedesign = (() => {
             selector: node.id,
             key: "x",
             severity: "P2",
+            kind: "violation",
             actual: `${node.box.scrollW}px content in ${node.box.clientW}px`,
             expected: "content fits horizontally",
             autoFix: false
@@ -526,6 +530,7 @@ var __litedesign = (() => {
             selector: node.id,
             key: "y",
             severity: "P2",
+            kind: "violation",
             actual: `${node.box.scrollH}px content in ${node.box.clientH}px`,
             expected: "content fits vertically",
             autoFix: false
@@ -564,6 +569,7 @@ var __litedesign = (() => {
             rule: "radius-consistency",
             selector: node.id,
             severity: "P3",
+            kind: "candidate",
             actual: value,
             expected: expectedValue,
             autoFix: true
@@ -602,6 +608,7 @@ var __litedesign = (() => {
           selector: gap.a,
           key: `${gap.axis}:${gap.b}`,
           severity: "P2",
+          kind: "candidate",
           actual: `${actual}px`,
           expected: `${Math.round(actual / SPACING_SCALE) * SPACING_SCALE}px`,
           autoFix: true
@@ -756,7 +763,7 @@ var __litedesign = (() => {
   }
 
   // packages/core/src/render/layers.ts
-  var LAYERS = ["grid", "guide", "gap", "issue", "hover"];
+  var LAYERS = ["grid", "guide", "gap", "issue", "dim", "focus", "hover"];
   var GUIDE_COLOR = {
     left: "rgba(236, 72, 153, 0.55)",
     right: "rgba(236, 72, 153, 0.55)",
@@ -785,16 +792,28 @@ var __litedesign = (() => {
     }
     return layers;
   }
-  function drawGrid(layer) {
+  function gridBackground(step, axis) {
+    const line = "rgba(59, 130, 246, 0.16)";
+    const vertical = `repeating-linear-gradient(to right, ${line} 0 1px, transparent 1px ${step}px)`;
+    const horizontal = `repeating-linear-gradient(to bottom, ${line} 0 1px, transparent 1px ${step}px)`;
+    if (axis === "vertical") return vertical;
+    if (axis === "horizontal") return horizontal;
+    return `${vertical}, ${horizontal}`;
+  }
+  function drawGrid(layer, grid) {
     layer.replaceChildren();
-    layer.style.backgroundImage = `repeating-linear-gradient(to right, rgba(59, 130, 246, 0.16) 0 1px, transparent 1px ${GRID_STEP}px)`;
+    layer.style.backgroundImage = gridBackground(grid.step, grid.axis);
+  }
+  function focusedGuides(graph, focus) {
+    if (focus === null) return graph.guides;
+    return graph.guides.filter((guide) => guide.members.includes(focus.id));
   }
-  function drawGuides(layer, graph) {
+  function drawGuides(layer, graph, focus = null) {
     layer.replaceChildren();
     const byId = new Map(graph.nodes.map((node) => [node.id, node]));
     const scrollX = window.scrollX;
     const scrollY = window.scrollY;
-    for (const guide of graph.guides.slice(0, MAX_MARKERS)) {
+    for (const guide of focusedGuides(graph, focus).slice(0, MAX_MARKERS)) {
       const span = spanOf(guide, byId);
       if (span === null) continue;
       const color = GUIDE_COLOR[guide.edge];
@@ -901,6 +920,147 @@ var __litedesign = (() => {
   }
   var HOVER_BORDER = "rgba(59, 130, 246, 0.9)";
   var HOVER_FILL = "rgba(59, 130, 246, 0.08)";
+  var FOCUS_DIM = "rgba(15, 23, 42, 0.55)";
+  var FOCUS_BORDER = "#3b82f6";
+  var SVG_NS = "http://www.w3.org/2000/svg";
+  var MIN_RADIUS = 4;
+  var TANGENT_COLOR = "rgba(148, 163, 184, 0.9)";
+  function parseRadius(css, rect) {
+    const text = css.trim();
+    if (text === "" || text.includes("/")) return null;
+    const parts = text.split(/\s+/);
+    if (parts.length > 4) return null;
+    const values = [];
+    for (const part of parts) {
+      const resolved = part.endsWith("%") ? Math.min(rect.w, rect.h) * (Number.parseFloat(part) / 100) : Number.parseFloat(part);
+      if (!Number.isFinite(resolved) || resolved < 0) return null;
+      values.push(resolved);
+    }
+    const [first = 0, second = first, third = first, fourth = second] = values;
+    const clamp = (radius) => Math.min(radius, rect.w / 2, rect.h / 2);
+    return {
+      tl: clamp(first),
+      tr: clamp(second),
+      br: clamp(third),
+      bl: clamp(fourth)
+    };
+  }
+  function radiusGeometry(rect, radii) {
+    const specs = [
+      { corner: "tl", r: radii.tl, x: rect.x, y: rect.y, sx: 1, sy: 1 },
+      { corner: "tr", r: radii.tr, x: rect.x + rect.w, y: rect.y, sx: -1, sy: 1 },
+      { corner: "br", r: radii.br, x: rect.x + rect.w, y: rect.y + rect.h, sx: -1, sy: -1 },
+      { corner: "bl", r: radii.bl, x: rect.x, y: rect.y + rect.h, sx: 1, sy: -1 }
+    ];
+    const marks = [];
+    for (const spec of specs) {
+      if (spec.r < MIN_RADIUS) continue;
+      const hx = spec.x + spec.sx * spec.r;
+      const hy = spec.y;
+      const vx = spec.x;
+      const vy = spec.y + spec.sy * spec.r;
+      const sweep = spec.sx * spec.sy === 1 ? 0 : 1;
+      marks.push({
+        corner: spec.corner,
+        radius: spec.r,
+        arc: `M ${hx} ${hy} A ${spec.r} ${spec.r} 0 0 ${sweep} ${vx} ${vy}`,
+        tangents: [
+          [spec.x, spec.y, hx, hy],
+          [spec.x, spec.y, vx, vy]
+        ]
+      });
+    }
+    return marks;
+  }
+  function createSubLayer(name, before) {
+    const layer = document.createElement("div");
+    layer.dataset.layer = name;
+    layer.style.cssText = `${BASE};inset:0`;
+    before.before(layer);
+    return layer;
+  }
+  var MARK_COLOR = "rgba(217, 119, 6, 0.95)";
+  function drawMarks(layer, marks, bySelector, interactive = false) {
+    layer.replaceChildren();
+    const badges = /* @__PURE__ */ new Map();
+    if (marks.length === 0) return badges;
+    const scrollX = window.scrollX;
+    const scrollY = window.scrollY;
+    for (const mark of marks) {
+      const node = bySelector.get(mark.selector);
+      if (node === void 0) continue;
+      const badge = box(
+        layer,
+        `left:${node.rect.x - scrollX}px;top:${node.rect.y - scrollY}px;transform:translateY(-100%);padding:2px 6px;border-radius:4px;background:${MARK_COLOR};color:#fff;font:10px/1.4 ui-monospace,monospace;white-space:nowrap` + (interactive ? ";pointer-events:auto;cursor:pointer" : "")
+      );
+      badge.textContent = mark.text;
+      badges.set(badge, mark);
+    }
+    return badges;
+  }
+  function drawRadius(layer, node) {
+    layer.replaceChildren();
+    if (node === null) return;
+    const radii = parseRadius(node.styles.borderRadius, node.rect);
+    if (radii === null) return;
+    const view = {
+      x: node.rect.x - window.scrollX,
+      y: node.rect.y - window.scrollY,
+      w: node.rect.w,
+      h: node.rect.h
+    };
+    const marks = radiusGeometry(view, radii);
+    if (marks.length === 0) return;
+    const svg = document.createElementNS(SVG_NS, "svg");
+    svg.style.cssText = `${BASE};inset:0;width:100%;height:100%`;
+    for (const mark of marks) {
+      const arc = document.createElementNS(SVG_NS, "path");
+      arc.setAttribute("d", mark.arc);
+      arc.setAttribute("fill", "none");
+      arc.setAttribute("stroke", GAP_COLOR);
+      arc.setAttribute("stroke-width", "2");
+      svg.append(arc);
+      for (const [x1, y1, x2, y2] of mark.tangents) {
+        const line = document.createElementNS(SVG_NS, "line");
+        line.setAttribute("x1", String(x1));
+        line.setAttribute("y1", String(y1));
+        line.setAttribute("x2", String(x2));
+        line.setAttribute("y2", String(y2));
+        line.setAttribute("stroke", TANGENT_COLOR);
+        line.setAttribute("stroke-width", "1");
+        line.setAttribute("stroke-dasharray", "3 3");
+        svg.append(line);
+      }
+    }
+    layer.append(svg);
+    const labeled = marks.every((mark) => mark.radius === marks[0]?.radius) ? marks.slice(0, 1) : marks;
+    for (const mark of labeled) {
+      const inset = mark.radius * 0.55;
+      const x = mark.corner === "tr" || mark.corner === "br" ? view.x + view.w - inset : view.x + inset;
+      const y = mark.corner === "br" || mark.corner === "bl" ? view.y + view.h - inset : view.y + inset;
+      label(layer, `${round(mark.radius, 1)}px`, x, y);
+    }
+  }
+  function dimStyle(rect, scroll) {
+    const left = rect.x - scroll.x;
+    const top = rect.y - scroll.y;
+    return `left:${left}px;top:${top}px;width:${rect.w}px;height:${rect.h}px;box-shadow:0 0 0 9999px ${FOCUS_DIM}`;
+  }
+  function outlineStyle(rect, scroll) {
+    const left = rect.x - scroll.x;
+    const top = rect.y - scroll.y;
+    return `left:${left}px;top:${top}px;width:${rect.w}px;height:${rect.h}px;border:2px solid ${FOCUS_BORDER};border-radius:2px`;
+  }
+  function drawDim(layer, node) {
+    layer.replaceChildren();
+    if (node === null) return;
+    box(layer, dimStyle(node.rect, { x: window.scrollX, y: window.scrollY }));
+  }
+  function drawFocus(layer, node) {
+    layer.replaceChildren();
+    if (node === null) return;
+    box(layer, outlineStyle(node.rect, { x: window.scrollX, y: window.scrollY }));
+  }
   function drawHover(layer, node) {
     layer.replaceChildren();
     if (node === null) return;
@@ -958,6 +1118,21 @@ var __litedesign = (() => {
     printStyle.textContent = "@media print { :host { display: none !important } }";
     shadow.append(printStyle);
     const layers = createLayers(shadow);
+    const radiusLayer = createSubLayer("radius", layers.hover);
+    const marksLayer = createSubLayer("marks", layers.hover);
+    if (options.onMarkClick !== void 0) {
+      const onMarkClick = options.onMarkClick;
+      marksLayer.addEventListener("click", (event) => {
+        if (!marksInteractive) return;
+        const badge = event.target;
+        if (!(badge instanceof HTMLDivElement)) return;
+        const mark = badgeMarks.get(badge);
+        if (mark === void 0) return;
+        event.preventDefault();
+        event.stopPropagation();
+        onMarkClick(mark, badge.getBoundingClientRect());
+      });
+    }
     if (options.toolbar !== void 0) shadow.append(options.toolbar);
     document.documentElement.append(host);
     let current = graph;
@@ -965,17 +1140,34 @@ var __litedesign = (() => {
     let hovered = null;
     let hoverTarget = null;
     let hoverFrame = 0;
+    let focusId = null;
     let visible = new Set(options.layers ?? LAYERS);
+    let marks = options.marks ?? [];
+    let marksInteractive = false;
+    let badgeMarks = /* @__PURE__ */ new Map();
+    let grid = options.grid ?? { step: GRID_STEP, axis: "both" };
     let frame = 0;
     const draw = () => {
       frame = 0;
       for (const name of LAYERS) {
         layers[name].style.display = visible.has(name) ? "block" : "none";
       }
-      drawGrid(layers.grid);
-      drawGuides(layers.guide, current);
+      drawGrid(layers.grid, grid);
       drawGaps(layers.gap, current);
       drawIssues(layers.issue, current);
+      const focused = focusId === null ? null : byId.get(focusId) ?? null;
+      drawGuides(layers.guide, current, focused);
+      const outlineNode = visible.has("focus") ? focused : null;
+      const dimNode = visible.has("dim") ? focused : null;
+      drawDim(layers.dim, dimNode);
+      drawFocus(layers.focus, outlineNode);
+      drawRadius(radiusLayer, outlineNode);
+      badgeMarks = drawMarks(
+        marksLayer,
+        marks,
+        new Map(current.nodes.map((node) => [node.selector, node])),
+        marksInteractive
+      );
       drawHover(layers.hover, hovered === null ? null : byId.get(hovered) ?? null);
     };
     const schedule = () => {
@@ -1020,12 +1212,26 @@ var __litedesign = (() => {
       update(next) {
         current = next;
         byId = indexNodes(next);
+        if (focusId !== null && !byId.has(focusId)) focusId = null;
         draw();
       },
       setLayers(names) {
         visible = new Set(names);
         draw();
       },
+      setFocus(id) {
+        focusId = id;
+        draw();
+      },
+      setMarks(next, interactive = false) {
+        marks = next;
+        marksInteractive = interactive;
+        draw();
+      },
+      setGrid(next) {
+        grid = next;
+        draw();
+      },
       destroy() {
         if (frame !== 0) cancelAnimationFrame(frame);
         if (hoverFrame !== 0) cancelAnimationFrame(hoverFrame);
@@ -1042,7 +1248,7 @@ var __litedesign = (() => {
   }
 
   // packages/core/src/index.ts
-  var VERSION = "0.1.0";
+  var VERSION = "0.2.1";
   return __toCommonJS(index_exports);
 })();
 //# sourceMappingURL=core.iife.js.map

package/dist/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "litedesign",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Grid, gap, and alignment on the real web page.",
   "permissions": ["activeTab", "scripting", "storage"],
   "host_permissions": ["http://*/*", "https://*/*"],

package/dist/extension/sw.js

@@ -205,6 +205,7 @@ async function route(action, payload) {
     case "graph":
     case "measure":
     case "overlay":
+    case "labels":
       return toTab(action, payload);
     case "screenshot":
       return capture("screenshot_prepare", payload);

package/dist/index.js

@@ -44,7 +44,7 @@ function isMode(value) {
 }
 
 // packages/cli/src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.1";
 
 // packages/cli/src/ws.ts
 import { spawn } from "node:child_process";
@@ -371,7 +371,10 @@ var Hub = class _Hub {
     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);
+      if (old?.socket === socket) {
+        this.#clients.delete(previous);
+        this.#broadcast({ type: "page-gone", tabId: previous });
+      }
     }
     this.#clients.set(tabId, { ...page, socket });
     this.#socketTab.set(socket, tabId);
@@ -1096,6 +1099,7 @@ function issue(input) {
     selector: input.selector,
     rule: input.rule,
     severity: input.severity,
+    kind: input.kind,
     actual: input.actual,
     expected: input.expected,
     autoFix: input.autoFix
@@ -1133,6 +1137,7 @@ var alignmentNearMiss = defineRule("alignment-near-miss", (graph) => {
           selector: worst.node.id,
           key: spec.edge,
           severity: "P2",
+          kind: "candidate",
           actual: `${Math.round(worst.value * 10) / 10}px`,
           expected: `${Math.round(target.value * 10) / 10}px`,
           autoFix: false
@@ -1161,6 +1166,7 @@ var contrastMinimum = defineRule("contrast", (graph) => {
         rule: "contrast",
         selector: node.id,
         severity: "P1",
+        kind: "violation",
         actual: `${Math.round(ratio * 100) / 100}:1`,
         expected: `>= ${minimum}:1`,
         autoFix: false
@@ -1207,6 +1213,7 @@ var overflowClipped = defineRule("overflow", (graph) => {
           selector: node.id,
           key: "x",
           severity: "P2",
+          kind: "violation",
           actual: `${node.box.scrollW}px content in ${node.box.clientW}px`,
           expected: "content fits horizontally",
           autoFix: false
@@ -1220,6 +1227,7 @@ var overflowClipped = defineRule("overflow", (graph) => {
           selector: node.id,
           key: "y",
           severity: "P2",
+          kind: "violation",
           actual: `${node.box.scrollH}px content in ${node.box.clientH}px`,
           expected: "content fits vertically",
           autoFix: false
@@ -1256,6 +1264,7 @@ var radiusConsistency = defineRule("radius-consistency", (graph) => {
           rule: "radius-consistency",
           selector: node.id,
           severity: "P3",
+          kind: "candidate",
           actual: value,
           expected: expectedValue,
           autoFix: true
@@ -1292,6 +1301,7 @@ var spacingScale = defineRule("spacing-scale", (graph) => {
         selector: gap.a,
         key: `${gap.axis}:${gap.b}`,
         severity: "P2",
+        kind: "candidate",
         actual: `${actual}px`,
         expected: `${Math.round(actual / SPACING_SCALE) * SPACING_SCALE}px`,
         autoFix: true
@@ -1308,7 +1318,7 @@ var defaultRules = [
   contrastMinimum
 ];
 var RULE_IDS = defaultRules.map((rule) => rule.id);
-var LAYERS = ["grid", "guide", "gap", "issue", "hover"];
+var LAYERS = ["grid", "guide", "gap", "issue", "dim", "focus", "hover"];
 
 // packages/cli/src/drivers/extension.ts
 var ExtensionDriver = class {
@@ -1359,6 +1369,21 @@ var ExtensionDriver = class {
     }
     return result;
   }
+  async labels() {
+    const result = await this.#request("labels");
+    if (result === void 0) {
+      throw new ToolError(
+        "the extension did not report labels. Reload the litedesign extension at chrome://extensions, then try again."
+      );
+    }
+    const labels = [];
+    for (const entry of result.labels ?? []) {
+      if (typeof entry.text === "string" && typeof entry.selector === "string") {
+        labels.push({ label: entry.text, selector: entry.selector });
+      }
+    }
+    return labels;
+  }
   async close() {
   }
   #request(action, payload) {
@@ -1493,22 +1518,46 @@ var PlaywrightDriver = class {
     );
     return page.screenshot({ type: "png" });
   }
+  /**
+   * Labels are marks the human makes through the toolbar; a headless page has
+   * no human in it, so there is nothing to read.
+   */
+  async labels() {
+    return [];
+  }
   async overlay(options) {
     const page = await this.#requirePage();
     await this.#inject(page);
     const layers = options.enabled ? options.layers ?? [...LAYERS] : [];
-    await page.evaluate(
+    const result = await page.evaluate(
       (input) => {
         const target = window;
         target.__litedesign_handle__?.destroy();
         target.__litedesign_handle__ = void 0;
-        if (!input.enabled) return;
+        if (!input.enabled) {
+          target.__litedesign_focus__ = null;
+          return { enabled: false, layers: [], focus: null };
+        }
         const graph = target.__litedesign.buildGraph(document.body);
-        target.__litedesign_handle__ = target.__litedesign.render(graph, { layers: input.layers });
+        const handle = target.__litedesign.render(graph, { layers: input.layers });
+        target.__litedesign_handle__ = handle;
+        if (input.focus !== void 0) target.__litedesign_focus__ = input.focus;
+        let focus = null;
+        const wanted = input.focus !== void 0 ? input.focus : target.__litedesign_focus__ ?? null;
+        if (wanted !== null) {
+          const node = target.__litedesign.resolveNode(graph, wanted);
+          if (node !== null) {
+            handle.setFocus(node.id);
+            focus = node.selector;
+            const element = document.querySelector(node.selector);
+            element?.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+          }
+        }
+        return { enabled: true, layers: input.layers, focus };
       },
-      { enabled: options.enabled, layers }
+      { enabled: options.enabled, layers, focus: options.focus }
     );
-    return { enabled: options.enabled, layers };
+    return result;
   }
   async close() {
     await this.#context?.close().catch(() => void 0);
@@ -1741,12 +1790,20 @@ function formatTree(graph, maxLines = MAX_TREE_LINES) {
   }
   return lines.join("\n");
 }
+function labelsSummary(marks) {
+  const names = [];
+  for (const mark of marks) {
+    if (!names.includes(mark.label)) names.push(mark.label);
+  }
+  return { count: marks.length, names };
+}
 function issuePayload(issues, limit) {
   return {
     issues: issues.slice(0, limit).map((issue2) => ({
       selector: issue2.selector,
       rule: issue2.rule,
       severity: issue2.severity,
+      kind: issue2.kind,
       actual: issue2.actual,
       expected: issue2.expected,
       autoFix: issue2.autoFix
@@ -1817,6 +1874,7 @@ async function inspectTool(input) {
     throw error;
   }
   const graph = await driver.graph();
+  const labels = labelsSummary(await driver.labels());
   const payload = {
     status: "ready",
     url: graph.url,
@@ -1824,7 +1882,8 @@ async function inspectTool(input) {
     summary: {
       nodes: graph.nodes.length,
       issues: graph.issues.length,
-      truncated: graph.truncated
+      truncated: graph.truncated,
+      labels
     },
     tree: formatTree(graph)
   };
@@ -1833,6 +1892,16 @@ async function inspectTool(input) {
   return imageResult(payload, image);
 }
 
+// packages/cli/src/mcp/tools/labels.ts
+async function labelsTool() {
+  const driver = requirePage();
+  const labels = await driver.labels();
+  return textResult({
+    labels,
+    count: labels.length
+  });
+}
+
 // packages/cli/src/mcp/tools/measure.ts
 async function measureTool(input) {
   const measured = await requirePage().measure(input.selector);
@@ -1844,10 +1913,11 @@ async function overlayTool(input) {
   const driver = requirePage();
   const enabled = input.enabled !== false;
   const layers = parseLayers(input.layers);
-  const result = await driver.overlay({ enabled, layers });
+  const result = await driver.overlay({ enabled, layers, focus: input.focus });
   return textResult({
     status: result.enabled ? "shown" : "hidden",
-    layers: result.layers
+    layers: result.layers,
+    focus: result.focus
   });
 }
 function parseLayers(requested) {
@@ -1876,6 +1946,17 @@ async function screenshotAnnotatedTool(input) {
   return imageResult({ ...pngSize(image), bytes: image.length }, image);
 }
 
+// packages/cli/src/mcp/workflow.ts
+var WORKFLOW_URI = "skill://litedesign/workflow";
+var WORKFLOW_TEXT = `# litedesign workflow
+
+- Call \`inspect\` first, always. Its summary includes the labels the human pinned on the page.
+- If the human refers to a part of the page by name ("the login button", "the altcha box"), call \`labels\` and use the pinned selector \u2014 never guess CSS selectors.
+- Labels are read-only: you read them; the human creates, renames, and removes them.
+- To show the human what you are editing, call \`overlay\` with \`focus\`. Set \`layers\` once at the start if needed; after that, send \`focus\` only \u2014 the human owns the layer toggles in the toolbar.
+- Findings carry kind: "violation" is a measured fact; "candidate" is a heuristic that can be a false positive \u2014 verify it with \`measure\` before changing code.
+`;
+
 // packages/cli/src/mcp/server.ts
 async function guard(run2) {
   try {
@@ -1899,6 +1980,18 @@ async function runMcpServer() {
     console.error(`[litedesign] extension bridge disabled: ${reason}`);
   }
   const server = new McpServer({ name: "litedesign", version: VERSION });
+  server.registerResource(
+    "workflow",
+    WORKFLOW_URI,
+    {
+      title: "Workflow",
+      description: "How the agent should work with this server: inspect first, resolve the human's names through labels, spotlight edits with focus.",
+      mimeType: "text/markdown"
+    },
+    async () => ({
+      contents: [{ uri: WORKFLOW_URI, text: WORKFLOW_TEXT, mimeType: "text/markdown" }]
+    })
+  );
   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")
@@ -1931,7 +2024,7 @@ async function runMcpServer() {
     "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.',
+      description: 'Open a page and return a tree summary. Call this before measure, find_issues, overlay, screenshot, or screenshot_annotated. The summary includes labels: the count and unique names the human pinned onto parts of the page \u2014 when the human refers to a part by name, get its selector from the labels tool. The full workflow is available as the resource skill://litedesign/workflow. 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,
@@ -1968,7 +2061,7 @@ async function runMcpServer() {
     "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.",
+      description: 'Run layout rules on the open page and return findings. Each finding carries kind: "violation" is a measured fact (overflow, contrast below WCAG); "candidate" is a heuristic judgment (spacing scale, near-miss alignment, radius consistency) that can be a false positive \u2014 verify it with measure before changing code. 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)")
@@ -1980,14 +2073,26 @@ async function runMcpServer() {
     "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.",
+      description: "Show or hide the measurement overlay in the page the human is looking at: grid, guides, gap labels, and issue boxes. Use focus to spotlight the component you are editing: the rest of the page dims, the target is outlined, and it scrolls to the viewport center \u2014 so the human sees exactly what you are changing. focus takes the same selector measure returns; null clears it. Set layers once at the start if you need specific ones; after that call with focus only \u2014 the human owns the layer toggles in the toolbar, and your calls must not override their choice. 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(", ")}`)
+        layers: z.array(z.string()).optional().describe(`Layers to draw. Default: all. Valid: ${LAYERS.join(", ")}`),
+        focus: z.string().nullish().describe(
+          "Selector of the component to spotlight (same format as measure). null clears the focus. Omit to leave it unchanged. Focusing scrolls the page, which changes what a later screenshot captures."
+        )
       }
     },
     async (input) => guard(() => overlayTool(input))
   );
+  server.registerTool(
+    "labels",
+    {
+      title: "Labels",
+      description: "Read the names the human pinned onto parts of the page through the toolbar label button. Each entry maps a human name to a selector you can pass to measure, find_issues, or overlay focus. When the human refers to a part by name, look it up here instead of guessing a selector. Labels are the human's marks: read-only for you. Returns an empty list when nothing is pinned yet.",
+      inputSchema: {}
+    },
+    async () => guard(() => labelsTool())
+  );
   server.registerTool(
     "screenshot",
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rahmantech/litedesign",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Grid, gap, and alignment on the real web page, plus an MCP bridge for agents.",
   "license": "Apache-2.0",
   "author": "Muhammad Abdurrahman",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist",
+    "!dist/**/*.map",
     "README.md"
   ],
   "engines": {
@@ -21,7 +22,7 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@litedesign/core": "0.1.0",
+    "@litedesign/core": "0.2.1",
     "@types/ws": "^8.18.2"
   },
   "publishConfig": {