gazesight 0.3.5

package/LICENSE

@@ -0,0 +1,37 @@
+GazeSight — Proprietary Software License
+All Rights Reserved
+
+Copyright (c) 2026 the GazeSight project. All rights reserved.
+
+This software and its accompanying source code, documentation, and assets
+(collectively, "the Software") are proprietary and confidential. The
+Software is licensed, not sold.
+
+No license, right, or interest in the Software is granted except as
+expressly set out in the Terms of Use accompanying a distributed copy of
+the Software, or as separately authorized in writing by the copyright
+holder.
+
+Except where required by applicable law or expressly authorized in
+writing by the copyright holder, no person may:
+
+  - copy, reproduce, or redistribute the Software, in whole or in part;
+  - modify, adapt, translate, or create derivative works based on the
+    Software;
+  - sublicense, sell, rent, lease, or otherwise transfer rights in the
+    Software;
+  - reverse engineer, decompile, or disassemble the Software, except to
+    the extent such restriction is prohibited by applicable law.
+
+Use of any distributed build of the Software (including the Firefox
+browser extension) is governed by the Terms of Use published alongside
+that distribution.
+
+Third-party dependencies bundled with or used to build the Software
+remain licensed under their own respective licenses, as declared in this
+repository's package manifests and associated license inventories. This
+proprietary license does not extend to those third-party components.
+
+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.

package/README.md

