@patrizzos/stylespeak 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stylespeak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# StyleSpeak
+
+A companion MCP server and CLI to [stylesafe](https://www.npmjs.com/package/stylesafe) that makes CSS legible to AI agents — resolving cascade, tracing properties, and explaining what applies and why before an agent touches a single line of styles.
+
+## The problem
+
+AI coding agents write CSS without being able to see its effect. They modify a rule, assume it worked, and move on — unaware that a higher-specificity rule elsewhere already overrides it, or that a combinator rule in another file is silently winning. stylespeak gives agents a structured knowledge layer to consult *before* making changes.
+
+## What it does
+
+**`resolve_styles`** — answers "what CSS actually applies to this selector?"
+
+Given a selector and a set of files, returns every CSS property the selector would receive, which rule wins for each, and which rules were overridden — with confidence levels since no real DOM is available.
+
+**`trace_property`** — answers "everywhere this property is set, who wins?"
+
+Given a property name and a set of files, returns every rule that sets it, groups competing rules that target overlapping selectors, and shows the full cascade chain for each group. Use this to understand the blast radius of a change before making it.
+
+## Quick start
+
+### As a CLI tool
+
+```bash
+npm install -g stylespeak
+```
+
+Resolve what applies to a selector:
+```bash
+stylespeak resolve ".btn.primary" src/styles/main.css
+stylespeak resolve "#header a" src/styles/base.css src/styles/header.css
+stylespeak resolve ".card-title" --projectRoot src/styles
+```
+
+Trace a property across files:
+```bash
+stylespeak trace "color" src/styles/main.css
+stylespeak trace "background-color" --projectRoot src/styles
+```
+
+### As an MCP server
+
+Add to your MCP client config (Cursor: `.cursor/mcp.json`, VS Code: `.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "stylespeak": {
+      "command": "node",
+      "args": ["/absolute/path/to/stylespeak/src/server.js"]
+    }
+  }
+}
+```
+
+Once connected, agents can call:
+- `resolve_styles({ selector, files, projectRoot })`
+- `trace_property({ property, files, projectRoot })`
+
+## Example output
+
+```bash
+stylespeak resolve ".btn.primary" src/styles/buttons.css
+```
+
+```json
+{
+  "query": { "selector": ".btn.primary", "filesAnalyzed": ["buttons.css"] },
+  "properties": {
+    "background-color": {
+      "winner": {
+        "value": "darkblue",
+        "selector": ".btn.primary",
+        "specificity": "(0,0,2,0)",
+        "source": { "file": "buttons.css", "line": 9 }
+      },
+      "overridden": [
+        {
+          "value": "blue",
+          "selector": ".btn",
+          "specificity": "(0,0,1,0)",
+          "reason": "lower specificity"
+        }
+      ],
+      "confidence": "certain"
+    }
+  },
+  "summary": "Found 6 properties applying to \".btn.primary\" from 5 matched rule(s).",
+  "agentNote": "1 property is certain. 2 properties are likely. 3 properties are possible (combinator rules — depends on DOM context). 3 properties have overridden rules — review before modifying."
+}
+```
+
+## Confidence levels
+
+Since stylespeak performs static analysis without a real DOM, every resolved property carries a confidence level:
+
+| Level | Meaning |
+|---|---|
+| `certain` | Exact selector match — rule definitively applies |
+| `likely` | Rule tokens are a subset of the queried selector — applies in most cases |
+| `possible` | Combinator rule (e.g. `.sidebar .btn`) — depends on DOM ancestry, unknown without rendering |
+
+An agent should treat `certain` and `likely` results as ground truth, and `possible` results as conditional — they may apply depending on where the element lives in the DOM.
+
+## Use cases
+
+- **Before editing styles** — call `resolve_styles` to understand the full cascade context first
+- **Before changing a property** — call `trace_property` to see the blast radius across all files
+- **Debugging "why isn't my CSS working"** — trace the property to find the higher-specificity rule that's winning
+- **Style audits** — run across a project directory to map what's actually applying where
+
+## CLI options
+
+Both commands accept:
+- One or more file paths as positional arguments
+- `--projectRoot <dir>` to analyze all CSS/SCSS files in a directory recursively
+
+```bash
+stylespeak resolve ".btn" src/main.css src/components.css
+stylespeak trace "padding" --projectRoot src/styles
+```
+
+## How it pairs with stylesafe
+
+**stylesafe** catches problems in your CSS — conflicts, dead rules, Tailwind clashes — before they ship.
+
+**stylespeak** explains your CSS — resolving cascade, tracing properties, mapping what applies and why — so agents understand before they act.
+
+Use stylesafe as a post-edit check. Use stylespeak as a pre-edit consultation. Together they give AI coding agents a complete feedback loop on styles.
+
+## GitHub Actions
+
+```yaml
+name: style check
+
+on: [pull_request]
+
+jobs:
+  stylespeak:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install -g stylespeak
+      - run: stylespeak trace "color" --projectRoot src/styles
+```
+
+## Architecture
+
+```
+src/
+  cssParser.js        — dependency-free CSS tokenizer with line number tracking
+  specificity.js      — standard (id, class, type) specificity calculator
+  cssomBuilder.js     — builds in-memory cascade model from multiple files
+  selectorMatcher.js  — heuristic selector matching with confidence levels
+  resolveStyles.js    — resolve_styles tool implementation
+  traceProperty.js    — trace_property tool implementation
+  server.js           — MCP server (stdio JSON-RPC) + CLI entry point
+```
+
+Zero external dependencies. Requires Node.js 18+.
+
+## Roadmap
+
+- **v0.2** — CSS custom property (variable) resolution, CSS Modules scope awareness
+- **v0.3** — AST component graph analysis for more accurate selector matching without a DOM
+- **v1.0** — Chrome DevTools Protocol integration for live cascade resolution against a running browser

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@patrizzos/stylespeak",
+  "mcpName": "io.github.Patrizzos/stylespeak",
+  "version": "0.1.0",
+  "description": "MCP server and CLI that makes CSS legible to AI agents — resolves cascade, traces properties, explains what applies and why.",
+  "main": "src/server.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Patrizzos/stylespeak.git"
+  },
+  "bin": {
+    "stylespeak": "src/server.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node test/run.js"
+  },
+  "keywords": ["mcp", "css", "tailwind", "cascade", "agent", "ai", "devtools"],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/cssParser.js

@@ -0,0 +1,100 @@
+/**
+ * CSS Parser for stylescope.
+ * Improved over stylesafe's version with:
+ *  - Line number tracking for every rule (for source location in output)
+ *  - At-rule context preservation (@media, @layer, @supports)
+ *  - Returns { rules } where each rule has { selectors, declarations, source: { file, line }, mediaContext }
+ */
+
+function stripComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, match => match.replace(/[^\n]/g, ' '));
+}
+
+function getLineNumber(text, index) {
+  return text.slice(0, index).split('\n').length;
+}
+
+function parseDeclarations(block) {
+  const decls = [];
+  const parts = block.split(';');
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx === -1) continue;
+    const prop = trimmed.slice(0, colonIdx).trim().toLowerCase();
+    let value = trimmed.slice(colonIdx + 1).trim();
+    if (!prop) continue;
+    const important = /!important\s*$/i.test(value);
+    if (important) value = value.replace(/!important\s*$/i, '').trim();
+    decls.push({ prop, value, important });
+  }
+  return decls;
+}
+
+function findMatchingBrace(css, openIdx) {
+  let depth = 1;
+  let i = openIdx + 1;
+  while (i < css.length && depth > 0) {
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}') depth--;
+    i++;
+  }
+  return i - 1;
+}
+
+function parseCSS(cssText, filename = '<input>') {
+  const css = stripComments(cssText);
+  const rules = [];
+  let i = 0;
+  const atStack = [];
+
+  while (i < css.length) {
+    while (i < css.length && /\s/.test(css[i])) i++;
+    if (i >= css.length) break;
+
+    if (css[i] === '@') {
+      const braceIdx = css.indexOf('{', i);
+      const semiIdx = css.indexOf(';', i);
+      if (braceIdx === -1 || (semiIdx !== -1 && semiIdx < braceIdx)) {
+        i = semiIdx === -1 ? css.length : semiIdx + 1;
+        continue;
+      }
+      const atHeader = css.slice(i, braceIdx).trim();
+      atStack.push(atHeader);
+      i = braceIdx + 1;
+      continue;
+    }
+
+    if (css[i] === '}') {
+      if (atStack.length > 0) atStack.pop();
+      i++;
+      continue;
+    }
+
+    const braceIdx = css.indexOf('{', i);
+    if (braceIdx === -1) break;
+
+    const selectorText = css.slice(i, braceIdx).trim();
+    if (!selectorText) { i = braceIdx + 1; continue; }
+
+    const closeIdx = findMatchingBrace(css, braceIdx);
+    const declBlock = css.slice(braceIdx + 1, closeIdx);
+    const declarations = parseDeclarations(declBlock);
+    const selectors = selectorText.split(',').map(s => s.trim()).filter(Boolean);
+    const line = getLineNumber(css, i);
+
+    rules.push({
+      selectors,
+      declarations,
+      mediaContext: atStack.length > 0 ? atStack.join(' > ') : null,
+      source: { file: filename, line },
+    });
+
+    i = closeIdx + 1;
+  }
+
+  return rules;
+}
+
+module.exports = { parseCSS };

