@comty.io/core 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,16 @@
 # @comty.io/core
 
-Comty's browser SDK provides shared comments and an element inspector, with no npm package dependencies.
+Comty's browser SDK and development companion have no npm package dependencies. The Node companion runs the locally installed Codex, Claude, Cursor, Gemini or Grok CLI. Agent tasks stay in memory while the development server runs; only the current local answer is shown, and no modification history is saved. Replies to shared comments are stored with those comments.
+
+Requires Node.js 22.12 or newer for the development tools.
+
+## Comment targets and routes
+
+Comments use the pathname and hash routes starting with `#/` or `#!/`. Plain fragments such as `#contact` remain on the same page. Hash changes, history navigation, `pushState` and `replaceState` reload the appropriate comments. Older pathname-only comments remain readable on hash routes; when their target cannot be found, the sidebar identifies their original page as unknown. Existing records are not rewritten.
+
+Target matching combines content, attributes and surrounding structure. Small changes inside a container can preserve its comments; ambiguous matches do not place a pin. The sidebar shows **Target missing** when no target is found and **Target uncertain** when placement cannot be determined reliably. Both still open the full thread. Closed or unmounted known overlays do not count as deleted elements, and their comments never attach to matching content outside that overlay.
+
+Run `npm run test:anchors` for route, reload, ambiguity and overlay regressions.
 
 ## Comment screenshots
 
@@ -41,7 +51,7 @@ The toolbar pipette shows a circular nine-pixel magnifier from a local DOM snaps
 
 ## Element inspector
 
-The dense inspector displays all collected properties without an expandable section, with color tokens and values sharing a line when space permits. Long selectors truncate at the beginning to preserve the final tag. The header copies the selector and all declarations; each property's copy icon copies its value and transitions to a check on success. Color and font values open their detail panels after selecting an element. Reduced-motion preferences disable the icon transition. Placement prefers below the target, then either side, then above; when no outside space fits, it minimizes overlap while staying in the viewport. Run `npm run test:inspector` for browser coverage of these interactions.
+The dense inspector displays all collected properties without an expandable section, with color tokens and values sharing a line when space permits. Existing comment pins remain visible and follow their elements in Inspect mode, and their threads can still be opened. Long selectors truncate at the beginning to preserve the final tag. The header copies the selector and all declarations; each property's copy icon copies its value and transitions to a check on success. Color and font values open their detail panels after selecting an element. Reduced-motion preferences disable the icon transition. Placement prefers below the target, then either side, then above; when no outside space fits, it minimizes overlap while staying in the viewport. Run `npm run test:inspector` for browser coverage of these interactions.
 
 ## Border measurements
 
@@ -58,3 +68,73 @@ Open inspection with **Shift I**, then select the stopwatch or press **M**. Drag
 Supported: CSS transitions, CSS animations and Web Animations on document timelines, including newly mounted sidebars and open shadow roots (new shadow roots can take up to 500 ms to be discovered). Comty's own interface is excluded. No screen capture, permission prompt, recording buffer, upload or package dependency is involved.
 
 JavaScript animation loops, canvas, closed shadow roots, embedded frames and scroll-driven timelines are not controlled. Application timers and state changes keep their normal timing: a panel removed by a fixed timer can disappear before its slowed animation ends. Comty does not patch global clocks or delay application actions.