@@ -0,0 +1,102 @@
+# GazeSight
+
+**GazeSight — Browser vision for coding agents.**
+
+**Let your coding agent see what you see.**
+
+GazeSight lets coding agents inspect the browser tab you're already using, without launching another browser session. Firefox is fully supported and Mozilla-approved (0.3.4). Chrome is supported via manual installation while it awaits Chrome Web Store review. Node.js 20+ and an MCP coding agent with image support are required. Technical decisions and measured results live in `GAZESIGHT_MASTER_SPEC.md` in the source repository.
+
+## Install and first capture
+
+```sh
+npx gazesight setup
+```
+
+This is not yet published to the npm registry (see [Release maintainers](#release-maintainers)). Until it is, install the tarball supplied with this preview:
+
+```sh
+npm install -g ./gazesight-0.3.4.tgz
+gazesight setup
+```
+
+After publication, `npx gazesight setup` and `npm install -g gazesight && gazesight setup` are equivalent entrypoints.
+
+1. **Firefox**: install the separately supplied **Mozilla-signed GazeSight 0.3.4** XPI through about:addons > gear > Install Add-on From File. Do not disable signature verification. Developers can load the manifest printed by setup temporarily in about:debugging; this is a development fallback only.
+   **Chrome**: open chrome://extensions, enable Developer mode, click "Load unpacked", and select the `dist/chrome` directory printed by setup. Chrome Web Store listing is prepared but not yet submitted; this manual path is the only installation method until then.
+2. Open the extension's options page (Firefox: extension options; Chrome: right-click the toolbar icon > Options, or chrome://extensions > Details > Extension options). Import the local config JSON at the path printed by setup, then save. No token copy is required.
+3. Run `gazesight setup` in a real terminal (not piped/scripted). It detects Claude Code and/or Codex on your PATH and asks which to configure — or configure both non-interactively with `gazesight setup --client both` (or `--client claude` / `--client codex`). When a client is detected, setup registers GazeSight with it directly (`claude mcp add` / `codex mcp add` under the hood, at user scope) — no manual file editing, and re-running is safe (it detects an existing registration and leaves it unchanged). If a client isn't detected on PATH, setup instead prints the manual `.mcp.json`/`config.toml` snippet for you to merge by hand. Restart the agent to load MCP.
+4. Open your local project in your browser, keep its tab active, and click the GazeSight toolbar icon ("Use this tab").
+5. Run `gazesight doctor`. Run it **while your coding agent's MCP connection to GazeSight is active** — the health checks it reports depend on that session being live, the same way any MCP tool call would.
+6. Ask your agent: "Use GazeSight visual_capture to inspect my active preview tab." The image arrives directly as MCP image content.
+
+Claude Code stores user-scope servers in `~/.claude.json`; Codex uses `~/.codex/config.toml` with `[mcp_servers.gazesight]`. Setup generates installation-specific Node/CLI paths; it never relies on a developer's source checkout. See [Claude Code MCP docs](https://code.claude.com/docs/en/mcp-quickstart) and [Codex MCP docs](https://developers.openai.com/codex/mcp/).
+
+## Capture and permissions
+
+FAST is the default (`waitForStable: false`). STABLE (`waitForStable: true`) observes local DOM/resources/layout activity with a 100ms quiet window, two frames, and a 2000ms deadline. It means **render appears stable**, not "HMR finished." A future delayed update can still arrive later. Continuous animation or unfinished resources can cause an explicit timeout.
+
+HMR ordinarily preserves application state. Explicit reload/navigation replaces the document and can reset it. After a new document, the REAUTH badge and `GS_REAUTHORIZE_TARGET` ask you to click the icon again. GazeSight never grants permission or chooses a replacement tab automatically.
+
+## Doctor and troubleshooting
+
+```sh
+gazesight doctor
+gazesight --help
+```
+
+Doctor is read-only and reports corrective actions for Node/build, MCP/port, connection/pairing, target and capture permission. **Run it while your coding agent's MCP session is active** — the MCP server's own health-check endpoint only stays reachable while a real MCP client holds its stdio connection open (this is intentional: the same signal that tells GazeSight a session ended). Only one GazeSight server can own a port; stop a competing agent or configure a different port with `gazesight setup --config PATH --port PORT` and import that config into the extension. Existing config is reused without overwriting its token or port. `GS_NO_TARGET_TAB`: select a local preview with the icon. `GS_NOT_CONNECTED`: check extension options and agent MCP startup. An inactive target is refused; return to that tab. Nothing launches a browser for you.
+
+## Local configuration
+
+Windows: `%APPDATA%/GazeSight/config.json`. macOS: `~/Library/Application Support/GazeSight/config.json`. Linux: `$XDG_CONFIG_HOME/gazesight/config.json`, or `~/.config/gazesight/config.json`. Override with `--config PATH` or `GAZESIGHT_CONFIG_FILE`. Run GazeSight setup to create a fresh pairing configuration. No previous configuration or token is copied or deleted. Files are created exclusively with mode 0600 where supported; Windows uses inherited directory ACLs. Keep the private config in your own user directory.
+
+## Privacy and security
+
+The bridge binds only 127.0.0.1 and requires a random 256-bit pairing token. No GazeSight backend, telemetry, startup task or persistent service is installed. Images are not written to disk by default. Captures, selected URLs, runtime errors and browser status travel to your local coding agent; that agent may send image/content to its model provider according to its own settings — GazeSight does not claim that no data ever leaves your device once your agent is in the loop. Select only tabs you intend to share. No arbitrary page JavaScript execution is exposed. External website origins are disabled unless explicitly configured in both extension and server. Full policy: https://www.gazesight.dev/privacy/
+
+## Uninstall
+
+```sh
+npm uninstall -g gazesight
+```
+
+Remove the MCP entry from your agent (`claude mcp remove gazesight -s user`, or `codex mcp remove gazesight`, or delete the manual `.mcp.json`/`config.toml` entry) and the extension from your browser, then stop/restart that agent to close its MCP process and release the port. Uninstall retains the private config. Delete it manually if desired; no user data is automatically removed.
+
+## Closed preview and TTFC
+
+Signed XPI installation in normal Firefox and the complete first-run flow must pass before Closed Developer Preview GO. Five future testers can manually fill `docs/preview-matrix.csv`; no results are uploaded automatically. Time To First Capture (TTFC) starts **before installation/setup** and ends when the coding agent first receives a successful image. Record start/end locally with a stopwatch or timestamps, including manual steps; target under 3 minutes is indicative, not a build gate. A developer's already-paired capture latency is not a new-user TTFC measurement.
+
+## Release maintainers
+
+Build validated on Windows x64 with Node 24.15.0. Real npm-package installation validated end to end on Windows (clean `npm pack` tarball installed into an isolated directory outside the monorepo, then CLI/`setup`/`doctor`/`mcp` all exercised against real client connections). macOS and Linux are not code-path-specific (cross-platform config paths, standard `#!/usr/bin/env node` shebang, no Windows-only APIs) but have not been independently installed and tested on those OSes — treat that as not-yet-validated, not as validated by inference. Use Node 22+ for Mozilla release tooling (runtime package remains Node 20+). Install the exact dependencies through package-lock.json.
+
+```sh
+npm ci
+npm run build
+npm run lint
+npm run typecheck
+npm test
+npm run extension:lint
+npm run release
+```
+
+Root `package.json` is the canonical version; `npm run build` synchronizes internal packages, manifest and generated runtime version. `npm run release` creates a tarball, a clearly unsigned Firefox XPI and SHA-256 checksums in `release/`. `npm pack` produces the actual npm publication tarball (52 files as of this writing: CLI, MCP server, worker, Firefox and Chrome extension builds, README, LICENSE, `docs/preview-matrix.csv` — never the monorepo's TypeScript source, tests, or experiments). `npm run extension:sign` requires `WEB_EXT_API_KEY` (AMO JWT issuer) and `WEB_EXT_API_SECRET` (AMO JWT secret) in the environment. It uses Mozilla's unlisted channel; credentials never enter source or command arguments. Build/lint first, then sign; no signed filename is generated without a successful Mozilla response and signature entries. Re-run release for checksums after signing. Provide reproducible TypeScript source/build instructions to AMO reviewers if requested; never include credentials or private config. See [Mozilla signing guide](https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/).
+
+### npm publication
+
+The `gazesight` name is unclaimed on the npm registry (verified via `npm view gazesight`, HTTP 404). Root `package.json` has `"private": true` as a deliberate guard against an accidental `npm publish`; removing it is a conscious, separate step the maintainer takes immediately before a real publish, not something any build/release script does automatically. Prefer npm's Trusted Publishing (OIDC from a GitHub Actions workflow, no long-lived `NPM_TOKEN` stored anywhere) if you set up CI for this; otherwise publish from a trusted local machine with 2FA/OTP. Never commit an npm token to this repository. After a real publish, verify from a clean environment:
+
+```sh
+npx --yes gazesight@latest setup
+npx --yes gazesight@latest doctor
+```
+
+## Before distribution
+
+The permanent Firefox add-on identity is **extension@gazesight.dev**, using the domain confirmed as controlled by the owner. GazeSight has its own unlisted AMO submission and a genuinely Mozilla-returned signed 0.3.4 XPI. The signed payload matches the submitted build. Normal Firefox installation, pairing and native capture validation must complete before external distribution. Chrome Web Store submission materials (listing copy, screenshots, promotional assets, reviewer instructions) are prepared under `release/gazesight-chrome-cws-*`; submission itself awaits explicit owner approval. Previous project evidence is archived separately in the source repository; it does not validate this build.
+
+The project license is proprietary, all rights reserved (see LICENSE).
+
+## Environment
+
+`GAZESIGHT_CONFIG_FILE` selects the private config. Explicit environment settings take priority: `GAZESIGHT_PAIR_TOKEN` (64 hexadecimal characters), `GAZESIGHT_PORT` (32147), `GAZESIGHT_TIMEOUT_MS` (10000), `GAZESIGHT_ALLOWED_ORIGINS` (comma-separated exact origins), `GAZESIGHT_DEBUG_DIR` (image disk output, disabled by default). MCP status is `gazesight://status`; doctor uses authenticated loopback `/gazesight/status`.

package/dist/chrome/background-capture-offscreen.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>GazeSight background capture</title>
+  </head>
+  <body>
+    <script type="module" src="background-capture-offscreen.js"></script>
+  </body>
+</html>

package/dist/chrome/background-capture-offscreen.js

@@ -0,0 +1 @@
+chrome.runtime.onMessage.addListener((a,m,i)=>{if(a?.type==="gazesight-background-capture-offscreen")return(async()=>{let r;try{r=await navigator.mediaDevices.getUserMedia({audio:!1,video:{mandatory:{chromeMediaSource:"tab",chromeMediaSourceId:a.streamId}}});let e=document.createElement("video");e.srcObject=r,e.muted=!0,await e.play();let c=e.currentTime;for(let o=0;o<20&&(await new Promise(s=>setTimeout(s,100)),!(e.currentTime>c+.05));o++);let t=document.createElement("canvas");t.width=e.videoWidth,t.height=e.videoHeight;let n=t.getContext("2d");if(!n)throw new Error("2D context unavailable in offscreen document");n.drawImage(e,0,0);let d=(a.format==="jpeg"?"jpeg":"png")==="jpeg"?t.toDataURL("image/jpeg",Number(a.quality??85)/100):t.toDataURL("image/png");i({ok:!0,dataUrl:d,width:t.width,height:t.height})}catch(e){i({ok:!1,error:String(e)})}finally{r?.getTracks().forEach(e=>e.stop())}})(),!0});