@comty.io/core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @comty.io/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`.
+
+Requires Node.js 22.12 or newer for the development tools.
+
+## Browser SDK
+
+```sh
+npm install @comty.io/core
+```
+
+```js
+import { initComty } from '@comty.io/core';
+
+await initComty({
+  projectKey: 'YOUR_PROJECT_KEY',
+  apiUrl: 'https://YOUR_COMTY_API',
+});
+```
+
+Call once from your application entry. Server rendering is safe: it does nothing until called in a browser. Repeated calls with the same options reuse the document's instance. Reload the page to change its project or API URL. Register the site's domain in Comty to use shared comments.
+
+The standalone script remains available at your existing CDN URL:
+
+```html
+<script src="https://YOUR_COMTY_CDN/v1/comty-sdk.js"
+  data-project-key="YOUR_PROJECT_KEY"
+  data-api-url="https://YOUR_COMTY_API"></script>
+```
+
+Choose one browser entry per page (npm, development injection, or CDN). Both distributions are generated from `src/browser.js`.
+
+## Color tokens
+
+Element inspection shows a copyable CSS custom-property name above foreground/background colors when the winning declaration can be identified. It handles ordinary selectors, `:where()`, inline styles, inheritance, `!important`, active media/supports rules and named top-level cascade layers. Semantic aliases retain their declared name. No extra line is rendered for literal colors or uncertain provenance (including inaccessible stylesheets, shadow/scoped or nested cascades, and unsupported functional selectors).
+
+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.
+
+## Live motion
+
+Open inspection with **Shift I**, then select the stopwatch or press **M**. Drag the speed gauge directly: **0.1×–1×**, in 0.1 steps. Its fill and handle track the value; arrow keys and Home/End work too. The whole page remains interactive. Hover, click and open panels normally; new native animations are detected as they appear. At 0.2×, a 100 ms transition has a nominal playback duration of 500 ms. Detection can occur after its first frame.
+
+**Pause** holds controlled animations, including new ones. **Escape** closes Motion. Closing Motion or switching tools restores the original playback rates and releases pauses introduced by Comty, while preserving animations that were already paused by the application.
+
+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.
+
+## Development
+
+```sh
+cd sdk
+npm ci
+npm run build
+npm test
+npm run check:build
+npm run test:vite
+```
+
+Vite is a development dependency used by the integration test; it is not included in the published package.
+
+For browser checks, run `bun sdk/tests/serve.mjs` from the repository root. Open `http://127.0.0.1:4178/` for the comment/inspector regression suite, or `http://127.0.0.1:4178/motion` for the interactive live-motion lab and slowdown checks. The test bridge is injected by that local server only and is not included in the published SDK.
+
+From the repository root, run `bun sdk/tests/serve.mjs`, open the printed URL and select **Run regression checks**. Edit `src/browser.js`, never the generated `comty-sdk.js`.
+
+See the repository's `doc.md` for publication, CDN deployment, verification and rollback steps.