+
+## Agent mode with Vite
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import { comty } from '@comty.io/core/vite';
+
+export default defineConfig({
+  plugins: [comty({ agent: 'codex' })],
+});
+```
+
+Keep your existing plugins. Run your normal dev command and open `http://localhost:<vite-port>`. The plugin injects the SDK and starts the companion automatically. It is disabled for production builds. Choose the installed coding agent with `agent: 'codex' | 'claude' | 'cursor' | 'gemini' | 'grok'`. The optional `model` setting accepts a model ID from the selected agent; omit it to use that agent's default. A project key is optional in local Agent mode; set `projectKey` and `apiUrl` in the plugin options if you also want shared Comty comments.
+
+## Other development servers
+
+```sh
+npx comty dev --agent codex -- vite --strictPort
+# Next.js:
+npx comty dev --agent claude --target http://127.0.0.1:3000 -- next dev
+```
+
+Open the **Comty URL printed in the terminal** (by default `http://127.0.0.1:4387`). The application continues to run on its own port. HTTP and WebSockets are forwarded to it. `--target` must match that port; use a fixed port so a busy port cannot silently select a different application. The wrapper currently expects uncompressed HTML and buffers HTML responses up to 8 MiB. Prefer the direct Vite plugin when using Vite. Do not use the wrapper and plugin together.
+
+Optional flags: `--port`, `--model`, `--project-key`, `--api-url`. Without a command after `--`, the wrapper connects to an already-running local server.
+
+### Choose your coding agent
+
+Use the coding agent CLI already installed and signed in on your computer, then set `--agent` (or the Vite plugin's `agent` option). It must be available on the development server's `PATH`; no agent package is needed in your project. This selects a **coding agent**, not just a model API: the CLI reads the project, edits files and runs checks. Comty does not install the agent or provide its credentials. If the CLI is missing, install it once using that agent's instructions. If its version does not support your chosen model, update that existing CLI.
+
+To choose a model, add `model: 'your-agent-model-id'` to the Vite plugin or `--model your-agent-model-id` to `comty dev`. Model IDs belong to the selected agent and must be available on your account. Leave this option out to use its CLI default.
+
+| Agent | `agent` value | Existing CLI command |
+| --- | --- | --- |
+| Codex | `codex` | `codex` |
+| Claude Code | `claude` | `claude` |
+| Gemini CLI | `gemini` | `gemini` |
+| Grok Build | `grok` | `grok` |
+| Cursor | `cursor` | `agent` |
+
+With Vite or SvelteKit, set `comty({ agent: 'gemini' })` in `vite.config` and keep running `npm run dev`. With Next.js or another non-Vite server, keep the same `--agent` choice and set `--target` to its fixed local port. For example, put `"dev": "comty dev --agent grok --target http://127.0.0.1:3000 -- next dev -p 3000"` in `package.json`, then run only `npm run dev`. Open the Comty URL printed by the wrapper.
+
+Gemini CLI runs through its [ACP mode](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/acp-mode.md); Grok Build uses its [ACP stdio mode](https://docs.x.ai/build/cli/headless-scripting). Authenticate in the selected CLI before starting Comty. Gemini and Grok require versions with these ACP modes. If your CLI has no usable login, Comty reports the failure in the Agent panel.
+
+## Using the agent
+
+Comty resolves each agent through the development server's PATH: `codex`, `claude`, `agent` (Cursor), `gemini`, or `grok`. It reuses that CLI's configuration and login. Tool permission requests are relayed to the Comty sidebar; Claude uses a local MCP tool for this. Comty does not provision an AI subscription or credentials.
+
+1. Press **Shift A** to open Agent mode directly (localhost only), or select the `</>` Agent tool from the toolbar.
+2. Click an element.
+3. Ask a question or describe a change. **Apply globally** is off by default, so the request targets this element. Turn it on to request a change to every instance of the same component variant. The agent must identify that component and variant in source before applying the broader change. No Comty account is needed for this local flow.
+4. Work in progress is indicated on the element, without a progress toast. Click the Agent tool again to read the latest answer or change summary. Requested tool permissions and errors still appear when they need attention.
+5. In an existing shared comment thread, reply with `@Agent` to start a local agent task. Your question and the agent's response remain in the shared thread. This requires a project editor account, a project key, and the local companion running in your browser. Without `@Agent`, replies remain ordinary human comments.
+
+Each request starts its own agent session, so tasks can run at the same time in the same project directory. Concurrent agents can touch the same files; review overlapping changes. Cancel stops that task's agent; it does **not** revert changes already made. Requests time out after 30 minutes. Restarting the development server clears unfinished tasks from the sidebar without reverting any code changes. Existing `.comty/tasks.json` files from the older version are left untouched and are no longer read.
+
+Comty starts a separate agent session. It does not send instructions into an already-open Codex, Claude or Cursor conversation. Cursor requires a recent Cursor CLI with `agent acp` support; run `agent login` before using it. Legacy `cursor-agent` releases without ACP are unsupported.
+
+Direct Agent requests are never sent to the Comty API or its database. Their prompt and page context are sent to the selected AI provider by its coding agent. In a shared thread, the `@Agent` message and final answer are stored as comment replies; the thread transcript and page context are sent to the selected coding agent. Standard shared comments retain their existing Comty authentication and storage.
+
+Add `.comty/` to your application's `.gitignore`. Keep the companion on loopback; LAN binding, tunnels and production hosting are unsupported. Requests require the random token of the running development session and its exact origin.
+
+## Inspector annotations and area captures
+
+In Inspect (**Shift I**), choose **Annotate** (**D**) to draw with a pencil, rectangle, ellipse or arrow. Choose a stroke from the visual width buttons and a color from the swatches or the custom color picker. **⌘/Ctrl Z** undoes the last annotation; the trash button clears all drawings. **Escape** cancels an unfinished stroke, then exits the tool. Drawings follow document scrolling, remain when changing tools, and reset on navigation or reload.
+
+Choose **Capture area** (**S** while inspecting), then drag a rectangle in either direction to download a PNG. The image includes visible annotations, ruler strips, ruler guides, layout guides and distance measurements, without the toolbar or selection controls. **Escape** cancels. Captures stay local and use the existing DOM snapshot engine; inaccessible embedded pages and protected media may not appear exactly as rendered by the browser.
+
+The local Agent refreshes on entry and when returning to the tab. It polls only while tasks are pending or running; those progress checks do not reload shared comments. Inspector tools make no polling requests while idle.