package/src/cssomBuilder.js

@@ -0,0 +1,138 @@
+/**
+ * CSSOM Builder — reads one or more CSS files and builds an in-memory cascade model.
+ *
+ * The model is a flat ordered list of enriched rules, each carrying:
+ *   - selectors (array)
+ *   - declarations (array of { prop, value, important })
+ *   - source { file, line }
+ *   - mediaContext (string | null)
+ *   - specificity per selector (computed on build)
+ *   - sourceOrder (global integer, cross-file, determines cascade tiebreaking)
+ *
+ * This is the shared foundation both resolveStyles and traceProperty query against.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseCSS } = require('./cssParser');
+const { calculateSpecificity, compareSpecificity, specificityToString } = require('./specificity');
+
+const STYLE_EXTENSIONS = new Set(['.css', '.scss']);
+
+function buildCSSOM(filePaths) {
+  const flatRules = [];
+  let sourceOrder = 0;
+
+  for (const filePath of filePaths) {
+    if (!fs.existsSync(filePath)) continue;
+    const ext = path.extname(filePath).toLowerCase();
+    if (!STYLE_EXTENSIONS.has(ext)) continue;
+
+    const cssText = fs.readFileSync(filePath, 'utf8');
+    const rules = parseCSS(cssText, filePath);
+
+    for (const rule of rules) {
+      for (const selector of rule.selectors) {
+        flatRules.push({
+          selector: selector.trim(),
+          declarations: rule.declarations,
+          source: rule.source,
+          mediaContext: rule.mediaContext,
+          specificity: calculateSpecificity(selector),
+          sourceOrder: sourceOrder++,
+        });
+      }
+    }
+  }
+
+  return { rules: flatRules, fileCount: filePaths.length };
+}
+
+/**
+ * Discovers all CSS/SCSS files under a directory recursively.
+ */
+function discoverStyleFiles(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  function walk(current) {
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!['node_modules', '.git', 'dist', 'build', '.next', 'out'].includes(entry.name)) {
+          walk(fullPath);
+        }
+      } else if (STYLE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}
+
+/**
+ * Resolves which value wins for a given property across a set of rules
+ * that all potentially apply to an element (pre-filtered to matching rules).
+ * Returns { winner, overridden[] }.
+ */
+function resolveCascade(matchingRules, prop) {
+  const relevant = matchingRules.filter(r =>
+    r.declarations.some(d => d.prop === prop)
+  );
+
+  if (relevant.length === 0) return null;
+
+  // Sort by cascade order: !important first, then specificity, then source order
+  const withDecl = relevant.map(rule => ({
+    rule,
+    decl: rule.declarations.find(d => d.prop === prop),
+  }));
+
+  const CONFIDENCE_RANK = { certain: 0, likely: 1, possible: 2 };
+
+  withDecl.sort((a, b) => {
+    // !important always wins
+    if (a.decl.important && !b.decl.important) return -1;
+    if (!a.decl.important && b.decl.important) return 1;
+    // confidence first — certain/likely beats possible (possible rules need DOM context)
+    const confA = CONFIDENCE_RANK[a.rule.matchConfidence] ?? 1;
+    const confB = CONFIDENCE_RANK[b.rule.matchConfidence] ?? 1;
+    if (confA !== confB) return confA - confB;
+    // then specificity
+    const cmp = compareSpecificity(b.rule.specificity, a.rule.specificity);
+    if (cmp !== 0) return cmp;
+    // then source order (later wins)
+    return b.rule.sourceOrder - a.rule.sourceOrder;
+  });
+
+  const [winning, ...losing] = withDecl;
+
+  return {
+    winner: {
+      value: winning.decl.value,
+      important: winning.decl.important,
+      selector: winning.rule.selector,
+      specificity: specificityToString(winning.rule.specificity),
+      source: winning.rule.source,
+      mediaContext: winning.rule.mediaContext,
+    },
+    overridden: losing.map(({ rule, decl }) => ({
+      value: decl.value,
+      important: decl.important,
+      selector: rule.selector,
+      specificity: specificityToString(rule.specificity),
+      source: rule.source,
+      mediaContext: rule.mediaContext,
+      reason: losing.length > 0
+        ? decl.important && !winning.decl.important ? 'overridden by !important'
+          : compareSpecificity(rule.specificity, winning.rule.specificity) < 0 ? 'lower specificity'
+          : 'earlier in source order'
+        : 'lower specificity',
+    })),
+  };
+}
+
+module.exports = { buildCSSOM, discoverStyleFiles, resolveCascade, specificityToString };

