@cssints/devtools 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssints/devtools",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A dev overlay inspector for cssints: an element's classes by the call that made them, the cascade of the sheet, checked against the browser",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,7 @@
   "sideEffects": false,
   "exports": {
     "./overlay": "./dist/overlay.js",
+    "./opencode": "./dist/opencode.js",
     "./core": {
       "types": "./src/core/index.ts",
       "default": "./src/core/index.ts"
@@ -28,11 +29,11 @@
     "./inject": "./src/core/inject.ts"
   },
   "dependencies": {
-    "@cssints/css-grammar": "^0.1.0",
+    "@cssints/css-grammar": "^0.3.0",
     "effect": "4.0.0"
   },
   "peerDependencies": {
-    "cssints": "^0.1.0"
+    "cssints": "^0.3.0"
   },
   "engines": {
     "node": ">=22"

package/src/core/cascade.ts

@@ -78,6 +78,8 @@ export interface TokenRow {
 
 export interface Inspection {
   element: string;
+  /** the readable classes of the element's cn() and cv() calls (`cs-Landing-logo`, dev only), not in the table */
+  names: string[];
   root: string;
   groups: Group[];
   rows: Row[];
@@ -87,6 +89,8 @@ export interface Inspection {
 const lh = (prop: string): readonly string[] => longhands[prop] ?? [prop];
 const isScope = (w: string) => /^@scope\b/i.test(w);
 const CLASSY = /\._[\w-]/;
+// the readable class of a cn() or cv() site that the dev server adds (instrument.ts `tagged`)
+const READABLE = /^cs-[\w-]+$/;
 const UNLAYERED = 1e9;
 // Computed values of these depend on the element's content, which the clone does not have.
 const LAYOUT =
@@ -346,7 +350,10 @@ export const inspect = Effect.fn("devtools.inspect")(function* (model: Model, el
     groups.push({ site, classes: left.filter((c) => site.classes.includes(c)).map(classRow) });
     left = left.filter((c) => !site.classes.includes(c));
   }
-  const rest = classes.filter((c) => !groups.some((g) => g.classes.some((r) => r.cls === c)));
+  const readable = classes.filter((c) => !table.classes[c] && READABLE.test(c));
+  const rest = classes.filter(
+    (c) => !readable.includes(c) && !groups.some((g) => g.classes.some((r) => r.cls === c)),
+  );
   if (rest.length) groups.push({ classes: rest.map(classRow) });
 
   // the tokens the element's rules read
@@ -371,6 +378,7 @@ export const inspect = Effect.fn("devtools.inspect")(function* (model: Model, el
   }
   return {
     element: yield* page.label(el),
+    names: readable,
     root: table.root,
     groups,
     rows,

package/src/core/index.ts

@@ -15,10 +15,10 @@ 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 { buildPrompt, pagePrompt, 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 { ASK, ASKED, LINKED, session, STALE, TABLE, Transport } from "./session.ts";
+export type { Asked, Linked } 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/prompt.ts

@@ -1,6 +1,7 @@
 // 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).
+// property and what it beat, the tokens) plus the user's instruction, the route and how the page is displayed. Every list is
+// cut, so a page of a thousand rules sends a few kilobytes; the dev server adds an `App:` line on top and cuts the whole once
+// more, from the end (packages/cssints/src/devtools-server.ts): the instruction and the header come first and stay.
 import type { Candidate, Inspection } from "./cascade.ts";
 
 const SITES = 8;
@@ -8,6 +9,23 @@ const ROWS = 24;
 const BEATEN = 3;
 const TOKENS = 12;
 const CALL = 400;
+const INSTRUCTION = 4000;
+const VALUE = 80;
+const ATTRS = 8;
+const HTML_ATTRS = 12;
+// what tells what an element is; never `value`: a form's values stay in the page
+const IDENTITY = new Set([
+  "id",
+  "role",
+  "aria-label",
+  "href",
+  "src",
+  "alt",
+  "type",
+  "name",
+  "placeholder",
+  "title",
+]);
 
 /**
  * A file name relative to the root of the app, when it is under it.
@@ -21,17 +39,88 @@ export const relative = (root: string, file: string) =>
 const cut = (text: string, max: number) => (text.length > max ? `${text.slice(0, max)}…` : text);
 const flat = (text: string | null) => (text ?? "").replace(/\s+/g, " ").trim();
 
+const label = (e: Element) => `${e.localName}${e.id ? `#${e.id}` : ""}`;
+
 // 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(" > ");
+  return [up2?.parentElement, up2, parent, el].flatMap((e) => (e ? [label(e)] : [])).join(" > ");
 };
 
 const where = (c: Candidate) => `${c.selector} (${c.layer || "unlayered"})`;
 
+// name="value" of the attributes `keep` names, each value cut
+const attrs = (el: Element, keep: (name: string) => boolean, max: number) =>
+  [...el.attributes]
+    .flatMap((a) => (keep(a.name) ? [`${a.name}="${cut(flat(a.value), VALUE)}"`] : []))
+    .slice(0, max)
+    .join(" ");
+
+// the data-* of the element and its three nearest ancestors (<html>'s are in the header)
+const dataLines = (el: Element) => {
+  const parent = el.parentElement;
+  const up2 = parent?.parentElement;
+  return [el, parent, up2, up2?.parentElement].flatMap((e) => {
+    const data =
+      e && e !== el.ownerDocument.documentElement && attrs(e, (n) => n.startsWith("data-"), ATTRS);
+    return e && data ? [`Data of ${label(e)}: ${data}`] : [];
+  });
+};
+
+// the route, the title and what decides how the page looks now: the same for both prompts
+const header = (doc: Document, el?: Element) => {
+  const { defaultView: win, location: at } = doc;
+  if (!win) return [];
+  const { innerWidth: w, innerHeight: h, devicePixelRatio: dpr } = win;
+  const root = attrs(
+    doc.documentElement,
+    (n) => n === "class" || n.startsWith("data-"),
+    HTML_ATTRS,
+  );
+  const lines = [
+    `Page: ${cut(at.pathname + at.search + at.hash, 300)}`,
+    `Title: ${cut(flat(doc.title), 120) || "(none)"}`,
+    "Display:",
+    `- viewport: ${w}x${h}${dpr === 1 ? "" : `, devicePixelRatio ${dpr}`}`,
+  ];
+  if (root) lines.push(`- <html> ${root}`);
+  const dark = win.matchMedia("(prefers-color-scheme: dark)").matches;
+  const still = win.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  lines.push(
+    `- prefers-color-scheme: ${dark ? "dark" : "light"}${still ? "; prefers-reduced-motion: reduce" : ""}`,
+  );
+  if (el) {
+    const r = el.getBoundingClientRect();
+    const state = [
+      el.matches(":hover") ? ["hovered"] : [],
+      doc.activeElement === el ? ["focused"] : [],
+      el.matches(":disabled") || el.getAttribute("aria-disabled") === "true" ? ["disabled"] : [],
+    ].flat();
+    lines.push(
+      `- rect: ${Math.round(r.width)}x${Math.round(r.height)} at ${Math.round(r.x)},${Math.round(r.y)} in the viewport${state.length ? `; ${state.join(", ")}` : ""}`,
+    );
+  }
+  return lines;
+};
+
+/**
+ * The prompt with no element picked: the instruction, the page it is about and how it is displayed.
+ * @param {string} instruction what the user asked for
+ * @param {Document} doc the document of the page
+ * @returns {string} the text to send to the agent
+ */
+export const pagePrompt = (instruction: string, doc: Document) =>
+  [
+    "Change the UI of the running app as the instruction says.",
+    "The styles are written with cssints (`css.*` calls): edit those calls, not the generated class names.",
+    "Find the markup from the route (Page) and the app (App).",
+    "",
+    `Instruction: ${cut(instruction.trim(), INSTRUCTION)}`,
+    "",
+    ...header(doc),
+  ].join("\n");
+
 /**
  * The prompt for an element: the instruction first, then what cssints knows of the element.
  * @param {Inspection} inspection the cascade of the element (`inspect`)
@@ -44,15 +133,20 @@ export const buildPrompt = (inspection: Inspection, el: Element, instruction: st
   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.",
+    "The styles are written with cssints: each `css.*` call under `Styled by` produced the classes of the element,",
+    "so start from those files and edit those calls, not the generated class names.",
+    "For the markup, start from the route (Page) and the app (App).",
+    "",
+    `Instruction: ${cut(instruction.trim(), INSTRUCTION)}`,
     "",
-    `Instruction: ${instruction.trim()}`,
+    ...header(el.ownerDocument, el),
     "",
     `Element: <${inspection.element}>`,
     `DOM path: ${domPath(el)}`,
     `Text: ${cut(flat(el.textContent), 120) || "(none)"}`,
     `Classes: ${[...el.classList].slice(0, 12).join(" ") || "(none)"}`,
+    `Attributes: ${attrs(el, (n) => IDENTITY.has(n), IDENTITY.size) || "(none)"}`,
+    ...dataLines(el),
     "",
     "Styled by (file:line, the call as written):",
   ];

package/src/core/session.ts

@@ -19,12 +19,30 @@ export interface Asked {
   readonly message?: string;
 }
 
+/** the browser asks whether an OpenCode service is found (no session is created); the answer is a LINKED */
+export const LINK = "cssints:devtools:link";
+export const LINKED = "cssints:devtools:linked";
+
+/** `message` is set when the client is missing or the lookup failed, not when OpenCode simply is not running. */
+export interface Linked {
+  readonly connected: boolean;
+  /** the address of the service */
+  readonly url?: string;
+  /** the folder the sessions open in */
+  readonly directory: string;
+  /** the session `/cssints-devtools` attached to this dev server: prompts go there, none starts a new one */
+  readonly session?: 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;
+  /** next to `ask`: probes for the service, the answer comes as LINKED */
+  readonly link?: () => void;
 }
 
 export class Transport extends Context.Service<Transport, TransportApi>()(