@cssints/devtools 0.2.0 → 0.3.1

package/README.md

@@ -33,6 +33,11 @@ docs/API.md, "Debugging: the devtools overlay"; the design in docs/research/devt
   (a `cssints` button and Alt+Shift+C). The first open loads both; a call shows as `file:line` and its source, with no link
   to an editor. The table has no path of the machine that built it. Sizes are logged by the build (this site: table 70 kB,
   overlay 190 kB, the entry +0.85 kB).
+- **Readable classes, dev only.** The dev server adds `cs-<owner>[-<label>]` to each `cn(...)` and `cv({...})`:
+  `const logo = cn(...)` inside `function Landing()` gives `cs-Landing-logo`, at the top of `landing/page.ts`
+  `cs-page-logo`, `<div class={cn(...)}>` in `Button` `cs-Button`. The panel shows it first in its bar and in the hover
+  tag; the prompt's `Classes:` line lists it. It is not in the table, the sheet or the hashes, and a build has none.
+  docs/API.md, "Debugging: the devtools overlay".
 - **The data is the compiler's.** The table holds the sheet as the server renders it, each class's rule, plugin,
   tokens and sites, and the place of every call. The core parses the sheet; it never reads the page's CSSOM for
   cssints' rules.
@@ -54,15 +59,75 @@ cssints({ devtools: true, opencode: true });
 cssints({ devtools: true, opencode: { agent: "build", skills: ["cssints"] } });
 ```
 
-With an element picked, the panel has a prompt box (Enter sends, Shift+Enter is a new line). The dev server starts a session
-on the running OpenCode V2 service (`Service.discover` of `@opencode/client`; the page never talks to it) in the nearest
-folder up from the Vite root that has a `.git`, with a prompt of `src/core/prompt.ts`: your instruction, the element (tag,
-DOM path, text, classes), the `css.*` calls that style it (`file:line` and the call's source), the winner of each property
-and what it beat, and the tokens it reads; every list is cut. The box then shows `running · <session id>`, and `completed`,
-`failed` or `interrupted`; with no service running it says so and keeps your text. The page and the server talk over the
-HMR channel (`cssints:devtools:ask`, `cssints:devtools:asked`), not a route. A build has none of it. The idea, and the
-calls to the V2 client, follow [brendonovich/vite-plugin-opencode](https://github.com/Brendonovich/vite-plugin-opencode)
-(MIT, Brendan Allan), which marks the markup with Babel and so needs no table; here the table is the context.
+The panel has an OpenCode box whenever the option is on, picked element or not. It is pinned: at the bottom of the panel in
+a left or right dock, at its right edge (20 rem wide, to the right of the inspection) in a top or bottom dock, and in the
+detached window by the window's shape (wider than tall: the right edge); the inspection beside it scrolls, the box does not.
+The box has a title row (`OpenCode`, and a dot with `connected` or `not connected`), the input (Enter sends, Shift+Enter is a
+new line) and one status line:
+
+- Not connected: how to connect. Start OpenCode (or `opencode serve --service`) and run `/cssints-devtools` in a session; the
+  dev server finds the running service by itself; a prompt without an attached session opens a new one in the repository
+  folder; `@opencode/client` must be in the app's devDependencies. When the server has its own message (the client is not
+  installed), it follows.
+- Connected: `connected to <service address> · attached session <id> · <state>`, or `no session attached: a prompt starts a
+new one`. The id is the session `/cssints-devtools` attached to this dev server (truncated; the full id is the title); the
+  state is `running`, `completed`, `failed` or `interrupted`.
+
+The page asks the dev server whether a service is found (a probe: it looks, it creates no session) when the panel opens, when
+the box gets focus and after a send that found none, so starting OpenCode later shows up without a reload.
+
+### The command `/cssints-devtools`
+
+The box does not choose a session: an OpenCode command attaches the session it runs in to a dev server. The plugin is the
+main entry of this package, so OpenCode loads it by the package name (checked on 2.0.27: it installs the package and finds
+the entry; a package subpath, `@cssints/devtools/opencode`, is not loaded as a plugin):
+
+```jsonc
+// opencode.jsonc of the repository of the app (or ~/.config/opencode/opencode.jsonc)
+{ "plugins": ["@cssints/devtools"] }
+```
+
+Or, with the package installed in the app, a file of the repository (OpenCode loads the `.ts` files of `.opencode/plugins/`):
+
+```ts
+// .opencode/plugins/cssints-devtools.ts
+export { default } from "@cssints/devtools/opencode";
+```
+
+Then, in an OpenCode session:
+
+- `/cssints-devtools`: one dev server of this repository with `opencode` on runs: this session is attached to it. Several
+  run: they are listed (id, address, root) and none is attached. None: it says so.
+- `/cssints-devtools <id or part of it>` picks one (the id is the Vite root relative to the repository, `/` as `-`, so
+  `docs` picks `apps-docs`); `/cssints-devtools off [id]` detaches this session (or that server).
+
+Each outcome is a message in the session (`ctx.session.synthetic`, which also gives the model a turn to acknowledge it). The
+prompts of an attached server's panel are sent to that session, which is not created again; a session that is gone makes the
+send fail with a message that says to run `/cssints-devtools` again. The rendezvous is files, not a route (the ask channel is
+the HMR socket, which Vite's token protects): `<repository>/node_modules/.cache/cssints-devtools/<id>.json` (`root`, `pid`,
+`url`) is written by the dev server while it runs, and `<id>.session.json` by the command. A dev server that crashed leaves a
+file with a dead pid, which the command ignores and removes. The plugin imports `cssints/devtools-link`, the module both
+sides share.
+
+Without an attached session, Enter starts a session on the running OpenCode V2 service (`Service.discover` of
+`@opencode/client`; the page never talks to it) in the nearest folder up from the Vite root that has a `.git`. The prompt is built by `src/core/prompt.ts`:
+
+- `App:` (added by the dev server, on top): the Vite root relative to the repository (`.` when it is the repository) and the
+  address the server listens on, as file paths in the prompt are relative to that root;
+- your instruction, then `Page:` (path, query and hash, not the origin), `Title:` and `Display:` (viewport and pixel ratio,
+  the `class` and `data-*` attributes of `<html>`, `prefers-color-scheme` and `prefers-reduced-motion`; with an element, its
+  rendered size and position and whether it is hovered, focused or disabled);
+- with an element picked: its tag, DOM path, text, classes, `id`, `role`, `aria-label`, `href`, `src`, `alt`, `type`, `name`,
+  `placeholder` and `title`, the `data-*` attributes of it and of its three nearest ancestors, the `css.*` calls that style it
+  (`file:line` and the call's source), the winner of each property and what it beat, and the tokens it reads. Never a `value`,
+  a cookie or storage.
+
+Every list and value is cut, the server cuts the whole at 16,000 characters from the end (the `App:` line, the instruction
+and the header come first and stay). With no service running the box says how to connect and keeps your text. The
+page and the server talk over the HMR channel (`cssints:devtools:ask`, `asked`, `link`, `linked`), not a route. A build has
+none of it. The idea, and the calls to the V2 client, follow
+[brendonovich/vite-plugin-opencode](https://github.com/Brendonovich/vite-plugin-opencode) (MIT, Brendan Allan), which marks the
+markup with Babel and so needs no table; here the table is the context.
 
 ## Layout
 
@@ -98,6 +163,7 @@ the calls to the V2 client. No code is copied. The overlay is built with [Solid]
 bun run test            # test/core.mjs (the cascade on happy-dom: hover vs media, @container, @supports, @scope,
                         # an unlayered rule, frame's kernel, within(), grouping), test/build.mjs (nothing in a build
                         # without the option; with "build": the table, the lazy chunk, the loader's size; apps/docs/test/browser.mjs opens it in Chrome),
-                        # test/opencode.mjs (the dev server and a fake OpenCode service: the prompt as sent, the agent, the directory, the status, no service)
-bun run test:browsers   # builds dist/overlay.js, then the demo in Chrome, Firefox and WebKit (test/browsers.mjs; each dock: the panel on its side, a pick beside it, a drag of the grip, the button after Esc, the dock and sizes after a reload; detach: the pop-up with the panel, a pick in the page followed live, the choice after a reload, closing re-docks, a blocked pop-up), then the prompt box in Chrome (test/ask-browser.mjs)
+                        # test/opencode.mjs (the dev server and a fake OpenCode service: the prompt as sent, the agent, the directory, the status, no service; the link probe, with and without the service and the client; an attached session, a detached one, two dev servers, a session that is gone, stale files),
+                        # test/opencode-plugin.mjs (the command on a fake plugin context: none, one, several, a pick, off, a stale pid)
+bun run test:browsers   # builds dist/overlay.js, then the demo in Chrome, Firefox and WebKit (test/browsers.mjs; each dock: the panel on its side, a pick beside it, a drag of the grip, the button after Esc, the dock and sizes after a reload; detach: the pop-up with the panel, a pick in the page followed live, the choice after a reload, closing re-docks, a blocked pop-up), then the OpenCode box in Chrome (test/ask-browser.mjs: with nothing picked, pinned in each dock and in the window, the connect text, a service started later found on focus, the attached session and its title; screenshots in test/out/)
 ```

