@comty.io/core 0.1.2 → 0.1.4

package/README.md

@@ -1,8 +1,20 @@
 # @comty.io/core
 
-Comty's browser SDK and development companion have no npm package dependencies. The Node companion runs the locally installed Codex, Claude or Cursor CLI and stores technical requests in your project's `.comty/tasks.json`.
+Comty's browser SDK provides shared comments and an element inspector, with no npm package dependencies.
 
-Requires Node.js 22.12 or newer for the development tools.
+## 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.
+
+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.
+
+The capture never locks or restyles the live page. If the URL, viewport or page scroll changes before cloning finishes, it skips that screenshot rather than attaching a mismatched image. Browser restrictions still apply to private resources, closed shadow roots and embedded frames; inaccessible frames retain an empty layout box. The final SVG serialization/rasterization still uses browser APIs on the main thread, so zero processing cost on every possible site cannot be guaranteed.
+
+`npm run build` reproducibly bundles the pinned library with small checked hooks for cooperative scheduling, resource fetching, cloning and exact font sizes; its MIT notice is included. No runtime package install is needed by SDK consumers. `npm run test:capture` runs Chrome/Chromium visual and posting tests; install Chromium with `npx playwright install chromium` on machines without Chrome. Comparison PNGs are written to `test-results/`.
+
+Visual tests disable screen-only LCD text antialiasing so the native reference and SVG/canvas capture use grayscale rendering. They reuse the comparator bundled with the pinned Playwright version and keep a 1% changed-pixel limit. Negative controls verify that missing fonts, images, comment markers and link underlines still fail; scrolled containers also have their own comparison region. CI uploads reference, capture and difference PNGs on failure. Review the comparator's internal imports when upgrading Playwright.
 
 ## Browser SDK
 
@@ -27,6 +39,10 @@ Element inspection shows a copyable CSS custom-property name above foreground/ba
 
 The toolbar pipette shows a circular nine-pixel magnifier from a local DOM snapshot, keeping the toolbar interactive with normal UI cursors. Its light/dark ring follows the sampled colour. Scrolling or resizing refreshes the snapshot. Inaccessible images, canvas/video, external fonts and live animations may differ from screen pixels; use native screen sampling for those. If a readable snapshot cannot be created, selection falls back to the element’s CSS colour. Shift-click the pipette in Chrome or Edge to sample screen pixels instead (including images). The screen pipette receives a pixel color and copies its HEX value. When an inspected element has an identifiable background token whose rendered color matches the sample, the toast shows that token as **Element token · --name**. The native pipette does not report which element produced the pixel, so the label describes the inspected element rather than attributing the sampled pixel. Matching variable values alone do not produce a label. No additional dependency is required.
 
+## 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.
+
 ## Border measurements
 
 Open inspection with **Shift I**, then choose the ruler tool or press **R**. Move close to an element or page border: a red point marks the snapped start and the cursor shows the measurement axis. Drag to another border to measure its distance. Horizontal borders produce vertical measurements; side borders produce horizontal measurements. Releasing away from a border keeps the endpoint at that page position.
@@ -42,47 +58,3 @@ 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', model: 'gpt-6-luna' })],
-});
-```
-
-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. The `model` option selects any model supported by your installed Codex CLI; omit it to use your Codex default. Use `agent: 'claude'` or `agent: 'cursor'` to select another provider. 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` (Codex only), `--project-key`, `--api-url`. Without a command after `--`, the wrapper connects to an already-running local server.
-
-## Using the agent
-
-Install and sign in to your selected coding agent first. Codex and Claude use the project's local CLI when present, otherwise `codex` or `claude` on PATH. Cursor uses `agent` on PATH. Claude's permission requests are relayed to the same Comty sidebar through a local MCP tool. 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. Describe your change and submit. No Comty account is needed.
-4. Use History in the Code toolbar to show or hide the Local agent sidebar. Review any requested tool permissions there; allow once or deny.
-5. Completed tasks disappear from the page. Their result and verification remain in History. Errors remain visible and can be retried after reviewing partial edits.
-
-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 and remain available for review. Neither normal operation nor shutdown deletes task history.
-
-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.
-
-Technical 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. 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.