cursor-companion-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# cursor-companion-ai
+
+An AI cursor that reads any web page and guides users by pointing at the exact element to interact with, with a short caption. Drop into any HTML page with one `<script>` tag.
+
+- Right-click anywhere → type a goal in plain English → the cursor flies to each step.
+- Two modes per goal: **Teach me** (highlight, you click) and **Do it for me** (autonomous, fills inputs + clicks through).
+- Works on any DOM-driven app — no `data-*` tags required (auto-labels elements from text / aria-label / nearby context).
+- BYOK: ship your own Anthropic API key and the library calls `api.anthropic.com` directly from the browser. No backend to host.
+
+## Quick start
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/cursor-companion-ai@latest/dist/companion.js"
+  data-anthropic-key="sk-ant-..."
+  data-context="This is My App. The 'Reports' tab is at the top. When users say 'export', they mean the download button in the toolbar."
+></script>
+```
+
+That's it. Reload the page → right-click anywhere → companion panel appears at the cursor → type a goal.
+
+## Configuration
+
+All config is via `data-*` attributes on the `<script>` tag.
+
+| Attribute | Required | What it does |
+|---|---|---|
+| `data-anthropic-key` | Yes (for direct mode) | Your Anthropic API key (`sk-ant-...`). The library calls Anthropic from the browser with this key. **Visible in page source** — see the security note below. |
+| `data-context` | Recommended | Plain-English description of your app: page names, terminology, conventions, edge cases. Prepended to every model call so the AI sounds like it knows your product. |
+| `data-endpoint` | Optional | If set, requests go to your own backend at this URL instead of direct Anthropic. Use this in production where the key shouldn't be in the browser. The backend just relays to Anthropic with a server-held key. |
+
+## Security note
+
+`data-anthropic-key` puts the key in your page's HTML and JS bundle. Anyone who views the page source can read it.
+
+- ✅ **Safe inside an authenticated dashboard** where only logged-in users see the script tag. They're trusted to not abuse the key, or each user supplies their own.
+- ✅ **Safe in dev environments** where you control who has access.
+- ❌ **NOT safe on a public marketing page** where any visitor can grab the key.
+
+For production / public deployments, run your own thin proxy at `/api/chat` and point `data-endpoint` at it. The proxy holds the key server-side and forwards requests. See [examples/proxy](#run-your-own-proxy-optional) below.
+
+## Programmatic API
+
+The script also exposes setters on the global window for runtime updates:
+
+```js
+// Update the context as the user navigates between pages
+window.companion.setContext("Now on /reports — exports go via the toolbar Download button.");
+
+// Replace the API key
+window.companion.setAnthropicKey("sk-ant-new-key");
+
+// Point at a different proxy
+window.companion.setEndpoint("https://my-proxy.example.com/api/chat");
+```
+
+(Programmatic setters are coming in 0.2; for now use the `data-*` attributes.)
+
+## Run your own proxy (optional)
+
+If you don't want the key in the browser, run a tiny proxy that forwards requests to Anthropic. The minimal Next.js route looks like:
+
+```ts
+// app/api/chat/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+export const runtime = "nodejs";
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  // Inject the server-side key — overrides anything the browser sent
+  body.anthropicKey = process.env.ANTHROPIC_API_KEY;
+  // Forward to your own /api/chat implementation or call Anthropic here.
+  // For a full reference, see the source repo: lib/guide.ts + app/api/chat/route.ts
+  const r = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "x-api-key": process.env.ANTHROPIC_API_KEY!,
+      "anthropic-version": "2023-06-01",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  return NextResponse.json(await r.json());
+}
+```
+
+Then on the script tag:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/cursor-companion-ai@latest/dist/companion.js"
+  data-endpoint="/api/chat"
+  data-context="..."
+></script>
+```
+
+## How it works
+
+Each step:
+
+1. The companion serializes every visible interactive element on the page (auto-labeled from `text`, `aria-label`, nearby headings/labels, etc.).
+2. Sends `{ goal, elements, history, context }` to Claude (direct from browser, or via your proxy).
+3. Claude returns one JSON object: which element to point at next + what to say.
+4. Cursor springs to the element, draws a highlight ring, shows the caption.
+5. After the user clicks (Teach mode) or after the auto-action (Do it for me), waits for the DOM to settle, then asks for the next step.
+6. Loops until done.
+
+If Claude can't tell what to do from text alone, it can ask for a screenshot via a `request_screenshot` tool — captured client-side via `html2canvas`, sent back as an image.
+
+## Bundle
+
+- ~970 KB minified, ~250 KB gzipped over the wire.
+- Includes: React + ReactDOM, framer-motion (cursor + ring animations), html2canvas (screenshot tool), the bundled Anthropic SDK, the companion components, and a Tailwind CSS slice scoped to the companion's UI.
+
+## Build from source
+
+```bash
+git clone https://github.com/your-handle/cursor-companion.git
+cd cursor-companion
+npm install
+npm run build:embed         # produces dist/companion.js
+npm run dev                 # Next.js demo at http://localhost:3000
+```
+
+The demo at `/dashboard-complex` shows the companion guiding through a construction-supply-chain CRM with 9 pages of inputs, modals, tabs, and a kanban board.
+
+The demo at `/embed-demo.html` shows the same companion mounted on a plain HTML page via the `<script>` tag — no React or Tailwind on the host.
+
+## License
+
+MIT. Use it, fork it, ship it.