Release 1.1.0: header icon actions, pin fixes, test design policy and E2E in CI

.claude/skills/testing/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: testing
+description: NeedMark's procedure for adding, changing, running and pruning tests. Use whenever a change in this repository adds or alters behaviour, fixes a bug, touches tests under src/**/*.test.ts or tests/*.spec.ts, or when reviewing or trimming the test suites, so each check lands in the smallest layer that can catch it and the browser suite stays small.
+---
+
+# Testing in NeedMark
+
+The rules live in [`docs/testing.md`](../../../docs/testing.md); this skill is the order to apply them in. Read the Principles, Layers and sizes, and What not to test sections of that document before writing a test.
+
+## 1. Decide what to prove
+
+- Write the behaviour as one sentence a user or caller would recognise: "Leaving details hides the target outline", not "clearLocated hides outline".
+- For a bug, that sentence is the expected behaviour the bug violates. You will reproduce it first.
+- If the change only alters styling or copy, plan a demo check instead of a test.
+
+## 2. Pick the smallest layer
+
+Ask, in order, and stop at the first yes:
+
+1. Can it be called with plain data and no I/O? → small Vitest test next to the source file.
+2. Does it need files or a localhost server, but no browser? → medium Vitest test (temporary directory, free port).
+3. Does the outcome depend on layout, rendering, events, browser APIs, or the full widget–server–files flow? → Playwright spec.
+
+For a Playwright test, also decide whether WebKit could behave differently (rendering and capture, hit testing, carets and ranges, frames and shadow roots, stack formats, native dialogs, style inheritance, pointer and keyboard events, media). Only then add `{ tag: '@cross-engine' }`.
+
+## 3. Look for an existing test first
+
+- Search by behaviour: `grep -rn "<key word>" src --include='*.test.ts' tests/*.spec.ts`.
+- If a test already drives the same flow and the new assertion belongs to the same behaviour, extend it. Otherwise add a new, focused test.
+- If the same rule is already checked at a lower layer, do not add it in the browser.
+
+## 4. Write it
+
+- Arrange, act, assert, in straight lines; show the inputs that matter in the test body.
+- Name the test after the behaviour and outcome.
+- Playwright: import `test`, `expect` and helpers from `tests/support/review.ts`; locate by role, label and text; wait with web-first assertions or `expect.poll`, never with a fixed timeout; stub slow or flaky transports with `page.route`.
+- Vitest: build data from `tests/fixtures.ts`; clean up temporary directories and servers in `afterEach`.
+- For a bug, run the new test before the fix and confirm it fails for the reason you expect.
+
+## 5. Run
+
+- While iterating: `pnpm test <file>`, or `pnpm build` then `pnpm test:e2e <spec> -g "<title>" --project=chromium`.
+- Before committing: `pnpm build`, `pnpm typecheck`, `pnpm test` and `pnpm test:e2e` all pass. A full E2E run takes about ten minutes; run it in the background and report the summary line.
+- Check user-facing changes in the demo as described in docs/testing.md#manual-check.
+
+## 6. Leave the suite smaller or equal where you can
+
+- When your change makes a test redundant (same rule at a lower layer, or a flow another test already covers), delete or merge it in the same change.
+- Remove assertions on styling or decoration you come across in the tests you touch.
+- If you notice a flaky test, fix the race; do not add retries or longer timeouts.
+
+## Checklist
+
+- [ ] The behaviour is stated as a sentence and the test name says it.
+- [ ] The test is at the smallest layer that can catch the failure.
+- [ ] A bug fix has a test that failed before the fix.
+- [ ] No styling, static copy or type-level guarantees are asserted.
+- [ ] `@cross-engine` only where WebKit could behave differently.
+- [ ] Redundant tests touched by the change were removed or merged.
+- [ ] `pnpm build`, `pnpm typecheck`, `pnpm test`, `pnpm test:e2e` pass.

.github/workflows/ci.yml

@@ -31,3 +31,26 @@ jobs:
       - run: pnpm build
       - run: pnpm typecheck
       - run: pnpm test
+
+  e2e:
+    name: E2E
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm exec playwright install --with-deps chromium webkit
+      # Chromium runs headed for the native tab-picker tests, so it needs a virtual display.
+      - run: xvfb-run --auto-servernum pnpm test:e2e
+      - if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-traces
+          path: test-results/
+          retention-days: 7

