@comty.io/core 0.1.4 → 0.1.6

package/README.md

@@ -1,12 +1,22 @@
 # @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
 
 Posting immediately displays a pending comment and sends the JSON request. After the API confirms the save, the SDK captures and uploads the viewport separately. Screenshot failures do not roll back comments; save failures restore the draft for retry. Screenshot annotations reuse the real Comty pin and hover card (avatar, author, date and content). They are measured in an invisible, inert host, then cloned with their computed styles and embedded resources into the screenshot. The temporary host is removed after cloning and never appears on screen.
 
-The bundled capture engine is based on `html-to-image` 1.11.13 (MIT), not SnapDOM. It embeds web fonts, responsive images, CSS backgrounds and pseudo-elements, preserves scroll offsets, and yields during DOM traversal. Offscreen leaf boxes keep their layout dimensions without their rendering cost. PNG is preferred for text; large images fall back to JPEG. Captures are capped at 2× resolution / 2560 pixels per side and have a 15-second processing deadline.
+The bundled capture engine is based on `html-to-image` 1.11.13 (MIT), not SnapDOM. It embeds web fonts, responsive images, CSS backgrounds and pseudo-elements, preserves scroll offsets, and yields during DOM traversal. Each font face keeps its source when selecting WOFF2, including consecutive subset and weight rules. Transparent page backgrounds are composited over the browser's light or dark canvas so the image viewer cannot tint the screenshot. Offscreen leaf boxes keep their layout dimensions without their rendering cost. PNG is preferred for text; large images fall back to JPEG. Captures are capped at 2× resolution / 2560 pixels per side and have a 15-second processing deadline.
 
 Resources are fetched directly first. Public cross-origin assets blocked by CORS can use `/api/sdk/capture-resource`, authenticated with the SDK token and restricted to the project's allowed domain. The API validates and pins public DNS addresses on every redirect, limits bytes/concurrency/time, and never forwards credentials to resource hosts. Deploy the API alongside the SDK to enable this fallback.
 
@@ -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,65 @@ 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
+
+Install and sign in to the coding agent CLI you want to use, then set `--agent` (or the Vite plugin's `agent` option). 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.
+
+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 | CLI to install and sign in to |
+| --- | --- | --- |
+| 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
+
+Codex and Claude use the project's local CLI when present, otherwise `codex` or `claude` on PATH. Cursor uses `agent`, Gemini uses `gemini`, and Grok Build uses `grok` on PATH. 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. Open the toolbar with Shift S or Shift I.
+2. Select the `</>` Agent tool and 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.