package/src/resolveStyles.js

@@ -0,0 +1,96 @@
+/**
+ * resolve_styles — answers "what CSS actually applies to this selector?"
+ *
+ * Given a selector string and a set of files, returns a structured map of every
+ * CSS property that could apply, who wins, and who got overridden — with confidence
+ * levels so agents know how much to trust each answer.
+ */
+
+const path = require('path');
+const { buildCSSOM, discoverStyleFiles, resolveCascade } = require('./cssomBuilder');
+const { matchSelector } = require('./selectorMatcher');
+
+function resolveStyles({ selector, files = [], projectRoot = null }) {
+  if (!selector) return { error: 'selector is required' };
+
+  // Resolve file list
+  let filePaths = [...files];
+  if (projectRoot) filePaths.push(...discoverStyleFiles(projectRoot));
+  if (filePaths.length === 0) return { error: 'No CSS files found. Provide files[] or projectRoot.' };
+
+  const cssom = buildCSSOM(filePaths);
+
+  // Find all rules that could apply to this selector, tagged with match confidence
+  const matchingRules = [];
+  for (const rule of cssom.rules) {
+    const confidence = matchSelector(rule.selector, selector);
+    if (confidence !== 'none') {
+      matchingRules.push({ ...rule, matchConfidence: confidence });
+    }
+  }
+
+  if (matchingRules.length === 0) {
+    return {
+      query: { selector, filesAnalyzed: filePaths.map(f => path.basename(f)) },
+      properties: {},
+      matchedRules: 0,
+      summary: 'No rules found matching "' + selector + '" across ' + filePaths.length + ' file(s).',
+      agentNote: 'Either the selector does not exist yet, the files provided do not contain it, or the selector uses a pattern the static analyzer cannot match. Try broadening the file list or checking the selector spelling.',
+    };
+  }
+
+  // Collect all unique properties across matching rules
+  const allProps = new Set();
+  for (const rule of matchingRules) {
+    for (const decl of rule.declarations) allProps.add(decl.prop);
+  }
+
+  // Resolve each property through the cascade
+  const properties = {};
+  let overrideCount = 0;
+
+  for (const prop of allProps) {
+    const resolution = resolveCascade(matchingRules, prop);
+    if (!resolution) continue;
+
+    // Confidence for the property = lowest confidence among rules involved
+    const involvedRules = matchingRules.filter(r => r.declarations.some(d => d.prop === prop));
+    const lowestConfidence = involvedRules.some(r => r.matchConfidence === 'possible') ? 'possible'
+      : involvedRules.some(r => r.matchConfidence === 'likely') ? 'likely' : 'certain';
+
+    if (resolution.overridden.length > 0) overrideCount++;
+
+    properties[prop] = {
+      winner: resolution.winner,
+      overridden: resolution.overridden,
+      confidence: lowestConfidence,
+    };
+  }
+
+  // Group by confidence for the agent note
+  const certain = Object.entries(properties).filter(([, v]) => v.confidence === 'certain').map(([k]) => k);
+  const likely = Object.entries(properties).filter(([, v]) => v.confidence === 'likely').map(([k]) => k);
+  const possible = Object.entries(properties).filter(([, v]) => v.confidence === 'possible').map(([k]) => k);
+  const mediaWinners = Object.values(properties).filter(p => p.winner.mediaContext).length;
+
+  const agentNoteParts = [];
+  if (certain.length) agentNoteParts.push(certain.length + ' propert' + (certain.length === 1 ? 'y is' : 'ies are') + ' certain (exact selector match).');
+  if (likely.length) agentNoteParts.push(likely.length + ' propert' + (likely.length === 1 ? 'y is' : 'ies are') + ' likely (rule applies to this selector based on token overlap).');
+  if (possible.length) agentNoteParts.push(possible.length + ' propert' + (possible.length === 1 ? 'y is' : 'ies are') + ' possible (via ancestor/combinator rule - depends on DOM context).');
+  if (overrideCount) agentNoteParts.push(overrideCount + ' propert' + (overrideCount === 1 ? 'y has' : 'ies have') + ' overridden rules - review before modifying.');
+  if (mediaWinners > 0) agentNoteParts.push(mediaWinners + ' propert' + (mediaWinners === 1 ? "y's" : "ies'") + ' winning value comes from a @media rule - only applies at that breakpoint.');
+
+  return {
+    query: {
+      selector,
+      filesAnalyzed: filePaths.map(f => path.basename(f)),
+      rulesScanned: cssom.rules.length,
+    },
+    properties,
+    matchedRules: matchingRules.length,
+    summary: 'Found ' + Object.keys(properties).length + ' properties applying to "' + selector + '" from ' + matchingRules.length + ' matched rule(s) across ' + filePaths.length + ' file(s).',
+    agentNote: agentNoteParts.join(' '),
+  };
+}
+
+module.exports = { resolveStyles };