package/dist/opencode.js

@@ -0,0 +1,30 @@
+import { attach as e, gitRoot as t, servers as n, sessionOf as r } from "cssints/devtools-link";
+//#region src/opencode.ts
+var i = "cssints-devtools", a = (e, t) => t.map((t) => {
+	let n = r(e, t.id);
+	return `- ${t.id}  ${t.url}  ${t.root}${n ? `  (session ${n})` : ""}`;
+}).join("\n"), o = (t, o, s) => {
+	let c = n(t), [l = "", ...u] = s.trim().split(/\s+/), d = l === "off" ? u.join(" ") : l, f = d ? c.filter((e) => e.id.includes(d)) : c, p = f.filter((e) => e.id === d), m = p.length ? p : f;
+	if (l === "off") {
+		let n = m.filter((e) => d ? !0 : r(t, e.id) === o);
+		return n.forEach((n) => e(t, n.id)), n.length ? `Detached from ${n.map((e) => e.id).join(", ")}: its devtools panel starts a new session per prompt again.` : d ? `No running dev server matches "${d}".\n${a(t, c)}` : "This session is not attached to any dev server.";
+	}
+	if (!c.length) return `No cssints dev server with \`devtools: true, opencode: true\` runs in ${t}. Start one, then run /${i} again.`;
+	let [h, g] = m;
+	return h ? g ? `${m.length} dev servers run${d ? ` that match "${d}"` : ""}; none is attached. Run /${i} <id> to pick one:\n${a(t, m)}` : (e(t, h.id, o), `Attached this session (${o}) to the dev server ${h.id} (${h.url}, ${h.root}). The prompts of its devtools panel now go to this session. /${i} off detaches.`) : `No running dev server matches "${d}". Running:\n${a(t, c)}`;
+}, s = {
+	id: "cssints.devtools",
+	setup(e) {
+		let n = t(e.location.directory);
+		return e.command.transform((t) => t.add({
+			name: i,
+			description: "Attach this session to the devtools of a cssints dev server (off detaches)",
+			execute: ({ sessionID: t, prompt: r }) => e.session.synthetic({
+				sessionID: t,
+				text: `${o(n, t, r.text)}\n\n(A notice from the /${i} command: acknowledge it in one short sentence and run no tools.)`
+			}).then(() => void 0)
+		})).then((e) => () => e.dispose());
+	}
+};
+//#endregion
+export { i as COMMAND, s as default, o as run };