{"owner":"algolia","repo":"instantsearch","hasSkills":true,"totalSkillsCount":43,"totalTokensCount":43884,"categories":["command-prompt","anthropic-skill","root-instruction","claude-rule","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".claude/commands/expose-option.md",".claude/commands/preflight.md",".claude/rules/e2e.md",".claude/skills/port-widget/SKILL.md",".claude/skills/port-widget/agents/openai.yaml",".claude/skills/port-widget/references/js-flavor.md",".claude/skills/port-widget/references/react-flavor.md",".claude/skills/port-widget/references/testing.md",".claude/skills/port-widget/references/vue-flavor.md","AGENTS.md","CLAUDE.md","packages/algoliasearch-helper/CLAUDE.md","packages/algoliasearch-helper/README.md","packages/algoliasearch-helper/examples/readme.md","packages/create-instantsearch-app/README.md","packages/create-instantsearch-app/docs/custom-templates.md","packages/create-instantsearch-app/docs/deploy.md","packages/create-instantsearch-app/src/templates/Autocomplete/README.md","packages/create-instantsearch-app/src/templates/InstantSearch.js widget/README.md","packages/create-instantsearch-app/src/templates/InstantSearch.js/README.md","packages/create-instantsearch-app/src/templates/JavaScript Client/README.md","packages/create-instantsearch-app/src/templates/JavaScript Helper/README.md","packages/create-instantsearch-app/src/templates/React InstantSearch Native/README.md","packages/create-instantsearch-app/src/templates/React InstantSearch/README.md","packages/create-instantsearch-app/src/templates/Vue InstantSearch with Vue 3/README.md","packages/create-instantsearch-app/src/templates/Vue InstantSearch/README.md","packages/instantsearch-codemods/README.md","packages/instantsearch-ui-components/CLAUDE.md","packages/instantsearch-ui-components/README.md","packages/instantsearch-ui-components/src/lib/markdown-to-jsx/README.md","packages/instantsearch.css/README.md","packages/instantsearch.js/CLAUDE.md","packages/instantsearch.js/README.md","packages/instantsearch.js/scripts/transforms/README.md","packages/react-instantsearch-core/README.md","packages/react-instantsearch-nextjs/CLAUDE.md","packages/react-instantsearch-nextjs/README.md","packages/react-instantsearch-router-nextjs/CLAUDE.md","packages/react-instantsearch-router-nextjs/README.md","packages/react-instantsearch/CLAUDE.md","packages/react-instantsearch/README.md","packages/vue-instantsearch/CLAUDE.md","packages/vue-instantsearch/README.md"],"skills":{".claude/commands/expose-option.md":"---\ndescription: Thread a new option on an existing connector through all three flavors (JS, React, Vue) + common tests\nargument-hint: [short description of what it does]\n---\n\nYou are exposing a new option through the InstantSearch fan-out. The architecture is **connector (logic) → flavor wrapper → shared UI**, so the option is defined once in the connector and surfaced by each flavor.\n\n**Input:** `$ARGUMENTS`\n\n- First token = the connector (e.g. `connectRefinementList` or just `refinementList`).\n- Second token = the new option name (e.g. `clearOnChange`).\n- Remaining text = a short description of the behavior, if given.\n\nIf the connector or option name is missing or ambiguous, ask before changing files. If the behavior isn't specified, ask what the option should do — do **not** guess at semantics.\n\nThis is a checklist for a cross-flavor option rollout. The connector is the single source of truth; React and Vue only _wrap_ it, so do the connector first, then the wrappers.\n\n## Steps\n\n1. **Scope the contract first.** Read the connector `packages/instantsearch.js/src/connectors//connect.ts` and its JS widget `packages/instantsearch.js/src/widgets//.tsx`. Confirm the option doesn't already exist and settle the exact semantics + the option's type signature. This is the contract every flavor must match.\n\n2. **Connector first** (in `packages/instantsearch.js`):\n - Add the option to the connector's widget-params type with a TSDoc comment.\n - Implement the behavior in the lifecycle (`init`/`render`/`getWidgetSearchParameters`/etc.).\n - Surface it on the **typed render state** if consumers need it (untyped render state is an oxlint error).\n - Thread it through the JS widget. Keep it framework-agnostic — no React/Vue/DOM-framework code in the connector.\n\n For a presentational-only variant, **reuse the existing connector** with a distinct `$$widgetType` — never fork connector logic.\n\n3. **If the option changes shared markup/layout** (not just behavior), update the shared `createComponent` in `packages/instantsearch-ui-components` _before_ wiring the flavors — its output is the contract they consume.\n\n4. **Thread it through the wrappers** (independent of each other once the connector is settled):\n - **React** — the hook `packages/react-instantsearch-core/src/connectors/use.ts` and the component `packages/react-instantsearch/src/widgets/.tsx`, kept in sync and typed.\n - **Vue** — `packages/vue-instantsearch/src/components/.{vue,js}` (and `src/mixins/` if wiring lives there), working for **both Vue 2 and Vue 3**.\n\n5. **Tests.** Cross-flavor behavior → add/extend `tests/common/connectors//` (or `.../widgets//`) and register it in each flavor's `common-*.test.*` (see `tests/common/README.md`); flavor-specific assertions stay in each package's co-located `__tests__/`. If browser-level behavior is affected, add an e2e spec (see `.claude/rules/e2e.md`).\n\n6. **Verify.** Confirm all three flavors expose the same option with consistent naming/types, then:\n ```bash\n yarn jest packages/instantsearch.js/src/connectors/\n yarn jest \n yarn type-check\n yarn lint:changed\n ```\n (Or run `/preflight`.)\n\n## Notes\n\n- Why this order: the connector is the contract; React and Vue only _wrap_ it, so they're independent of each other and safe to do once the connector is settled.\n- Don't hand-edit changelogs (Ship.js generates them). Commit message: `feat(): add option`.\n",".claude/commands/preflight.md":"---\ndescription: Run the pre-push checklist — lint, types, relevant tests, and a Conventional-Commit sanity check\nallowed-tools: Bash(yarn lint:changed), Bash(yarn lint:fix), Bash(yarn type-check), Bash(yarn type-check:*), Bash(yarn jest:*), Bash(git status:*), Bash(git diff:*), Bash(git log:*)\n---\n\nRun the InstantSearch pre-push checks against the **current changes** and report a concise pass/fail summary. Don't fix anything silently — surface failures and propose fixes.\n\n## Steps\n\n1. **Scope the change.** `git status` + `git diff --name-only` (and vs. the base branch if on a feature branch) to see which packages/files are touched.\n\n2. **Lint the changed files:** `yarn lint:changed`. If it fails, show the violations; offer `yarn lint:fix` for auto-fixable ones (note that oxlint bans `for-in`/`for-of`/`async` and implicit `any` in library code — those need manual fixes).\n\n3. **Type-check:** `yarn type-check`. If any touched code interacts with the legacy algoliasearch versions, also run `yarn type-check:v3` / `yarn type-check:v4`.\n\n4. **Run the relevant tests** — not the whole suite. Map changed files to their `yarn jest ` (e.g. a connector → `yarn jest packages/instantsearch.js/src/connectors/`; a React widget → its `__tests__` path). If a connector's cross-flavor behavior changed, include the matching `tests/common/` path.\n\n5. **Conventional-Commit sanity check.** Look at staged changes / recent commits and confirm the message fits `type(scope): description` (scope = widget/connector or topic like `deps`/`ci`). Flag if it doesn't; suggest a corrected message. Reference issues with `fix #1234` in the body when applicable.\n\n## Output\n\nReport a short checklist:\n\n- ✅/❌ lint:changed\n- ✅/❌ type-check (+ v3/v4 if run)\n- ✅/❌ tests (list the paths run)\n- ✅/❌ commit message\n\nFor any ❌, show the failing output and the smallest fix. Don't run the full `yarn test` or `yarn build` unless asked — this is the fast pre-push loop.\n\nRun the checks directly. If a check fails, fix it in the package that owns the failing file before re-running.\n",".claude/rules/e2e.md":"---\npaths:\n - 'tests/e2e/**'\n - '.github/workflows/e2e.yml'\n - '.github/workflows/ci.yml'\n - 'website/serve.json'\n - 'examples/*/e-commerce*/**'\n - 'packages/react-instantsearch-nextjs/playwright.config.ts'\n - 'packages/react-instantsearch-nextjs/__tests__/e2e/**'\n - 'packages/react-instantsearch-router-nextjs/playwright.config.ts'\n - 'packages/react-instantsearch-router-nextjs/__tests__/e2e/**'\n---\n\n# E2E Testing Guide\n\n## Test Locations and Frameworks\n\n| Location | Framework | Purpose |\n| --- | --- | --- |\n| `tests/e2e/playwright/` | Playwright | Main e2e suite for all InstantSearch flavors |\n| `tests/e2e/` (wdio files) | WebdriverIO | IE11 tests only (via Sauce Labs) |\n| `packages/react-instantsearch-nextjs/__tests__/e2e/` | Playwright | App Router Next.js e2e tests |\n| `packages/react-instantsearch-router-nextjs/__tests__/e2e/` | Playwright | Pages Router Next.js e2e tests |\n\n`.github/workflows/e2e.yml` runs on a weekday schedule and is called from `ci.yml` on pushes to master, never on pull requests. Run the suites locally before you push.\n\n## Running Tests Locally\n\n### Main E2E Suite (Playwright)\n\n**Prerequisites:** Examples must be built first:\n\n```bash\nyarn website:examples\n```\n\n```bash\n# Run all Playwright tests (all flavors, chromium + firefox)\nyarn test:e2e\n\n# Run tests for a specific flavor\nE2E_FLAVOR=react yarn test:e2e\n\n# Run tests for a specific browser (faster local dev)\nE2E_BROWSER=chromium yarn test:e2e\n\n# Combine both for fastest local iteration\nE2E_FLAVOR=react E2E_BROWSER=chromium yarn test:e2e\n\n# Run tests with UI mode for debugging\nyarn workspace @instantsearch/e2e-tests test:playwright --ui\n```\n\n### Next.js Package Tests\n\n```bash\n# App Router (react-instantsearch-nextjs)\nyarn workspace react-instantsearch-nextjs test:e2e\n\n# Pages Router (react-instantsearch-router-nextjs)\nyarn workspace react-instantsearch-router-nextjs test:e2e\n\n# Run with list reporter (outputs to terminal instead of opening browser)\nyarn workspace react-instantsearch-nextjs test:e2e --reporter=list\nyarn workspace react-instantsearch-router-nextjs test:e2e --reporter=list\n```\n\n### IE11 Tests (Requires Sauce Labs credentials)\n\n```bash\n# Set environment variables first\nexport SAUCE_USERNAME=your_username\nexport SAUCE_ACCESS_KEY=your_access_key\n\nyarn test:e2e:ie11\n```\n\n## Writing Playwright Tests\n\n### Test Structure\n\n```typescript\nimport { test, expect } from '../fixtures';\n\ntest.describe('feature name', () => {\n test('does something specific', async ({ page, helpers }) => {\n // Use '.' to navigate to baseURL, NOT '/' (which goes to root)\n await page.goto('.');\n\n // Use helpers for common InstantSearch interactions\n await helpers.clickRefinementListItem('Apple');\n await helpers.setSearchBoxValue('macbook');\n\n // Use Playwright's built-in assertions\n await expect(page.locator('.ais-Hits-item')).toHaveCount(16);\n });\n});\n```\n\n### Available Helper Methods\n\nThe `helpers` fixture provides these methods. Full signatures in `tests/e2e/playwright/fixtures.ts`.\n\n- **RefinementList:** `clickRefinementListItem(label)`, `getSelectedRefinementListItem()`\n- **SearchBox:** `setSearchBoxValue(value)`, `getSearchBoxValue()`\n- **Hits:** `getHitsTitles()`\n- **HierarchicalMenu:** `clickHierarchicalMenuItem(label)`, `getSelectedHierarchicalMenuItems()`\n- **RangeSlider:** `dragRangeSliderLowerBoundTo(value)`, `dragRangeSliderUpperBoundTo(value)`, `getRangeSliderLowerBoundValue()`, `getRangeSliderUpperBoundValue()`\n- **Pagination:** `clickPage(number)`, `clickNextPage()`, `clickPreviousPage()`, `getCurrentPage()`\n- **ToggleRefinement:** `clickToggleRefinement()`, `getToggleRefinementStatus()`\n- **RatingMenu:** `clickRatingMenuItem(label)`, `getSelectedRatingMenuItem()`. `label` is the link's `aria-label`, such as `4 & up`.\n- **SortBy:** `setSortByValue(label)`, `getSortByValue()`\n- **HitsPerPage:** `setHitsPerPage(label)`, `getHitsPerPage()`\n- **ClearRefinements:** `clickClearRefinements()`\n- **Any selector:** `waitForElement(selector)`, `getTextFromSelector(selector)`\n\n### Best Practices\n\n1. **Use helpers for InstantSearch interactions** - They handle waiting for URL changes automatically\n2. **Prefer Playwright's auto-waiting assertions** - Use `await expect(locator).toHaveText('...')` instead of manual waits\n3. **Avoid `page.waitForTimeout()`** - Use proper waits like `waitForURL()` or `expect.poll()`\n4. **Use locator chaining** - `page.locator('.parent').locator('.child')`\n5. **Use `'.'` for baseURL navigation** - `page.goto('.')` navigates to the baseURL path; `page.goto('/')` goes to the root domain (common mistake)\n6. **Prefer relative paths** - For routes like `search/category/?query=test`, use paths without leading `/`\n7. **Avoid hardcoded test data** - The Algolia index data can change. Instead of checking exact product names, verify behavior (e.g., results changed, count > 0, URL updated)\n8. **Wait for results after navigation** - After pagination or filter changes, wait for new results to load before asserting\n9. **Don't use `scrollIntoViewIfNeeded()`** - Playwright auto-scrolls elements into view before clicking\n10. **Don't add redundant waits after URL waits** - If you wait for URL change, the UI has already updated; no need to also wait for element visibility\n\n## Flavor System\n\nThe main e2e suite tests multiple InstantSearch flavors:\n\n- `js` - instantsearch.js with vanilla JS\n- `js-umd` - instantsearch.js UMD build\n- `react` - React InstantSearch\n- `vue` - Vue InstantSearch\n\nTests run against example apps in `website/examples/{flavor}/e-commerce/`.\n\nTo run a single flavor:\n\n```bash\nE2E_FLAVOR=react yarn test:e2e\n```\n\n## IE11 Considerations\n\nIE11 tests are kept in WebdriverIO because Playwright doesn't support IE11. These tests:\n\n- Only run `js` and `js-umd` flavors\n- Require Sauce Labs for remote IE11 browser\n- Use the same test specs in `tests/e2e/specs/` and helpers in `tests/e2e/helpers/`\n\n## Debugging\n\n### Playwright\n\n```bash\n# Run with headed browser\nyarn workspace @instantsearch/e2e-tests test:playwright --headed\n\n# Run with UI mode (interactive debugging)\nyarn workspace @instantsearch/e2e-tests test:playwright --ui\n\n# Run specific test file\nyarn workspace @instantsearch/e2e-tests test:playwright specs/brand-and-query.spec.ts\n\n# Debug mode with inspector\nPWDEBUG=1 yarn workspace @instantsearch/e2e-tests test:playwright\n```\n\n### View Test Reports\n\nAfter running tests, open the HTML report:\n\n```bash\nnpx playwright show-report tests/e2e/playwright/playwright-report\n```\n\n## Troubleshooting\n\n### Tests timeout waiting for elements\n\n1. **Check if examples are built**: Run `yarn website:examples` before running tests\n2. **Check if the server starts**: The webServer uses port 3456 (not 5000, which conflicts with macOS AirPlay)\n3. **Check navigation**: Use `page.goto('.')` not `page.goto('/')` to navigate to baseURL\n\n### Port conflicts on macOS\n\nOn macOS, port 5000 is used by AirPlay Receiver (ControlCenter). The tests use port 3456 instead. If you need to change the port, update:\n\n- `tests/e2e/playwright/playwright.config.ts` (both `baseURL` and `webServer.command/url`)\n\n### SPA routing not working\n\nThe e-commerce examples use History API routing (e.g., `/search/Appliances/`). The `website/serve.json` file configures rewrites for these routes. If you add new SPA routes, update this file:\n\n```json\n{\n \"rewrites\": [\n {\n \"source\": \"/examples/js/e-commerce/search/**\",\n \"destination\": \"/examples/js/e-commerce/index.html\"\n }\n ]\n}\n```\n\n### Tests are flaky with multiple workers\n\nThe static server can handle 2 parallel workers. All configs use 2 workers for both CI and local runs.\n\nThe main suite retries once locally and twice in CI. The Next.js suites retry twice in CI and not at all locally.\n\n### Multiple elements matched\n\nIf you see \"strict mode violation\" errors about multiple elements:\n\n- SearchBox selectors are scoped to the header to avoid matching RefinementList search inputs\n- Use more specific selectors when targeting widgets that may appear multiple times\n\n### Different HTML structures across flavors\n\nThe JS and React examples have different HTML structures:\n\n- **JS examples**: Use `id=\"header\"` and `data-widget=\"searchbox\"` attributes\n- **React examples**: Use `className=\"header\"` (class instead of id) and render SearchBox directly inside header\n\nThe fixtures account for this with combined selectors like:\n\n```typescript\n'#header .ais-SearchBox [type=search], .header > .ais-SearchBox [type=search], [data-widget=\"searchbox\"] .ais-SearchBox [type=search]';\n```\n\nIf you add new selectors, ensure they work across all flavors.\n\n## Migration Notes: WebDriverIO to Playwright\n\nWhen migrating tests from WebDriverIO to Playwright, be aware of these differences:\n\n### URL Waiting\n\n- **WebDriverIO**: Used custom `waitForUrl()` that polls `browser.getUrl()` until match\n- **Playwright**: Use `await expect(page).toHaveURL(url)` which has built-in retrying\n\n### Element Selection\n\n- **WebDriverIO**: `$('.ais-Hits-item')` returns first match, clicking works on container elements\n- **Playwright**: `page.locator('.ais-Hits-item').first()` - clicking on container may not hit child link elements. Use `.locator('a')` to target links explicitly:\n\n ```typescript\n // WebDriverIO\n const link = await $('.ais-Hits-item');\n await link.click();\n\n // Playwright - click the link inside the hit\n const link = page.locator('.ais-Hits-item a').first();\n await link.click();\n ```\n\n### Browser Back Navigation\n\n- **WebDriverIO**: `browser.back()` worked reliably for SPA navigation\n- **Playwright**: `page.goBack()` works but may require `slowMo` in headless mode for Next.js App Router dynamic routes\n\n### Headless Mode Timing Issues\n\nPlaywright's headless mode runs faster than headed mode, which can cause timing issues with SPA navigation and state updates. For Next.js App Router tests involving browser back/forward navigation with dynamic routes, add `slowMo` at the test file level (not globally, to avoid slowing down all tests):\n\n```typescript\nimport { test, expect } from '@playwright/test';\n\n// slowMo is required for browser back/forward navigation tests in headless mode\ntest.use({ launchOptions: { slowMo: 500 } });\n\ntest.describe('browser back/forward buttons', () => {\n // tests that use page.goBack() or page.goForward()\n});\n```\n\nThis gives the browser enough time to process JavaScript events like popstate handlers used by InstantSearch routing, while keeping other tests fast.\n",".claude/skills/port-widget/SKILL.md":"---\nname: port-widget\ndescription: Port or introduce an InstantSearch widget or connector-driven feature across this monorepo's JavaScript, React, and Vue flavors. Use when the task is to add a missing wrapper around an existing connector, bring a widget from one flavor to another, or implement a new shared widget end-to-end in `instantsearch.js`, `react-instantsearch`, and `vue-instantsearch`. Triggers include requests like \"port X to vue\", \"add Y to react-instantsearch\", \"make Z available in all flavors\", or \"implement the missing InstantSearch wrapper for this connector\".\n---\n\n# Port InstantSearch Widgets Across Flavors\n\n## Start with the repo audit\n\n- Run `python3 scripts/audit_widget_coverage.py ` from this skill folder before editing.\n- Use `--repo /path/to/instantsearch` if your current working directory is not inside the InstantSearch repo.\n- Treat placeholder Vue failures in `packages/vue-instantsearch/src/__tests__/common-widgets.test.js` or `common-connectors.test.js` as evidence that the connector exists but the Vue wrapper still needs work.\n\n## Layer map\n\n- Connector: `packages/instantsearch.js/src/connectors//connect.ts`\n- JS widget: `packages/instantsearch.js/src/widgets//.tsx`\n- React hook: `packages/react-instantsearch-core/src/connectors/use.ts`\n- React widget: `packages/react-instantsearch/src/widgets/.tsx`\n- Optional React UI: `packages/react-instantsearch/src/ui/.tsx`\n- Vue wrapper: `packages/vue-instantsearch/src/components/.vue` or `.js`\n- Shared widget tests: `tests/common/widgets//`\n- Shared connector tests: `tests/common/connectors//`\n\n## Variant widgets\n\nSome widgets reuse another widget's connector with different defaults or UI. For example, `menuSelect` uses `connectMenu`/`useMenu` (not a dedicated `connectMenuSelect`). The audit will show `no` for connector and hook rows — this is expected. The `$$widgetType` still differs (`ais.menuSelect` vs `ais.menu`). When porting a variant widget, skip connector/hook creation and reuse the existing hook directly in the widget file.\n\nKnown variants: `menuSelect` → `connectMenu`/`useMenu`.\n\n## Workflow\n\n1. Decide the scope.\n - Existing connector, missing wrapper: keep the connector API unchanged and port only the wrapper plus wrapper tests.\n - Variant widget (shared connector, different UI): skip connector/hook creation; reuse the existing hook and set a distinct `$$widgetType`.\n - Missing connector or changed render state: start in `instantsearch.js`, then update every flavor and both common test suites.\n - Vue port for a newer recommendation, chat, or filter-suggestions feature: inspect `Hits.js`, `Highlighter.js`, `DynamicWidgets.js`, and `util/vue-compat.js` before designing the wrapper.\n2. Match a real precedent.\n - Pick one close widget in the target flavor and one close widget in another flavor.\n - Reuse the same prop names, slot or component escape hatches, `$$widgetType`, and test style.\n3. Build from the bottom up.\n - Connector exports belong in `packages/instantsearch.js/src/connectors/index.ts`.\n - JS widget exports belong in `packages/instantsearch.js/src/widgets/index.ts`.\n - React hook exports belong in `packages/react-instantsearch-core/src/index.ts`.\n - React widget exports belong in `packages/react-instantsearch/src/widgets/index.ts`; `packages/react-instantsearch/src/index.ts` already re-exports widgets.\n - Vue exports belong in `packages/vue-instantsearch/src/widgets.js`; `src/instantsearch.js` and the plugin re-export and register from there automatically.\n4. Choose the right sharing model.\n - JS and React: prefer `instantsearch-ui-components` when the markup can be shared.\n - React: create `src/ui/.tsx` whenever the widget has no shared factory in `instantsearch-ui-components`. This includes simple widgets like `MenuSelect` (a plain ``).\n- Keep the widget file focused on mapping hook state and event handlers into the UI component.\n\n### Variant widgets (shared connector)\n\nSome widgets reuse another widget's hook instead of having a dedicated one. For example, `MenuSelect` uses `useMenu` (not `useMenuSelect`). In this case:\n\n- Import the existing hook directly in the widget file.\n- Pick only the relevant connector params (e.g., exclude `showMore`/`showMoreLimit` for `MenuSelect`).\n- Set a distinct `$$widgetType` (e.g., `'ais.menuSelect'`).\n\n## Registration checklist\n\n- Export the hook from `packages/react-instantsearch-core/src/index.ts` (skip for variant widgets that reuse an existing hook).\n- Export the widget from `packages/react-instantsearch/src/widgets/index.ts`.\n- If the widget is public, `packages/react-instantsearch/src/index.ts` already re-exports it through `./widgets`.\n- Add the widget to the switch in `packages/react-instantsearch/src/widgets/__tests__/__utils__/all-widgets.tsx` with required minimum props (e.g., `attribute=\"brand\"`).\n- In `packages/react-instantsearch/src/__tests__/common-widgets.test.tsx`:\n - Replace the `throw new Error('X is not supported in React InstantSearch')` with real setup code.\n - Remove the `skippedTests` entry for the widget in `testOptions`.\n",".claude/skills/port-widget/references/testing.md":"# Testing and Examples\n\n## Start with the common suites\n\n### Wrapper or public widget change\n\n- Update `tests/common/widgets//`.\n- Register or unskip the suite in each flavor's `common-widgets.test.*`:\n - `packages/instantsearch.js/src/__tests__/common-widgets.test.tsx`\n - `packages/react-instantsearch/src/__tests__/common-widgets.test.tsx`\n - `packages/vue-instantsearch/src/__tests__/common-widgets.test.js`\n- For previously unsupported widgets: replace the `throw new Error('X is not supported in ...')` placeholder with real setup code, and remove the `skippedTests` entry in `testOptions`.\n\n### Connector or hook API change\n\n- Update `tests/common/connectors//`.\n- Register or unskip the suite in:\n - `packages/instantsearch.js/src/__tests__/common-connectors.test.tsx`\n - `packages/react-instantsearch/src/__tests__/common-connectors.test.tsx`\n - `packages/vue-instantsearch/src/__tests__/common-connectors.test.js`\n\n## Flavor-specific tests\n\n- JavaScript: `packages/instantsearch.js/src/widgets//__tests__/`\n- React: `packages/react-instantsearch/src/widgets/__tests__/`\n- Vue: colocated component or package tests under `packages/vue-instantsearch/src/__tests__/`\n\nAdd flavor-specific tests only for behavior that the shared suites do not cover, such as:\n\n- slot rendering differences in Vue\n- React-only UI plumbing\n- template or CSS-class edge cases in `instantsearch.js`\n- registry coverage such as React's `all-widgets` helpers\n\n## Shared cross-widget suites\n\n- Search `tests/common/shared/` and `tests/common/shared-composition/` when the port affects routing, searchable behavior, or cross-widget composition.\n- Only touch those suites when the new widget changes shared behavior rather than a single widget contract.\n\n## Examples\n\n- Search existing examples before editing; not every user-facing widget belongs in the e-commerce demos.\n- E-commerce apps live in:\n - `examples/js/e-commerce/src/`\n - `examples/react/e-commerce/`\n - `examples/vue/e-commerce/src/`\n- Recommendation, chat, and query-suggestion features already appear in getting-started or query-suggestions examples for JS and React.\n\n## Vue-specific test timing\n\n### State delivery is async for some connectors\n\nMost connectors (e.g. `connectRefinementList`) deliver state synchronously during `mountApp` because the mock search client responds immediately. Newer connectors like `connectChat` deliver state asynchronously. The Vue test setup must account for this:\n\n```javascript\nmountApp({ render: ... }, container);\nawait nextTick(); // Vue tick\nawait new Promise((resolve) => setTimeout(resolve, 0)); // macrotask for async state\nawait nextTick(); // Vue tick to re-render\n```\n\n### Provide a custom `act` for Vue\n\nVue batches DOM updates asynchronously, unlike React which re-renders synchronously within event handlers. Tests that `await act(async () => { await wait(0); })` work because `act` wraps the wait. Provide a custom `act` in `testOptions` that flushes Vue's update queue:\n\n```javascript\ncreateXxxWidgetTests: {\n act: async (cb) => {\n await cb();\n await nextTick();\n },\n},\n```\n\nTests that click then immediately assert DOM changes (without `act`) will still fail in Vue. These are known limitations of the shared test suite's React-centric timing assumptions. Document them in the `testOptions` but avoid skipping the entire test suite.\n\n### Flavored test params\n\nFor `flavored` test suites (like Chat), `runTestSuites` extracts the flavor-specific params via `widgetParams[flavor]`. The Vue setup function receives only the Vue portion. Ensure the Vue params include all required connector params (e.g. `agentId`, `chat`) — empty `{}` will cause connector errors.\n\nWhen Vue params need component functions (tools with `layoutComponent`, custom `headerComponent`), use `import { h as vueH } from 'vue'` in the `.tsx` test file and return VNodes: `() => vueH('div', { class: 'foo' }, 'text')`.\n\n### skippedTests granularity\n\n`skippableDescribe` only skips entire describe blocks by name. Individual test names in `skippedTests` have no effect unless the test file uses `skippableTest`. The shared chat/options/templates/translations test files use plain `test()`, so individual test skipping is not available for Chat widget tests.\n\n## Useful commands\n\n```bash\n# Common widget/connector tests\nnpx jest packages/instantsearch.js/src/__tests__/common-widgets.test.tsx --no-coverage\nnpx jest packages/instantsearch.js/src/__tests__/common-connectors.test.tsx --no-coverage\nnpx jest packages/react-instantsearch/src/__tests__/common-widgets.test.tsx --no-coverage\nnpx jest packages/react-instantsearch/src/__tests__/common-connectors.test.tsx --no-coverage\nnpx jest packages/vue-instantsearch/src/__tests__/common-widgets.test.js --no-coverage\n\n# Run only tests matching a specific widget name\nnpx jest packages/react-instantsearch/src/__tests__/common-widgets.test.tsx --testNamePattern=\"MenuSelect\" --no-coverage\n\n# Flavor-specific tests\nnpx jest packages/react-instantsearch/src/widgets/__tests__ --no-coverage\nnpx jest packages/instantsearch.js/src/widgets/ --no-coverage\n\n# Update snapshots after adding new exports\nnpx jest packages/react-instantsearch/src/widgets/__tests__ --no-coverage -u\n\n# E2E\nyarn website:examples\nE2E_FLAVOR=react E2E_BROWSER=chromium yarn test:e2e\n```\n",".claude/skills/port-widget/references/vue-flavor.md":"# Vue Flavor (`vue-instantsearch`)\n\n## Current patterns in this repo\n\n- Slot-heavy SFCs: `RefinementList.vue`, `Menu.vue`, `Pagination.vue`\n- Render-function wrappers around shared UI components: `Hits.js`, `Highlighter.js`\n- Framework glue helpers: `mixins/widget.js`, `mixins/suit.js`, `util/vue-compat.js`\n\n## Choose the wrapper shape deliberately\n\n### Use a `.vue` SFC when\n\n- the widget exposes multiple named slots\n- the DOM structure is easiest to express in template syntax\n- the closest existing widget is already an SFC\n\n### Use a `.js` render function when\n\n- the widget reuses `instantsearch-ui-components`\n- the wrapper mostly adapts connector state into a shared UI factory\n- the widget needs `renderCompat(...)` or lower-level vnode control\n\n## Implementation rules\n\n- Import connectors from `instantsearch.js/es/connectors/index`.\n- Use `createWidgetMixin({ connector: ... }, { $$widgetType: 'ais.' })`.\n- Use `createSuitMixin({ name: '' })` for BEM classes. When the widget delegates all rendering to a shared `createXxxComponent` factory, the suit mixin's `suit()` method goes unused but the `classNames` prop it provides is still convenient. Pass `this.classNames` directly to the shared component's `classNames` prop (semantic keys like `{ root, container }`, not BEM keys).\n- Expose connector params through a computed `widgetParams()` object.\n- When reusing shared UI factories, wrap the render function with `renderCompat(...)` and map `this.classNames` into the `classNames` prop expected by the shared component.\n- Prefer `getScopedSlot` or `getDefaultSlot` helpers over direct slot access when matching render-function components.\n- In render-function callbacks that reference connector state (e.g. `onSubmit`, `onInput`), read from `this.state.xxx` instead of destructured locals. Vue batches re-renders, so destructured values become stale between synchronous user interactions (type then click).\n\n## Registration checklist\n\n- Export the component from `packages/vue-instantsearch/src/widgets.js`.\n- Do not manually edit `src/plugin.js` or `src/instantsearch.js` for normal widget additions; they already derive registration and exports from `widgets.js`.\n- Search `packages/vue-instantsearch/src/__tests__/common-widgets.test.js` and `common-connectors.test.js` for placeholder \"not supported\" branches before deciding the widget is genuinely absent.\n\n## Missing-feature caution\n\n- Recommendation widgets, chat, and filter suggestions already have connector-level test placeholders in Vue, but several still throw explicit \"not supported\" errors at the widget layer.\n- If you port one of those widgets, remove the placeholder failure and replace it with real setup code plus the component implementation.\n","AGENTS.md":"CLAUDE.md","CLAUDE.md":"# InstantSearch monorepo\n\nSearch UI libraries for Algolia across three flavors (vanilla JS, React, Vue), sharing one connector + UI-component core. Yarn 4 workspaces + Lerna (independent versioning).\n\n## Repo map\n\n| Package | What it is |\n| --- | --- |\n| `packages/instantsearch.js` | **Core.** Vanilla JS library. **All connectors live here** (`src/connectors/`) and are shared by every flavor. |\n| `packages/react-instantsearch-core` | Headless React: hooks (`useSearchBox`, …) that wrap connectors. Framework-agnostic (web/RN). |\n| `packages/react-instantsearch` | React DOM widgets = hooks + UI from `instantsearch-ui-components`. |\n| `packages/vue-instantsearch` | Vue 2/3 components wrapping connectors. |\n| `packages/instantsearch-ui-components` | **Shared UI layer.** Framework-agnostic widget markup + `ais-*` classes via factory components (`createComponent({ createElement, Fragment })`); reused by React directly, Vue via `renderCompat`, JS via the Preact renderer. Newer widgets get their layout here; older ones still define it in `instantsearch.js/src/components/`. |\n| `packages/algoliasearch-helper` | Low-level search-parameter/state manager underneath connectors. Mature, separately-versioned; **rarely the place for a change** — fix the connector instead. See its `CLAUDE.md`. |\n| `packages/instantsearch.css` | Default themes. |\n| `packages/react-instantsearch-nextjs` / `-router-nextjs` | Next.js App Router / Pages Router integrations. |\n| `packages/create-instantsearch-app`, `instantsearch-cli`, `instantsearch-codemods` | Scaffolding / CLI / migration tooling. |\n\nArchitecture in one line: **connector (logic, in instantsearch.js) → flavor wrapper (JS widget / React hook+component / Vue component) → shared UI components**. Change behavior in the connector; change markup in the UI layer.\n\n## Where work goes (per layer)\n\nBecause behavior lives in the connector and the flavors only wrap it, most changes have a natural home — and the per-package `CLAUDE.md` files carry each layer's conventions:\n\n| Work in… | Package |\n| --- | --- |\n| Connectors, JS widgets, runtime (`src/lib`), legacy Preact components (`src/components`), types | `packages/instantsearch.js` |\n| Shared framework-agnostic markup / `ais-*` classes | `packages/instantsearch-ui-components` |\n| React widgets/hooks + Next.js integrations | `react-instantsearch` / `react-instantsearch-core` / `*-nextjs` |\n| Vue components (Vue 2 **and** 3) | `vue-instantsearch` |\n\nFor a **cross-flavor change**, settle the contract in the connector first, then update the React and Vue wrappers, then the common tests. If the change is to **shared markup/layout** (not behavior), it lives in `instantsearch-ui-components` and the flavors consume the result — a class/structure change there ripples to all flavors and `instantsearch.css` at once.\n\n**Adding or surfacing a connector option is always cross-flavor work** — settle the contract in the connector first, then thread it through React **and** Vue, then add/extend common tests. Don't wire one flavor and stop. The **`/expose-option