package/src/selectorMatcher.js

@@ -0,0 +1,66 @@
+/**
+ * Selector matcher — determines whether a CSS rule's selector could apply
+ * to a queried selector string, without a real DOM.
+ *
+ * Three match levels, each returned with a confidence score:
+ *
+ *  'certain'  — selectors are identical (exact match)
+ *  'likely'   — the rule selector's rightmost compound is a subset of the query
+ *               (e.g. rule ".btn" matches query ".btn.primary" — .btn would apply)
+ *  'possible' — the rule uses a combinator that could apply to an ancestor/sibling
+ *               of the queried element (e.g. ".sidebar .btn" when querying ".btn")
+ *
+ * 'none' means no meaningful relationship — skip.
+ */
+
+function parseCompound(selector) {
+  // Split on combinators, return rightmost compound selector's tokens
+  const parts = selector.trim().split(/(?<=[^\s>+~])\s*[\s>+~]+\s*/);
+  const rightmost = parts[parts.length - 1].trim();
+  const tokens = new Set();
+
+  // IDs
+  for (const m of rightmost.matchAll(/#([\w-]+)/g)) tokens.add('#' + m[1]);
+  // Classes
+  for (const m of rightmost.matchAll(/\.([\w-]+)/g)) tokens.add('.' + m[1]);
+  // Tag
+  const tagMatch = rightmost.match(/^([a-zA-Z][\w-]*)/);
+  if (tagMatch && tagMatch[1] !== '*') tokens.add(tagMatch[1].toLowerCase());
+  // Attrs
+  for (const m of rightmost.matchAll(/\[([^\]]+)\]/g)) tokens.add('[' + m[1] + ']');
+
+  return { tokens, hasCombinator: parts.length > 1, full: selector.trim() };
+}
+
+function matchSelector(ruleSelector, querySelector) {
+  const rule = parseCompound(ruleSelector);
+  const query = parseCompound(querySelector);
+
+  // Exact match
+  if (rule.full === query.full) return 'certain';
+
+  // Combinator check must come before subset check — a rule like ".sidebar .btn"
+  // has rightmost compound ".btn" which would falsely match as 'likely' against
+  // a query of ".btn" if we checked subsets first. Combinator rules always require
+  // DOM context so the best they can be is 'possible'.
+  if (rule.hasCombinator) {
+    for (const t of rule.tokens) {
+      if (query.tokens.has(t)) return 'possible';
+    }
+    return 'none';
+  }
+
+  // No combinator — rule tokens are a subset of query tokens → likely
+  // e.g. rule ".btn" vs query ".btn.primary" → .btn would apply to .btn.primary
+  if (rule.tokens.size > 0) {
+    let allMatch = true;
+    for (const t of rule.tokens) {
+      if (!query.tokens.has(t)) { allMatch = false; break; }
+    }
+    if (allMatch) return 'likely';
+  }
+
+  return 'none';
+}
+
+module.exports = { matchSelector, parseCompound };

package/src/server.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * stylespeak — MCP server + CLI
+ *
+ * MCP mode: reads JSON-RPC from stdin, exposes two tools:
+ *   resolve_styles  — what CSS applies to a selector, who wins, who loses
+ *   trace_property  — every rule setting a property, competing groups, blast radius
+ *
+ * CLI mode: node server.js resolve .btn src/styles/main.css
+ *           node server.js trace color --projectRoot src
+ */
+
+const readline = require('readline');
+const { resolveStyles } = require('./resolveStyles');
+const { traceProperty } = require('./traceProperty');
+
+// ─── Tool definitions ────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'resolve_styles',
+    description:
+      'Resolves what CSS actually applies to a given selector. Returns every property ' +
+      'the selector would receive, which rule wins for each property, and which rules ' +
+      'were overridden — with confidence levels (certain/likely/possible) since no real ' +
+      'DOM is available. Call this before modifying styles for an element to understand ' +
+      'the full cascade context first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'CSS selector to resolve, e.g. ".btn.primary", "#header a:hover"',
+        },
+        files: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Absolute paths to CSS/SCSS files to analyze.',
+        },
+        projectRoot: {
+          type: 'string',
+          description: 'Optional: path to a project root. All CSS/SCSS files will be discovered recursively.',
+        },
+      },
+      required: ['selector'],
+    },
+  },
+  {
+    name: 'trace_property',
+    description:
+      'Traces a CSS property across all provided files — finding every rule that sets it, ' +
+      'grouping competing rules that target overlapping selectors, and showing who wins in ' +
+      'each group. Use this to understand the blast radius of a property before changing it, ' +
+      'or to find out why a property value isn\'t applying as expected.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        property: {
+          type: 'string',
+          description: 'CSS property name to trace, e.g. "color", "background-color", "padding"',
+        },
+        files: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Absolute paths to CSS/SCSS files to analyze.',
+        },
+        projectRoot: {
+          type: 'string',
+          description: 'Optional: path to a project root. All CSS/SCSS files will be discovered recursively.',
+        },
+      },
+      required: ['property'],
+    },
+  },
+];
+
+// ─── MCP server ──────────────────────────────────────────────────────────────
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + '\n');
+}
+
+function runTool(name, args) {
+  if (name === 'resolve_styles') return resolveStyles(args || {});
+  if (name === 'trace_property') return traceProperty(args || {});
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+function handleRequest(req) {
+  const { id, method, params } = req;
+
+  if (method === 'initialize') {
+    return send({
+      jsonrpc: '2.0', id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'stylespeak', version: '0.1.0' },
+      },
+    });
+  }
+
+  if (method === 'notifications/initialized') return;
+
+  if (method === 'tools/list') {
+    return send({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
+  }
+
+  if (method === 'tools/call') {
+    const { name, arguments: args } = params || {};
+    try {
+      const result = runTool(name, args);
+      return send({
+        jsonrpc: '2.0', id,
+        result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] },
+      });
+    } catch (err) {
+      return send({
+        jsonrpc: '2.0', id,
+        result: { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true },
+      });
+    }
+  }
+
+  if (id !== undefined) {
+    send({ jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } });
+  }
+}
+
+// ─── CLI mode ────────────────────────────────────────────────────────────────
+
+function runCLI(args) {
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    console.log('stylespeak — CSS knowledge layer for AI agents\n');
+    console.log('Usage:');
+    console.log('  node server.js resolve <selector> [file...] [--projectRoot <dir>]');
+    console.log('  node server.js trace <property> [file...] [--projectRoot <dir>]\n');
+    console.log('Examples:');
+    console.log('  node server.js resolve ".btn.primary" src/styles/main.css');
+    console.log('  node server.js trace "color" --projectRoot src/styles');
+    console.log('  node server.js resolve "#header a" src/styles/base.css src/styles/header.css');
+    return;
+  }
+
+  const projectRootIdx = args.indexOf('--projectRoot');
+  const projectRoot = projectRootIdx !== -1 ? args[projectRootIdx + 1] : null;
+  const fileArgs = args.slice(1).filter(a => !a.startsWith('--') && a !== projectRoot);
+
+  let result;
+  if (command === 'resolve') {
+    const selector = fileArgs[0];
+    const files = fileArgs.slice(1);
+    result = resolveStyles({ selector, files, projectRoot });
+  } else if (command === 'trace') {
+    const property = fileArgs[0];
+    const files = fileArgs.slice(1);
+    result = traceProperty({ property, files, projectRoot });
+  } else {
+    console.error(`Unknown command: ${command}. Use resolve or trace.`);
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+// ─── Entry point ─────────────────────────────────────────────────────────────
+
+const cliArgs = process.argv.slice(2);
+
+if (cliArgs.length > 0) {
+  runCLI(cliArgs);
+} else {
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+  rl.on('line', line => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    try { handleRequest(JSON.parse(trimmed)); } catch { /* ignore malformed */ }
+  });
+}

package/src/specificity.js

@@ -0,0 +1,51 @@
+/**
+ * CSS Specificity calculator.
+ * Returns [inline, id, class, type] as a 4-tuple.
+ * Handles :where() (zero specificity), :not()/:is()/:has() (argument specificity).
+ */
+
+function calculateSpecificity(selector) {
+  let sel = selector.trim();
+  let id = 0, cls = 0, typ = 0;
+
+  // pseudo-elements count as type
+  sel = sel.replace(/::?(before|after|first-line|first-letter|placeholder|selection|marker|backdrop|cue)\b/gi, () => { typ++; return ''; });
+
+  // :where() contributes zero
+  sel = sel.replace(/:where\([^)]*\)/gi, '');
+
+  // :not(), :is(), :has() — recurse into args (simplified: treat contents as normal)
+  sel = sel.replace(/:(not|is|has)\(([^)]*)\)/gi, (_, _n, inner) => ` ${inner} `);
+
+  // IDs
+  sel = sel.replace(/#[\w-]+/g, () => { id++; return ''; });
+
+  // classes, attributes, pseudo-classes
+  sel = sel.replace(/\.[\w-]+/g, () => { cls++; return ''; });
+  sel = sel.replace(/\[[^\]]*\]/g, () => { cls++; return ''; });
+  sel = sel.replace(/:[\w-]+(\([^)]*\))?/g, () => { cls++; return ''; });
+
+  // type selectors
+  const typeMatches = sel.match(/(^|[\s>+~])([a-zA-Z][\w-]*)/g);
+  if (typeMatches) {
+    for (const m of typeMatches) {
+      const tag = m.replace(/^[\s>+~]+/, '');
+      if (tag && tag !== '*') typ++;
+    }
+  }
+
+  return [0, id, cls, typ];
+}
+
+function compareSpecificity(a, b) {
+  for (let i = 0; i < 4; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+function specificityToString(s) {
+  return `(${s[0]},${s[1]},${s[2]},${s[3]})`;
+}
+
+module.exports = { calculateSpecificity, compareSpecificity, specificityToString };

package/src/traceProperty.js

@@ -0,0 +1,100 @@
+/**
+ * trace_property — answers "everywhere this CSS property is set, who wins?"
+ *
+ * Given a property name and a set of files, returns every rule that touches
+ * that property — grouped by selector, showing who wins and who loses for each
+ * competing group. Useful for agents trying to understand the full blast radius
+ * of a property before changing it.
+ */
+
+const path = require('path');
+const { buildCSSOM, discoverStyleFiles, resolveCascade, specificityToString } = require('./cssomBuilder');
+const { matchSelector } = require('./selectorMatcher');
+
+function traceProperty({ property, files = [], projectRoot = null }) {
+  if (!property) return { error: 'property is required' };
+
+  let filePaths = [...files];
+  if (projectRoot) filePaths.push(...discoverStyleFiles(projectRoot));
+  if (filePaths.length === 0) return { error: 'No CSS files found. Provide files[] or projectRoot.' };
+
+  const cssom = buildCSSOM(filePaths);
+
+  // Find every rule that sets this property
+  const occurrences = cssom.rules.filter(rule =>
+    rule.declarations.some(d => d.prop === property.toLowerCase())
+  );
+
+  if (occurrences.length === 0) {
+    return {
+      query: { property, filesAnalyzed: filePaths.map(f => path.basename(f)) },
+      occurrences: [],
+      competingGroups: [],
+      summary: `"${property}" is not set in any of the ${filePaths.length} analyzed file(s).`,
+      agentNote: `The property doesn't exist yet — safe to introduce. Check inherited values or browser defaults if you're seeing unexpected behavior.`,
+    };
+  }
+
+  // Build competing groups: selectors that could target overlapping elements.
+  // Two rules compete if EITHER direction of matchSelector returns non-'none' —
+  // e.g. .btn competes with .btn.primary because .btn applies to .btn.primary elements,
+  // even though .btn.primary does not apply to plain .btn elements.
+  const groups = [];
+  const assigned = new Set();
+
+  for (let i = 0; i < occurrences.length; i++) {
+    if (assigned.has(i)) continue;
+    const group = [occurrences[i]];
+    assigned.add(i);
+
+    for (let j = i + 1; j < occurrences.length; j++) {
+      if (assigned.has(j)) continue;
+      const confAB = matchSelector(occurrences[j].selector, occurrences[i].selector);
+      const confBA = matchSelector(occurrences[i].selector, occurrences[j].selector);
+      if (confAB !== 'none' || confBA !== 'none') {
+        group.push(occurrences[j]);
+        assigned.add(j);
+      }
+    }
+
+    if (group.length > 1) {
+      const resolution = resolveCascade(group, property.toLowerCase());
+      groups.push({
+        selectors: group.map(r => r.selector),
+        winner: resolution ? resolution.winner : null,
+        overridden: resolution ? resolution.overridden : [],
+      });
+    }
+  }
+
+  // Format all occurrences for output
+  const formatted = occurrences.map(rule => {
+    const decl = rule.declarations.find(d => d.prop === property.toLowerCase());
+    return {
+      selector: rule.selector,
+      value: decl.value,
+      important: decl.important,
+      specificity: specificityToString(rule.specificity),
+      source: rule.source,
+      mediaContext: rule.mediaContext || null,
+    };
+  });
+
+  const affectedFiles = [...new Set(occurrences.map(r => path.basename(r.source.file)))];
+
+  return {
+    query: {
+      property,
+      filesAnalyzed: filePaths.map(f => path.basename(f)),
+      rulesScanned: cssom.rules.length,
+    },
+    occurrences: formatted,
+    competingGroups: groups,
+    summary: `"${property}" is set ${occurrences.length} time(s) across ${affectedFiles.join(', ')}.${groups.length > 0 ? ` ${groups.length} competing group(s) found where rules override each other.` : ''}`,
+    agentNote: groups.length > 0
+      ? `Changing "${property}" in one rule may have no effect if a competing rule with higher specificity or later source order wins. Review competing groups before editing.`
+      : `No competing rules found — changes to "${property}" in these selectors should apply cleanly.`,
+  };
+}
+
+module.exports = { traceProperty };