.github/workflows/pages.yml

@@ -0,0 +1,32 @@
+name: Pages
+
+on:
+  push:
+    branches: [main]
+    paths: [site/**, .github/workflows/pages.yml]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -7,3 +7,9 @@ test-results/
 playwright-report/
 *.tgz
 .DS_Store
+examples/*/.needmark/
+examples/*/dist/
+examples/astro/.astro/
+examples/next/.next/
+examples/next/next-env.d.ts
+examples/next/tsconfig.tsbuildinfo

AGENTS.md

@@ -10,6 +10,17 @@ Common rules for developing and maintaining NeedMark. They apply to every agent
 - `.mise.toml` and `package.json#packageManager` are the version source of truth.
 - Do not push, publish or create releases unless explicitly asked. Changing `package.json#version` on `main` publishes to npm ([`docs/releasing.md`](./docs/releasing.md)), so bump it only when a release is requested.
 
+## Procedures and skills
+
+| Task | Reference | Claude Code skill |
+| --- | --- | --- |
+| Adding, changing, running or pruning tests | [`docs/testing.md`](./docs/testing.md) | `testing` |
+| Writing or reviewing code comments in `src/` | This file, [Source layout](#source-layout) | `code-comments` |
+| Checking a user-facing change by hand | [`docs/testing.md#manual-check`](./docs/testing.md#manual-check) | `testing` |
+| Releasing to npm | [`docs/releasing.md`](./docs/releasing.md) | — |
+
+Skills live in `.claude/skills/`. They hold procedures only; rules and behaviour stay in this file and `docs/`, which a skill links to instead of repeating.
+
 ## Product boundaries
 
 - Keep NeedMark independent of the hosted NeedBack service: no imports from its repository and no requirement on its API.
@@ -21,7 +32,7 @@ Common rules for developing and maintaining NeedMark. They apply to every agent
 
 - `src/index.ts`, `src/proxy.ts` and `src/cli.ts` are the only public entries. Add another only with `package.json#exports` and `scripts/build.mjs`.
 - `src/shared/` is browser-safe code for both sides, `src/server/` is Node only, and `src/client/` is the browser bundle (`capture/`, `context/`). Shared code imports neither side nor `node:`; client code never imports server code or `node:`; server code never imports client code. `src/structure.test.ts` enforces this.
-- Keep unit tests next to the file they test, and name files by responsibility inside their directory.
+- Keep unit tests next to the file they test, and name files by responsibility inside their directory. Browser specs live in `tests/` and share setup through `tests/support/`.
 - Code comments explain why an implementation was chosen, in English and Japanese, and never restate the specification (`src/comments.test.ts` checks both languages are present; Claude Code loads the `code-comments` skill).
 
 **Tradeoff:** the guidelines below favor caution over speed. Use judgment for trivial tasks.
@@ -58,9 +69,9 @@ Common rules for developing and maintaining NeedMark. They apply to every agent
 **Define success criteria. Loop until verified.**
 
 - Turn tasks into verifiable goals: "fix the bug" → "write a failing test that reproduces it, then make it pass"; "refactor X" → "tests pass before and after".
-- Follow [`docs/testing.md`](./docs/testing.md) to choose test layers and for the manual check in the demo.
-- Update existing tests in the same change when behavior changes intentionally.
-- A task is not done until `pnpm typecheck`, `pnpm test`, `pnpm build` and `pnpm test:e2e` pass, and user-facing changes were checked in the demo.
+- Follow [`docs/testing.md`](./docs/testing.md): test behaviour through public interfaces, at the smallest layer that can catch the failure, one behaviour per test. Browser tests are for what needs a real engine; tag them `@cross-engine` only when WebKit could behave differently.
+- Update existing tests in the same change when behavior changes intentionally, and delete or merge tests the change makes redundant instead of adding more beside them.
+- While iterating, run the tests the change touches. A task is not done until `pnpm typecheck`, `pnpm test`, `pnpm build` and `pnpm test:e2e` pass, and user-facing changes were checked in the demo.
 - For multi-step work, state a short plan with a verification for each step.
 
 ---

CONTRIBUTING.md

@@ -17,8 +17,8 @@ The project rules for contributors and coding agents are in [AGENTS.md](AGENTS.m
 ## Pull requests
 
 - Keep each pull request focused on one change.
-- Add or update tests as described in [docs/testing.md](docs/testing.md).
-- Before opening it, make sure `pnpm build`, `pnpm typecheck`, `pnpm test` and `pnpm test:e2e` pass. For changes to packaging, the CLI or dependencies, also run `pnpm test:package-managers`.
+- Add or update tests as described in [docs/testing.md](docs/testing.md): at the smallest layer that can catch the failure, one behaviour per test, and with a failing test first for bug fixes. Remove tests your change makes redundant.
+- Before opening it, make sure `pnpm build`, `pnpm typecheck`, `pnpm test` and `pnpm test:e2e` pass (CI runs all four). Install the browsers once with `pnpm exec playwright install chromium webkit`. For changes to packaging, the CLI or dependencies, also run `pnpm test:package-managers`.
 - Check user-facing changes in the demo.
 - Leave `version` in `package.json` unchanged; maintainers bump it when releasing ([docs/releasing.md](docs/releasing.md)).
 

README.ja.md

@@ -22,37 +22,21 @@ Node.js 22.12以降が必要です。アプリケーションのプロジェク
 
 ```sh
 pnpm add -D needmark   # npm install -D needmark / yarn add -D needmark
-pnpm exec needmark init --language=ja
+pnpm exec needmark init
+pnpm dev               # いつもの開発コマンド
 ```
 
-例はpnpmで記載しています。npmでは`npx needmark`、Yarnでは`yarn needmark`でCLIを実行します。初期設定の案内とAIへの指示には、プロジェクトのロックファイルに合ったコマンドが入ります。
+いつもどおりアプリを開くと、ページ下部にNeedMarkのツールバーが表示されます。例はpnpmで記載しています。npmでは`npx needmark`、Yarnでは`yarn needmark`でCLIを実行します。
 
-初期設定で`needmark.config.ts`と用途に応じたGitの除外ルールを作成します。ターミナルではローカル・Git共有と撮影方法を選びます。英語にする場合は`--language=en`を指定します。[非対話実行の全フラグ](docs/getting-started.ja.md#インストールと初期設定)はガイドに記載しています。
+`init`は推奨設定を示し、同意するとNeedMarkを開発サーバーにつなぎます。アプリのソースと本番ビルドには触れません。
 
-### Vite
+| プロジェクト | `init`が変更するもの |
+| --- | --- |
+| Vite（React、Vueなど） | `vite.config.*`の`plugins`に`needmark()`を追加 |
+| Astro | `astro.config.*`に`vite: { plugins: [needmark()] }`を追加 |
+| Next.js | `dev`スクリプトを`needmark dev --`経由にする。いつものポートのままNext.jsをその裏で動かします |
 
-既存のVite設定にプラグインを明示的に追加します。
-
-```ts
-import { defineConfig } from 'vite';
-import { needmark } from 'needmark';
-
-export default defineConfig({
-  plugins: [needmark()],
-});
-```
-
-プラグインは開発時だけ動作し、本番ビルドと`vite preview`には入りません。引数なしで呼ぶと、Viteを起動したディレクトリの`needmark.config.ts`を読み込みます。`localhost`、`127.0.0.1`、`[::1]`では設定なしで動作します。LANのアドレスやトンネルなど別のホスト名でレビューする場合だけ`origins`を指定します。
-
-### Next.jsなどの開発サーバー
-
-通常の方法でアプリケーションを起動し、同じプロジェクトで次を実行します。
-
-```sh
-pnpm exec needmark dev --target=http://localhost:3000
-```
-
-`http://localhost:4190`を開きます。プロキシはアプリのimportやビルドを変更せずにウィジェットを追加します。対象とレビュー先は異なるループバックHTTPオリジンが必要です。詳しくは[プロキシの設定と制約](docs/getting-started.ja.md#nextjsなどの開発サーバー)を参照してください。
+あわせて`needmark.config.ts`と用途に応じたGitの除外ルールを作ります。`NEEDMARK=off pnpm dev`で自分だけNeedMarkなしで起動でき、`needmark.config.ts`の`enabled: false`で全員分を止められます。`pnpm exec needmark remove`で接続を元に戻せます。`init`が読めない設定やほかの開発サーバーは、[はじめに](docs/getting-started.ja.md#開発サーバーにつなぐ)の手順で手動で設定します。[非対話実行の全フラグ](docs/getting-started.ja.md#インストールと初期設定)も記載しています。
 
 ## コメントして、AIに渡して、確認する
 

README.md

@@ -22,37 +22,21 @@ Requires Node.js 22.12 or newer. In your application project:
 
 ```sh
 pnpm add -D needmark   # npm install -D needmark / yarn add -D needmark
-pnpm exec needmark init --language=en
+pnpm exec needmark init
+pnpm dev               # your usual development command
 ```
 
-Examples use pnpm. With npm run the CLI as `npx needmark`, with Yarn as `yarn needmark`. Initialization output and agent prompts use the command that matches your project's lockfile.
+Open the app as usual; the NeedMark toolbar appears at the bottom of the page. Examples use pnpm. With npm run the CLI as `npx needmark`, with Yarn as `yarn needmark`.
 
-Initialization creates `needmark.config.ts` and targeted Git ignore rules. In a terminal, choose local/Git sharing and capture method. Use `--language=ja` for Japanese; [all noninteractive flags](docs/getting-started.md#install-and-initialize) are documented in the guide.
+`init` shows recommended settings and, with your consent, connects NeedMark to the development server. It never touches application source or production builds:
 
-### Vite
+| Project | What `init` changes |
+| --- | --- |
+| Vite (React, Vue and others) | Adds `needmark()` to `plugins` in `vite.config.*` |
+| Astro | Adds `vite: { plugins: [needmark()] }` to `astro.config.*` |
+| Next.js | Starts the `dev` script through `needmark dev --`, which keeps your usual port and runs Next.js behind it |
 
-Add the plugin explicitly to your existing Vite configuration:
-
-```ts
-import { defineConfig } from 'vite';
-import { needmark } from 'needmark';
-
-export default defineConfig({
-  plugins: [needmark()],
-});
-```
-
-The plugin runs during development only and is absent from production builds and `vite preview`. Called without arguments, it loads `needmark.config.ts` from the directory where Vite runs. It works on `localhost`, `127.0.0.1` and `[::1]` without configuration; set `origins` only to review through another hostname, such as a LAN address or a tunnel.
-
-### Next.js and other development servers
-
-Start your application normally, then run this in the same project:
-
-```sh
-pnpm exec needmark dev --target=http://localhost:3000
-```
-
-Open `http://localhost:4190`. The proxy adds the widget without changing application imports or builds. Target and review origin must be different loopback HTTP origins; [proxy setup and limits](docs/getting-started.md#nextjs-and-other-development-servers) explain the details.
+It also writes `needmark.config.ts` and targeted Git ignore rules. `NEEDMARK=off pnpm dev` starts without NeedMark for you; `enabled: false` in `needmark.config.ts` turns it off for everyone; `pnpm exec needmark remove` undoes the connection. Other servers and configs `init` cannot read are set up by hand as described in [Getting started](docs/getting-started.md#connect-the-development-server); [all noninteractive flags](docs/getting-started.md#install-and-initialize) are documented there too.
 
 ## Review, hand off, verify
 

docs/README.md

@@ -13,7 +13,7 @@ Start with the overview in your preferred language, then use the getting-started
 | Implementation and operating limits / 実装と動作上の制約 | [Architecture](architecture.md) | [英語リファレンス](architecture.md) |
 | Benchmark and product evaluation / ベンチマークと評価 | [Japanese only](agentation-comparison.ja.md) | [Agentationとの比較](agentation-comparison.ja.md) |
 | Contributor and agent rules / 開発・AIエージェントの共通ルール | [AGENTS.md](../AGENTS.md) | [AGENTS.md](../AGENTS.md) |
-| Testing and manual checks / テストと手動確認 | [Testing](testing.md) | [Testing（英語）](testing.md) |
+| Test design, running tests, manual checks and framework examples / テスト設計・実行・手動確認・フレームワーク別の例 | [Testing](testing.md) | [Testing（英語）](testing.md) |
 | Releasing to npm / npmへのリリース | [Releasing](releasing.md) | [Releasing（英語）](releasing.md) |
 
 Detailed reference sections / 詳細リファレンス: