@cssints/devtools 0.0.0-stage → 0.1.0

package/src/core/dom.ts

@@ -0,0 +1,184 @@
+// The page of the cascade in a browser: the element's own document. At-rules are decided by the browser through a probe
+// sheet, winners are checked on a childless clone, and the other sheets are walked for what beats cssints.
+import { Effect, Layer, Result } from "effect";
+
+import { type Foreign, type Observed, Page, type Probe } from "./page.ts";
+
+const PROBE = "data-cssints-probe";
+const isCssints = (sheet: CSSStyleSheet) =>
+  sheet.ownerNode instanceof Element &&
+  (sheet.ownerNode.getAttribute("data-vite-dev-id") ?? "").endsWith("virtual:cssints.css");
+
+const matches = (el: Element, selector: string) =>
+  Result.getOrElse(
+    Result.try(() => el.matches(selector)),
+    () => false,
+  );
+
+const label = (el: Element) => {
+  const data = [...el.attributes].find((a) => a.name.startsWith("data-") && a.name !== PROBE);
+  return `${el.localName}${el.id ? `#${el.id}` : ""}${data ? `[${data.name}${data.value ? `="${data.value}"` : ""}]` : ""}`;
+};
+
+const probe = (el: Element, probes: readonly Probe[]) => {
+  if (!probes.length) return [];
+  const style = el.ownerDocument.createElement("style");
+  style.textContent = probes
+    .map(({ wrap, selector }, i) => {
+      const target = selector ? `:is(${selector}):where([${PROBE}])` : `[${PROBE}]`;
+      return `${wrap.map((w) => `${w} {`).join(" ")} ${target} { --cssints-probe-${i}: 1 } ${"}".repeat(wrap.length)}`;
+    })
+    .join("\n");
+  el.ownerDocument.head.append(style);
+  el.setAttribute(PROBE, "");
+  const cs = getComputedStyle(el);
+  const out = probes.map((_, i) => cs.getPropertyValue(`--cssints-probe-${i}`).trim() === "1");
+  el.removeAttribute(PROBE);
+  style.remove();
+  return out;
+};
+
+// The rules of the other sheets that match the element and set `prop`; @media and @supports are evaluated, the rest kept.
+const foreign = (el: Element, prop: string): Foreign[] => {
+  const out: Foreign[] = [];
+  const view = el.ownerDocument.defaultView;
+  const walk = (rules: CSSRuleList, source: string, layer: string) => {
+    for (const r of rules) {
+      if (r instanceof CSSStyleRule) {
+        const value = r.style.getPropertyValue(prop);
+        if (value && matches(el, r.selectorText))
+          out.push({
+            selector: r.selectorText,
+            source,
+            layer,
+            value,
+            important: r.style.getPropertyPriority(prop) === "important",
+          });
+        walk(r.cssRules, source, layer);
+      } else if (r instanceof CSSLayerBlockRule)
+        walk(r.cssRules, source, layer ? `${layer}.${r.name}` : r.name);
+      else if (r instanceof CSSMediaRule) {
+        if (view?.matchMedia(r.conditionText).matches) walk(r.cssRules, source, layer);
+      } else if (r instanceof CSSSupportsRule) {
+        if (CSS.supports(r.conditionText)) walk(r.cssRules, source, layer);
+      } else if (r instanceof CSSGroupingRule) walk(r.cssRules, source, layer);
+    }
+  };
+  for (const sheet of el.ownerDocument.styleSheets) {
+    if (isCssints(sheet)) continue;
+    const owner = sheet.ownerNode instanceof Element ? sheet.ownerNode : undefined;
+    const source =
+      sheet.href ?? owner?.getAttribute("data-vite-dev-id") ?? `<${owner?.localName ?? "style"}>`;
+    const rules = Result.getOrUndefined(Result.try(() => sheet.cssRules));
+    if (rules) walk(rules, source, "");
+  }
+  return out;
+};
+
+const selectorText = (selector: string) =>
+  Result.getOrUndefined(
+    Result.try(() => {
+      const sheet = new CSSStyleSheet();
+      sheet.insertRule(`${selector} {}`);
+      const rule = sheet.cssRules[0];
+      return rule instanceof CSSStyleRule ? rule.selectorText : undefined;
+    }),
+  );
+
+// The winner's declaration of a custom property as the page has it. A transformer between the server and the page (Vite's
+// LightningCSS) reprints values, and an unregistered custom property computes to its tokens as written: `.04` is not
+// `0.04`. Among the page's rules with the winner's selector, the last whose at-rules hold for the element.
+const live = (el: Element, selector: string, prop: string) => {
+  const target = selectorText(selector);
+  if (target === undefined) return undefined;
+  const found: { wrap: string[]; value: string }[] = [];
+  const walk = (rules: CSSRuleList, wrap: string[]) => {
+    for (const r of rules) {
+      if (r instanceof CSSStyleRule) {
+        const value = r.style.getPropertyValue(prop);
+        if (value && r.selectorText === target) found.push({ wrap, value });
+      } else if (r instanceof CSSMediaRule)
+        walk(r.cssRules, [...wrap, `@media ${r.conditionText}`]);
+      else if (r instanceof CSSSupportsRule)
+        walk(r.cssRules, [...wrap, `@supports ${r.conditionText}`]);
+      else if (r instanceof CSSContainerRule)
+        walk(r.cssRules, [...wrap, `@container ${r.conditionText}`]);
+      // Firefox before 146 has no CSSScopeRule
+      else if (globalThis.CSSScopeRule && r instanceof CSSScopeRule)
+        walk(r.cssRules, [
+          ...wrap,
+          `@scope${r.start ? ` (${r.start})` : ""}${r.end ? ` to (${r.end})` : ""}`,
+        ]);
+      else if (r instanceof CSSGroupingRule) walk(r.cssRules, wrap);
+    }
+  };
+  const sheets = [...el.ownerDocument.styleSheets];
+  const own = sheets.filter(isCssints);
+  for (const sheet of own.length ? own : sheets) {
+    const rules = Result.getOrUndefined(Result.try(() => sheet.cssRules));
+    if (rules) walk(rules, []);
+  }
+  if (found.length < 2) return found[0]?.value;
+  const held = probe(
+    el,
+    found.map(({ wrap }) => ({ wrap })),
+  );
+  return found.findLast((_, i) => held[i])?.value ?? found.at(-1)!.value;
+};
+
+const VAR = /var\(\s*(--[\w-]+)/g;
+
+const verify = (
+  el: Element,
+  prop: string,
+  selector: string,
+  declared: string,
+  longhands: readonly string[],
+): Observed[] => {
+  const clone = el.cloneNode(false);
+  if (!(clone instanceof Element) || !(clone instanceof HTMLElement || clone instanceof SVGElement))
+    return [];
+  const value = (prop.startsWith("--") && live(el, selector, prop)) || declared;
+  const cs = getComputedStyle(el);
+  // the clone is not hovered or focused: the custom properties the value reads are copied from the element
+  for (const [, name] of value.matchAll(VAR))
+    clone.style.setProperty(name!, cs.getPropertyValue(name!));
+  clone.style.setProperty(prop, value, "important");
+  el.after(clone);
+  const ccs = getComputedStyle(clone);
+  const inline = el instanceof HTMLElement || el instanceof SVGElement ? el.style : undefined;
+  const animated = el.getAnimations().length > 0;
+  const out = longhands.map((l) => {
+    const computed = cs.getPropertyValue(l).trim();
+    const expected = ccs.getPropertyValue(l).trim();
+    return {
+      prop: l,
+      computed,
+      expected,
+      inline: inline?.getPropertyValue(l) ?? "",
+      foreign: computed === expected ? [] : foreign(el, l),
+      animated,
+    } satisfies Observed;
+  });
+  clone.remove();
+  return out;
+};
+
+/** The page of an element in a browser. */
+export const domPage = Layer.succeed(
+  Page,
+  Page.of({
+    classes: (el) => Effect.sync(() => [...el.classList]),
+    label: (el) => Effect.sync(() => label(el)),
+    parent: (el) => Effect.sync(() => el.parentElement ?? undefined),
+    matches: (el, selector) => Effect.sync(() => matches(el, selector)),
+    probe: (el, probes) => Effect.sync(() => probe(el, probes)),
+    custom: (el, names) =>
+      Effect.sync(() => {
+        const cs = getComputedStyle(el);
+        return names.map((n) => cs.getPropertyValue(n).trim());
+      }),
+    verify: (el, prop, selector, value, longhands) =>
+      Effect.sync(() => verify(el, prop, selector, value, longhands)),
+  }),
+);

package/src/core/index.ts

@@ -0,0 +1,24 @@
+// The inspector's core: the protocol with the dev server, the model of its table, the cascade of an element. No overlay
+// in it: the overlay (src/ui) is one host, a DevTools extension could be another.
+export { beats, inspect } from "./cascade.ts";
+export type {
+  Candidate,
+  ClassRow,
+  Condition,
+  Group,
+  Inspection,
+  Row,
+  TokenRow,
+  Verdict,
+} from "./cascade.ts";
+export { parseSheet, specificity, stripStates } from "./css.ts";
+export type { Decl, Sheet, SheetRule } from "./css.ts";
+export { domPage } from "./dom.ts";
+export { Page } from "./page.ts";
+export { buildPrompt, relative } from "./prompt.ts";
+export type { Foreign, Observed, Probe } from "./page.ts";
+export { ASK, ASKED, session, STALE, TABLE, Transport } from "./session.ts";
+export type { Asked } from "./session.ts";
+export type { Session, TransportApi } from "./session.ts";
+export { toModel, Table, TableError } from "./table.ts";
+export type { ClassRecord, Model, Site } from "./table.ts";

package/src/core/inject.ts

@@ -0,0 +1,45 @@
+// The core in a page without the overlay: a host that drives a browser (@cssints/mcp through Playwright) bundles this file,
+// adds it to the page, hands it the table it got from the dev server, and runs the overlay's cascade on an element.
+import { Effect, Exit, Result } from "effect";
+
+import { inspect, type Inspection } from "./cascade.ts";
+import { domPage } from "./dom.ts";
+import { toModel, type Model } from "./table.ts";
+
+let model: Model | undefined;
+
+const api = {
+  // decodes the table (`cssints:devtools`): an error message, or undefined
+  load: (table: unknown): string | undefined => {
+    const exit = Effect.runSyncExit(toModel(table));
+    if (Exit.isFailure(exit)) return String(exit.cause);
+    model = exit.value;
+    return undefined;
+  },
+  // the inspection of the first element that matches, how many match, its computed `prop`; or an error message
+  inspect: (
+    selector: string,
+    prop?: string,
+  ): { inspection: Inspection; matches: number; computed: string } | string => {
+    if (!model) return "no table: call load first";
+    const all = Result.try(() => document.querySelectorAll(selector));
+    if (Result.isFailure(all)) return `not a CSS selector: ${selector}`;
+    const el = all.success[0];
+    if (!el) return `no element matches ${selector}`;
+    // @effect-diagnostics-next-line strictEffectProvide:off -- the host's edge: the one place the core meets the page
+    const exit = Effect.runSyncExit(inspect(model, el).pipe(Effect.provide(domPage)));
+    if (Exit.isFailure(exit)) return String(exit.cause);
+    return {
+      inspection: exit.value,
+      matches: all.success.length,
+      computed: prop ? getComputedStyle(el).getPropertyValue(prop).trim() : "",
+    };
+  },
+  // takes the focus from whatever has it
+  blur: (): void => {
+    const a = document.activeElement;
+    if (a instanceof HTMLElement || a instanceof SVGElement) a.blur();
+  },
+};
+
+Object.assign(globalThis, { __cssintsDevtools: api });

package/src/core/model.ts

@@ -0,0 +1,6 @@
+// The table and its sheet without the DOM, for a host outside the page (@cssints/mcp reads the table in Node).
+export { parseSheet, specificity, splitTop, stripStates } from "./css.ts";
+export type { Decl, Sheet, SheetRule } from "./css.ts";
+export { STALE, TABLE } from "./session.ts";
+export { toModel, Table, TableError } from "./table.ts";
+export type { ClassRecord, Model, Site } from "./table.ts";

package/src/core/page.ts

@@ -0,0 +1,55 @@
+// What the cascade asks of the page an element is in. The DOM implementation is dom.ts; the unit tests give one of their own.
+import { type Effect, Context } from "effect";
+
+/** A rule of another sheet that matches the element and sets the property (dom.ts walks the CSSOM for it). */
+export interface Foreign {
+  selector: string;
+  /** the sheet: its href, Vite's dev id, or `<style>` */
+  source: string;
+  /** "" outside every layer */
+  layer: string;
+  value: string;
+  important: boolean;
+}
+
+/** What the browser says of one longhand, for a winner's declaration. */
+export interface Observed {
+  prop: string;
+  /** getComputedStyle of the element */
+  computed: string;
+  /** getComputedStyle of a childless clone in its place with the winner's declaration inline and `!important` */
+  expected: string;
+  /** the element's own `style` for it */
+  inline: string;
+  foreign: Foreign[];
+  animated: boolean;
+}
+
+export interface Probe {
+  wrap: readonly string[];
+  /** the selector inside the at-rules; none: the at-rules alone, for the element */
+  selector?: string;
+}
+
+export class Page extends Context.Service<
+  Page,
+  {
+    readonly classes: (el: Element) => Effect.Effect<string[]>;
+    readonly label: (el: Element) => Effect.Effect<string>;
+    readonly parent: (el: Element) => Effect.Effect<Element | undefined>;
+    /** `Element.matches` */
+    readonly matches: (el: Element, selector: string) => Effect.Effect<boolean>;
+    /** whether each rule applies to the element now, at-rules and selector, as the browser decides */
+    readonly probe: (el: Element, probes: readonly Probe[]) => Effect.Effect<boolean[]>;
+    /** computed values of custom properties */
+    readonly custom: (el: Element, names: readonly string[]) => Effect.Effect<string[]>;
+    /** the winner's declaration `prop: value` of the rule `selector` */
+    readonly verify: (
+      el: Element,
+      prop: string,
+      selector: string,
+      value: string,
+      longhands: readonly string[],
+    ) => Effect.Effect<Observed[]>;
+  }
+>()("@cssints/devtools/core/page") {}

package/src/core/prompt.ts

@@ -0,0 +1,82 @@
+// The prompt of "ask OpenCode": the picked element as cssints knows it (the css.* calls that style it, the winner of each
+// property and what it beat, the tokens) plus the user's instruction. Every list is cut, so a page of a thousand rules sends
+// a few kilobytes; the dev server cuts the whole once more (packages/cssints/src/devtools-server.ts).
+import type { Candidate, Inspection } from "./cascade.ts";
+
+const SITES = 8;
+const ROWS = 24;
+const BEATEN = 3;
+const TOKENS = 12;
+const CALL = 400;
+
+/**
+ * A file name relative to the root of the app, when it is under it.
+ * @param {string} root the root of the app
+ * @param {string} file a file name
+ * @returns {string} the name under the root, or the name as given
+ */
+export const relative = (root: string, file: string) =>
+  file.startsWith(`${root}/`) ? file.slice(root.length + 1) : file;
+
+const cut = (text: string, max: number) => (text.length > max ? `${text.slice(0, max)}…` : text);
+const flat = (text: string | null) => (text ?? "").replace(/\s+/g, " ").trim();
+
+// html > body > main > p: the element and its three nearest ancestors
+const domPath = (el: Element) => {
+  const parent = el.parentElement;
+  const up2 = parent?.parentElement;
+  return [up2?.parentElement, up2, parent, el]
+    .flatMap((e) => (e ? [`${e.localName}${e.id ? `#${e.id}` : ""}`] : []))
+    .join(" > ");
+};
+
+const where = (c: Candidate) => `${c.selector} (${c.layer || "unlayered"})`;
+
+/**
+ * The prompt for an element: the instruction first, then what cssints knows of the element.
+ * @param {Inspection} inspection the cascade of the element (`inspect`)
+ * @param {Element} el the picked element
+ * @param {string} instruction what the user asked for
+ * @returns {string} the text to send to the agent
+ */
+export const buildPrompt = (inspection: Inspection, el: Element, instruction: string) => {
+  const { root } = inspection;
+  const sites = inspection.groups.flatMap((g) => (g.site ? [g.site] : []));
+  const lines = [
+    "Change the UI of the running app as the instruction says.",
+    "The styles are written with cssints: each `css.*` call below produced the classes of the element,",
+    "so edit those calls (or the markup that uses them), not the generated class names.",
+    "",
+    `Instruction: ${instruction.trim()}`,
+    "",
+    `Element: <${inspection.element}>`,
+    `DOM path: ${domPath(el)}`,
+    `Text: ${cut(flat(el.textContent), 120) || "(none)"}`,
+    `Classes: ${[...el.classList].slice(0, 12).join(" ") || "(none)"}`,
+    "",
+    "Styled by (file:line, the call as written):",
+  ];
+  if (!sites.length) lines.push("- no cssints call: the element is styled elsewhere");
+  for (const s of sites.slice(0, SITES))
+    lines.push(`- ${relative(root, s.file)}:${s.line}`, `  ${cut(flat(s.text ?? ""), CALL)}`);
+  if (sites.length > SITES) lines.push(`- … and ${sites.length - SITES} more`);
+  lines.push("", "Properties now (the winner, then what it beat):");
+  for (const r of inspection.rows.slice(0, ROWS)) {
+    if (!r.winner) continue;
+    const w = r.winner;
+    const beaten = r.overridden
+      .slice(0, BEATEN)
+      .map((c) => `${c.decl.prop}: ${c.decl.value} ${where(c)}`);
+    lines.push(
+      `- ${w.decl.prop}: ${w.decl.value}${w.decl.important ? " !important" : ""} from ${where(w)}` +
+        (beaten.length ? `; overridden: ${beaten.join("; ")}` : ""),
+    );
+  }
+  if (inspection.rows.length > ROWS) lines.push(`- … and ${inspection.rows.length - ROWS} more`);
+  if (inspection.tokens.length) {
+    lines.push("", "Tokens it reads:");
+    for (const t of inspection.tokens.slice(0, TOKENS))
+      lines.push(`- ${t.name} = ${t.computed || "(not set)"}${t.path ? ` (${t.path})` : ""}`);
+  }
+  return lines.join("\n");
+};

package/src/core/session.ts

@@ -0,0 +1,80 @@
+// The protocol with the dev server and the state of the inspector: the last table, decoded into a model, and whether it is
+// stale. The transport is whatever carries the two events (Vite's HMR channel in the overlay, a port in an extension).
+import { Console, Context, Effect, Queue, Ref, Stream, SubscriptionRef } from "effect";
+
+import { toModel, type Model } from "./table.ts";
+
+export const TABLE = "cssints:devtools";
+export const STALE = "cssints:devtools:stale";
+/** the browser asks the dev server to start an OpenCode session: `{ ref, prompt }` */
+export const ASK = "cssints:devtools:ask";
+/** the dev server tells how that session goes: an `Asked` */
+export const ASKED = "cssints:devtools:asked";
+
+/** `unavailable`: no OpenCode service runs (or its client is not installed); `message` says what to do. */
+export interface Asked {
+  readonly ref: number;
+  readonly status: "running" | "completed" | "failed" | "interrupted" | "unavailable";
+  readonly id?: string;
+  readonly message?: string;
+}
+
+export interface TransportApi {
+  /** asks the server for the table (`cssints:devtools:get`); it answers with TABLE */
+  readonly request: () => void;
+  readonly on: (event: string, listener: (data: unknown) => void) => void;
+  /** only when the server has `opencode` on: sends a prompt, the answers come as ASKED; the overlay shows its prompt box if it is set */
+  readonly ask?: (ref: number, prompt: string) => void;
+}
+
+export class Transport extends Context.Service<Transport, TransportApi>()(
+  "@cssints/devtools/core/session/Transport",
+) {}
+
+export interface Session {
+  /** the model of the last table; undefined until the first one */
+  readonly model: SubscriptionRef.SubscriptionRef<Model | undefined>;
+  /** an open inspector refetches when the table goes stale; a closed one when it opens */
+  readonly setActive: (active: boolean) => Effect.Effect<void>;
+}
+
+const events = (transport: TransportApi, event: string) =>
+  Stream.callback<unknown>((queue) =>
+    Effect.sync(() => transport.on(event, (data) => Queue.offerUnsafe(queue, data))),
+  );
+
+/** Listens to the server for as long as the page lives; the first table is asked for when the inspector opens. */
+export const session = Effect.fn("devtools.session")(function* () {
+  const transport = yield* Transport;
+  const model = yield* SubscriptionRef.make<Model | undefined>(undefined);
+  const active = yield* Ref.make(false);
+  const stale = yield* Ref.make(true);
+  const request = Ref.set(stale, false).pipe(
+    Effect.andThen(Effect.sync(() => transport.request())),
+  );
+  const refetch = Effect.gen(function* () {
+    if ((yield* Ref.get(active)) && (yield* Ref.get(stale))) yield* request;
+  });
+  yield* Effect.forkDetach(
+    Stream.runForEach(events(transport, TABLE), (data) =>
+      toModel(data).pipe(
+        Effect.flatMap((m) => SubscriptionRef.set(model, m)),
+        Effect.catchTag("TableError", (e) => Console.error(e.message)),
+      ),
+    ),
+  );
+  // a cold page load transforms every module: one refetch once they are done
+  yield* Effect.forkDetach(
+    Stream.runForEach(
+      events(transport, STALE).pipe(
+        Stream.tap(() => Ref.set(stale, true)),
+        Stream.debounce("60 millis"),
+      ),
+      () => refetch,
+    ),
+  );
+  return {
+    model,
+    setActive: (on: boolean) => Ref.set(active, on).pipe(Effect.andThen(refetch)),
+  } satisfies Session;
+});

package/src/core/table.ts

@@ -0,0 +1,68 @@
+// The table the dev server sends (`cssints:devtools`, packages/cssints/src/devtools-server.ts `DevTable`), decoded at the
+// boundary, and the model the cascade reads: the table with its sheet parsed and its layers ranked.
+import { Data, Effect, Schema } from "effect";
+
+import { parseSheet, type Sheet } from "./css.ts";
+
+const Site = Schema.Struct({
+  file: Schema.String,
+  line: Schema.Finite,
+  column: Schema.Finite,
+  classes: Schema.Array(Schema.String),
+  text: Schema.optionalKey(Schema.String),
+});
+
+const ClassRecord = Schema.Struct({
+  kind: Schema.Literals(["class", "marker", "group"]),
+  layer: Schema.String,
+  wrap: Schema.Array(Schema.String),
+  prop: Schema.String,
+  css: Schema.String,
+  tokens: Schema.Array(Schema.String),
+  plugin: Schema.optionalKey(Schema.String),
+  sites: Schema.Array(Schema.Finite),
+});
+
+export const Table = Schema.Struct({
+  root: Schema.String,
+  sheet: Schema.String,
+  layers: Schema.Array(Schema.String),
+  classes: Schema.Record(Schema.String, ClassRecord),
+  sites: Schema.Array(Site),
+  tokens: Schema.Record(
+    Schema.String,
+    Schema.Struct({ path: Schema.String, value: Schema.String }),
+  ),
+});
+export type Table = typeof Table.Type;
+export type ClassRecord = typeof ClassRecord.Type;
+export type Site = typeof Site.Type;
+
+export class TableError extends Data.TaggedError("TableError")<{ readonly message: string }> {}
+
+export interface Model {
+  table: Table;
+  sheet: Sheet;
+  /** top-level layer -> rank; a rule outside every layer ranks above all of them */
+  rank: Map<string, number>;
+  /** class -> the indexes of the rules whose selector names it */
+  rulesOf: Map<string, number[]>;
+}
+
+/** The model of a table as the server sent it: decoded, its sheet parsed. */
+export const toModel = Effect.fn("devtools.toModel")(function* (payload: unknown) {
+  const table = yield* Schema.decodeUnknownEffect(Table)(payload).pipe(
+    Effect.mapError(
+      (e) => new TableError({ message: `cssints devtools: a bad table: ${e.message}` }),
+    ),
+  );
+  const sheet = yield* parseSheet(table.sheet);
+  const rank = new Map(table.layers.map((l, i) => [l, i]));
+  const rulesOf = new Map<string, number[]>();
+  for (const r of sheet.rules)
+    for (const [, cls] of r.selector.matchAll(/\.(_[\w-]+)/g)) {
+      const list = rulesOf.get(cls!) ?? rulesOf.set(cls!, []).get(cls!)!;
+      if (list.at(-1) !== r.index) list.push(r.index);
+    }
+  return { table, sheet, rank, rulesOf } satisfies Model;
+});