{"owner":"petyosi","repo":"react-virtuoso","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## NPM Registry Queries\n\nThis project uses `devEngines.packageManager` with `\"onFail\": \"error\"` in `package.json`, which causes `pnpm info` and `pnpm view` to fail because they delegate to npm, and npm 11 rejects the request. To check package versions, run npm from outside the project directory:\n\n```bash\n(cd /tmp && npm info <package> version)\n```\n\n## Build Commands\n\nThis is a pnpm workspaces monorepo. Run commands from the root or within specific workspace packages.\n\n### Root-level commands\n\nRun from repository root for all packages:\n\n- Build all: `pnpm build`\n- Lint all (includes type checking): `pnpm lint`\n- Format all: `pnpm format` (oxfmt)\n- Format check: `pnpm format:check`\n- Test all: `pnpm test`\n- E2E tests all: `pnpm e2e`\n- Markdown lint: `pnpm lint:md` / fix: `pnpm lint:md:fix`\n- Full CI: `pnpm ci` (setup, build, lint, lint:md, test, e2e)\n- Release: `pnpm release` (build + publish with changesets)\n- Add changeset: `pnpm changeset-add`\n- Dev docs site: `pnpm dev:docs`\n\n### react-virtuoso package (packages/react-virtuoso/)\n\n- Build: `pnpm run build` (uses vite)\n- Test: `pnpm run test` (vitest)\n- Test watch: `pnpm run test:watch`\n- Run single test: `pnpm vitest <test-file-path>` or `pnpm vitest -t \"<test-name>\"`\n- E2E tests: `pnpm run e2e` (playwright)\n- Lint (includes type checking): `pnpm run lint`\n- Format: `pnpm run format` (oxfmt)\n- Format check: `pnpm run format:check`\n- Dev/preview examples: `pnpm run ladle` (launches Ladle server for browsing examples/ folder)\n\n### virtuoso.dev docs app (apps/virtuoso.dev/)\n\n- Dev server: `pnpm run dev`\n- Build: `pnpm run build`\n- Format: `pnpm run format` (oxfmt + Prettier for .astro files)\n\nAfter docs changes: run `pnpm lint` from the app directory or root.\n\n**IMPORTANT - Documentation Locations:**\n\n**DO NOT EDIT** the following auto-generated directories:\n\n- `apps/virtuoso.dev/src/content/docs/data-table/`\n- `apps/virtuoso.dev/src/content/docs/react-virtuoso/`\n- `apps/virtuoso.dev/src/content/docs/masonry/`\n- `apps/virtuoso.dev/src/content/docs/gurx/`\n- `apps/virtuoso.dev/src/content/docs/message-list/`\n\nThese are auto-synced from source files + TypeDoc API via the `docsSync` integration. Any edits will be overwritten.\n\n**To edit package documentation**, modify the source files in each package:\n\n- **data-table**: `packages/data-table/docs/*.md`\n- **react-virtuoso**: `packages/react-virtuoso/README.md` or `packages/react-virtuoso/docs/*.md`\n- **masonry**: `packages/masonry/README.md` or `packages/masonry/docs/*.md`\n- **gurx**: `packages/gurx/README.md` or `packages/gurx/docs/*.md`\n- **message-list**: `packages/message-list/README.md` or `packages/message-list/docs/*.md`\n\n## Plugin Distribution\n\nThis repo ships `virtuoso-skills` as a Claude Code plugin from `packages/virtuoso-skills/`, a Codex plugin from `plugins/virtuoso-skills/`, and a root `skills/` mirror for `npx skills`.\n\nEdit source skill content in `packages/virtuoso-skills/skills/<name>/SKILL.md`. Do not edit `packages/virtuoso-skills/skills/*/references/`, root `skills/`, or `plugins/virtuoso-skills/skills/` directly; regenerate them with:\n\n```bash\npnpm build:skills\n```\n\nAfter merge, public Codex plugin install uses:\n\n```bash\ncodex plugin marketplace add petyosi/react-virtuoso --ref main --sparse .agents/plugins --sparse plugins/virtuoso-skills\ncodex plugin add virtuoso-skills@virtuoso\n```\n\nDo not commit `.agents/skills/` for Codex/OpenCode/Cursor unless the cross-agent install plan changes. `npx skills` owns that target path.\n\n## Monorepo Structure\n\n```text\npackages/\n  react-virtuoso/    - Main virtualization library\n  gurx/             - urx state management (fork/variant)\n  masonry/          - Masonry layout component\n  message-list/     - Chat/message list component\n  tooling/          - Shared build tooling\n\napps/\n  virtuoso.dev/     - Starlight/Astro documentation site\n\nexamples/            - Ladle stories for testing/development\n```\n\n## Architecture\n\n### State Management: urx System\n\nThe codebase uses **urx**, a custom reactive state management system built on streams/observables. Core concepts:\n\n- **Systems**: Stateful data-processing machines composed of streams\n- **Streams**: Can be stateless (signals) or stateful (depots that persist values)\n- **Depots**: Implicit state maintained in stateful streams, transformers (combineLatest), or operators (withLatestFrom, scan)\n- **Input/Output**: Systems receive input via input streams, process via transformers/operators, emit via output streams\n\nKey urx files: `src/urx/` directory contains:\n\n- `system.ts` - System creation and composition\n- `streams.ts` - Stream primitives\n- `pipe.ts` - Stream operators and transformers\n- `actions.ts` - Publishing/emitting\n- `transformers.ts` - Stream transformation utilities\n\n### Component Architecture\n\nThe virtualization logic is split into modular systems in `src/`:\n\n**Core Systems:**\n\n- `listSystem.ts` - Composes all feature systems into the main list system\n- `sizeSystem.ts` - Tracks and manages item sizes (critical for variable-height items)\n- `listStateSystem.ts` - Manages visible item ranges and scrolling state\n- `domIOSystem.ts` - DOM measurements and interactions\n\n**Feature Systems:**\n\n- `groupedListSystem.ts` - Grouped lists with sticky headers\n- `scrollToIndexSystem.ts` - Programmatic scroll positioning\n- `followOutputSystem.ts` - Auto-scroll for chat/feed UIs\n- `initialTopMostItemIndexSystem.ts` - Initial scroll position\n- `scrollSeekSystem.ts` - Placeholder rendering during fast scrolling\n- `windowScrollerSystem.ts` - Window-scrolling mode\n- And many more in `src/*System.ts` files\n\n**React Integration:**\n\n- `react-urx/` - Bridges urx systems to React components\n- `Virtuoso.tsx` - Main list component\n- `VirtuosoGrid.tsx` - Grid layout component\n- `TableVirtuoso.tsx` - Table virtualization component\n- Component interfaces in `component-interfaces/`\n\n### Size Calculation\n\nVariable-sized items work automatically via `sizeSystem.ts`:\n\n- Uses ResizeObserver for measurements\n- Maintains size ranges and estimates\n- No manual height specification needed\n- `correctItemSize()` utility in `utils/` handles size corrections\n\n### E2E Testing\n\nE2E tests in `packages/react-virtuoso/e2e/`:\n\n- Test files: `*.test.ts` (Playwright tests)\n- Example pages: `examples/*.tsx` (rendered in browser for tests)\n- Use Ladle (`pnpm run ladle`) to preview examples during development\n\n## Code Style\n\n- Never use `data-testid` attributes for CSS styling selectors. `data-testid` is reserved for testing only. Use `data-table-element-role` or other semantic data attributes for styling hooks.\n- TypeScript with strong typing; avoid `any`\n- oxfmt: 140 char width, single quotes, no semicolons\n- Naming: camelCase for variables/functions, PascalCase for components\n- Imports: React first, external libs, then internal modules\n- Functional components with hooks preferred\n- Use urx system patterns for state management\n- Error handling: prefer early returns\n\n## Markdown Style Guide\n\nWhen writing or editing markdown documentation:\n\n### Formatting Rules\n\n- Headings: ATX-style (`# Heading` not `Heading\\n=======`)\n- Code blocks: Always use fenced blocks with language specifiers\n\n```typescript\nconst foo = 'bar'\n```\n\n- Lists: Use `-` for unordered lists, indent nested items by 2 spaces\n- Emphasis: Use `_single underscore_` for emphasis, `**double asterisk**` for strong\n- Links: Prefer inline links `[text](url)` for readability\n\n### Content Guidelines\n\n- Start with clear, descriptive headings (H1 for title, H2 for major sections)\n- Use code blocks for all code examples, terminal commands, and file paths\n- Include language identifiers in fenced code blocks (`typescript`, `bash`, `json`)\n- Break long paragraphs into shorter ones (3-5 sentences max)\n- Use tables for structured data comparison\n- Add blank lines before and after headings, lists, code blocks, and tables\n\n### Special Cases\n\n- Inline HTML allowed for badges, complex layouts, or special formatting\n- Bare URLs allowed in reference sections and changelogs\n- Line length not enforced (practical for existing docs)\n- Multiple H1 headings allowed (document sections)\n\n### Linting\n\n- Run `pnpm lint:md` to check markdown files\n- Run `pnpm lint:md:fix` to auto-fix issues\n- Pre-commit hooks automatically lint staged .md files\n- Configuration: `.markdownlint.json` and `.markdownlintignore`\n- If necessary, use `markdownlint` CLI directly, but prefer pnpm scripts\n\n## Code Change Checklist\n\nAfter making code changes, run these commands to verify quality:\n\n### Required (always run)\n\n- `pnpm lint` - Lint and type check (oxlint --type-aware --type-check)\n- `pnpm format` - Format code with oxfmt\n- `pnpm test` - Run unit tests (vitest)\n\n### Conditionally Required\n\n- `pnpm lint:md` - If editing markdown files\n- `pnpm lint:md:fix` - Auto-fix markdown issues\n- `pnpm run e2e` - For UI/behavior changes (Playwright tests)\n- `pnpm run ladle` - To visually inspect component changes\n\n### Quick Full Validation\n\n- `pnpm ci` - Run complete CI pipeline (setup, build, lint, lint:md, test, e2e)\n- `pnpm format:check` - Check if files are formatted without modifying them\n\n### Fixing Issues\n\nFormat issues are auto-fixed by `pnpm format`. oxlint issues must be fixed manually. Configure your editor to:\n\n- Format on save using oxfmt (140 char width, single quotes, no semicolons)\n- Show oxlint warnings/errors\n\nPre-commit hooks will block commits if lint (which includes type checking) fails.\n\n## Development Workflow\n\n1. Make changes in `packages/react-virtuoso/src/`\n2. Run `pnpm format && pnpm lint && pnpm test`\n3. Check examples with `pnpm run ladle` if UI changes\n4. Run `pnpm e2e` for end-to-end validation if needed\n5. Add changeset with `pnpm changeset-add` for versioned changes\n\n## Git Hooks\n\nThis project uses [lefthook](https://github.com/evilmartians/lefthook) for git hooks.\n\n### Pre-commit Checks\n\nOn every commit, the following checks run automatically on staged files:\n\n- **Code formatting**: Formats `.ts/.tsx/.js/.jsx` files with oxfmt and `.astro` files with prettier; changes are auto-staged via `stage_fixed`\n- **Markdown linting**: Validates .md files with markdownlint\n- **Code linting**: Validates code files with oxlint\n\n### Skipping Hooks\n\nIf you need to skip hooks (e.g., WIP commits):\n\n```bash\nLEFTHOOK=0 git commit -m \"WIP: work in progress\"\n# Or use git commit --no-verify (not recommended)\n```\n\n### Hook Management\n\n- Configuration: `lefthook.json`\n- Install hooks: `pnpm exec lefthook install`\n- Uninstall hooks: `pnpm exec lefthook uninstall`\n- Run manually: `pnpm exec lefthook run pre-commit`\n","AGENTS.md":"# AGENTS.md\n\nRepo-specific guidance for agents working in `react-virtuoso`.\n\nUse this file for repo-specific navigation, validation, and documentation rules only. Keep it short, concrete, and limited to information that helps an agent make better decisions in this repository.\n\nIf a rule here appears to conflict with `package.json`, the actual filesystem, or a more specific instruction file in scope, trust the repo state and the more specific instruction.\n\n## High-Signal Rules\n\n- This is a `pnpm` workspaces monorepo. Prefer running commands from the repo root unless you need package-local scope.\n- Root `pnpm lint` does **not** run type checking. Run `pnpm typecheck` separately when you need type validation.\n- Internal working artifacts belong in Notion, not in repo markdown files.\n  - Use Notion for PRPs, plans, clarifications, execution notes, verification notes, prompts, investigations, reports, audits, and exported findings that are not product docs.\n  - Do not create or keep repo markdown artifacts in folders like `plans/`, `prompts/`, `reports/`, or similar ad hoc locations.\n  - Create new internal artifacts from the shared Notion template at `https://www.notion.so/3461834d8eff81318a4cccaf19b0de51` instead of creating free-form pages from scratch.\n  - The template's visual settings such as `Small text` and `Full width` are maintained manually in Notion. Preserve them by duplicating the template when possible.\n  - If the user asks for a PRP workflow, create or update the artifact in Notion instead of creating `plans/*.md`.\n  - If the user asks for a report or findings export, prefer a Notion page unless they explicitly ask for a repo file.\n  - Set a page icon that matches the artifact type or content when creating the page. Prefer clear, stable icons such as `📗` for PRPs/plans, `📊` for reports, `🔎` for investigations, `✍️` for prompts, and `🛠️` for execution notes.\n  - If an existing markdown file looks ambiguous, ask before deleting or migrating it.\n- Never use `data-testid` as a styling hook. It is reserved for tests. Use semantic attributes such as `data-table-element-role` instead.\n\n## NPM Registry Queries\n\nThis repo uses `devEngines.packageManager` with `\"onFail\": \"error\"` in the root `package.json`. `pnpm info` and `pnpm view` can fail because they delegate to npm and npm 11 rejects the request in this setup.\n\nUse npm from outside the repo instead:\n\n```bash\n(cd /tmp && npm info <package> version)\n```\n\n## Workspace Layout\n\n### Main packages\n\n- `packages/data-table` - virtualized data table package; currently the most active package in this repo\n- `packages/react-virtuoso` - main virtualization library\n- `packages/message-list` - chat/message list package\n- `packages/masonry` - masonry layout package\n- `packages/gurx` - reactive state library used by older Virtuoso internals\n- `packages/reactive-engine-*` - lower-level engine packages used by `data-table`\n\n### Apps and examples\n\n- `apps/virtuoso.dev` - Astro/Starlight docs site\n- `examples` - separate workspace for shared Ladle/integration examples\n- `packages/react-virtuoso/examples` - example pages used by `packages/react-virtuoso/e2e`\n\n## Plugin Distribution\n\n- This repo ships `virtuoso-skills` as a Claude Code plugin from `packages/virtuoso-skills/`, a Codex plugin from `plugins/virtuoso-skills/`, and a root `skills/` mirror for `npx skills`.\n- After merge, public Codex plugin install is:\n\n  ```bash\n  codex plugin marketplace add petyosi/react-virtuoso --ref main --sparse .agents/plugins --sparse plugins/virtuoso-skills\n  codex plugin add virtuoso-skills@virtuoso\n  ```\n\n- Source skill files live at `packages/virtuoso-skills/skills/<name>/SKILL.md`.\n- Do not edit `packages/virtuoso-skills/skills/*/references/`, root `skills/`, or `plugins/virtuoso-skills/skills/` directly. They are generated by `pnpm build:skills`.\n- Do not commit `.agents/skills/` for Codex/OpenCode/Cursor unless the cross-agent install plan changes. `npx skills` owns that target path.\n\n## Commands\n\n### Root\n\n- `pnpm build` - build all workspaces\n- `pnpm build:skills` - regenerate skill references and public skill mirrors\n- `pnpm validate:skills` - validate Claude and Codex plugin manifests\n- `pnpm typecheck` - run type checking across workspaces\n- `pnpm lint` - run package lint scripts across workspaces\n- `pnpm format` - format with `oxfmt`\n- `pnpm format:check` - check formatting with `oxfmt`\n- `pnpm test` - run workspace test scripts\n- `pnpm e2e` - run workspace e2e scripts\n- `pnpm lint:md` / `pnpm lint:md:fix` - markdown lint / fix\n- `pnpm ci` - full CI sequence: setup, build, typecheck, lint, markdown lint, test, e2e\n- `pnpm dev:docs` - start the docs site\n- `pnpm changeset-add` - add a changeset\n\n### `packages/data-table`\n\n- `pnpm build` - `tsc && vite build`\n- `pnpm typecheck` - `tsgo -b --noEmit`\n- `pnpm lint` - `oxlint --type-aware --type-check`\n- `pnpm test` - `vitest run --browser.headless`\n- `pnpm check` - `format:check + lint + typecheck`\n- `pnpm dev` - run Ladle serve mode\n- `pnpm dev:build` / `pnpm dev:preview` - Ladle build / preview\n\n### `packages/react-virtuoso`\n\n- `pnpm build` - Vite build\n- `pnpm typecheck` - `tsgo --noEmit`\n- `pnpm lint` - `oxlint --type-aware --type-check`\n- `pnpm test` - Vitest\n- `pnpm test:watch` - Vitest watch\n- `pnpm e2e` - Playwright\n- `pnpm ladle` - preview examples in Ladle\n\n### `apps/virtuoso.dev`\n\n- `pnpm dev` - Astro dev server\n- `pnpm build` - `shadcn build && astro build`\n- `pnpm lint` - `oxlint --type-aware --type-check && astro check`\n- `pnpm format` / `pnpm format:check` - `oxfmt` plus Prettier for `.astro`\n\n## Documentation Workflow\n\nThe docs site contains generated package docs. Do not edit the generated content under:\n\n- `apps/virtuoso.dev/src/content/docs/data-table/`\n- `apps/virtuoso.dev/src/content/docs/react-virtuoso/`\n- `apps/virtuoso.dev/src/content/docs/masonry/`\n- `apps/virtuoso.dev/src/content/docs/gurx/`\n- `apps/virtuoso.dev/src/content/docs/message-list/`\n\nEdit the source docs in the package instead:\n\n- `packages/data-table/README.md` and `packages/data-table/docs/*.md`\n- `packages/react-virtuoso/README.md` and `packages/react-virtuoso/docs/*.md`\n- `packages/message-list/README.md` and `packages/message-list/docs/*.md`\n- `packages/masonry/README.md`\n- `packages/gurx/README.md`\n\nAfter product docs changes:\n\n- run `pnpm lint:md` from the repo root\n- if docs-site content or registry code changed, run `pnpm --filter @virtuoso.dev/virtuoso.dev lint`\n\n## Validation Guidance\n\nChoose the narrowest validation that matches the change:\n\n- `packages/data-table` code changes: start with `pnpm check && pnpm test` in `packages/data-table`\n- `packages/react-virtuoso` code changes: run `pnpm lint && pnpm typecheck && pnpm test`, add `pnpm e2e` when behavior changes\n- docs-only markdown changes: run `pnpm lint:md`\n- docs site or registry changes: run `pnpm --filter @virtuoso.dev/virtuoso.dev lint`\n- broad cross-package changes: run root `pnpm typecheck && pnpm lint && pnpm test`\n\n## Architecture Notes\n\n- `packages/react-virtuoso` uses the custom `urx` stream/state system under `packages/react-virtuoso/src/urx`. If you touch its internals, follow existing `*System.ts` and `react-urx/` patterns.\n- `packages/data-table` is a separate package built on the `reactive-engine-*` workspaces. When working there, prefer matching existing engine/cell/stream patterns instead of borrowing directly from `react-virtuoso` internals.\n\n## Git Hooks\n\nThis repo uses `lefthook`. Pre-commit hooks format and lint staged files. If you need to skip them for a WIP commit:\n\n```bash\nLEFTHOOK=0 git commit -m \"WIP: ...\"\n```\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## NPM Registry Queries\n\nThis project uses `devEngines.packageManager` with `\"onFail\": \"error\"` in `package.json`, which causes `pnpm info` and `pnpm view` to fail because they delegate to npm, and npm 11 rejects the request. To check package versions, run npm from outside the project directory:\n\n```bash\n(cd /tmp && npm info <package> version)\n```\n\n## Build Commands\n\nThis is a pnpm workspaces monorepo. Run commands from the root or within specific workspace packages.\n\n### Root-level commands\n\nRun from repository root for all packages:\n\n- Build all: `pnpm build`\n- Lint all (includes type checking): `pnpm lint`\n- Format all: `pnpm format` (oxfmt)\n- Format check: `pnpm format:check`\n- Test all: `pnpm test`\n- E2E tests all: `pnpm e2e`\n- Markdown lint: `pnpm lint:md` / fix: `pnpm lint:md:fix`\n- Full CI: `pnpm ci` (setup, build, lint, lint:md, test, e2e)\n- Release: `pnpm release` (build + publish with changesets)\n- Add changeset: `pnpm changeset-add`\n- Dev docs site: `pnpm dev:docs`\n\n### react-virtuoso package (packages/react-virtuoso/)\n\n- Build: `pnpm run build` (uses vite)\n- Test: `pnpm run test` (vitest)\n- Test watch: `pnpm run test:watch`\n- Run single test: `pnpm vitest <test-file-path>` or `pnpm vitest -t \"<test-name>\"`\n- E2E tests: `pnpm run e2e` (playwright)\n- Lint (includes type checking): `pnpm run lint`\n- Format: `pnpm run format` (oxfmt)\n- Format check: `pnpm run format:check`\n- Dev/preview examples: `pnpm run ladle` (launches Ladle server for browsing examples/ folder)\n\n### virtuoso.dev docs app (apps/virtuoso.dev/)\n\n- Dev server: `pnpm run dev`\n- Build: `pnpm run build`\n- Format: `pnpm run format` (oxfmt + Prettier for .astro files)\n\nAfter docs changes: run `pnpm lint` from the app directory or root.\n\n**IMPORTANT - Documentation Locations:**\n\n**DO NOT EDIT** the following auto-generated directories:\n\n- `apps/virtuoso.dev/src/content/docs/data-table/`\n- `apps/virtuoso.dev/src/content/docs/react-virtuoso/`\n- `apps/virtuoso.dev/src/content/docs/masonry/`\n- `apps/virtuoso.dev/src/content/docs/gurx/`\n- `apps/virtuoso.dev/src/content/docs/message-list/`\n\nThese are auto-synced from source files + TypeDoc API via the `docsSync` integration. Any edits will be overwritten.\n\n**To edit package documentation**, modify the source files in each package:\n\n- **data-table**: `packages/data-table/docs/*.md`\n- **react-virtuoso**: `packages/react-virtuoso/README.md` or `packages/react-virtuoso/docs/*.md`\n- **masonry**: `packages/masonry/README.md` or `packages/masonry/docs/*.md`\n- **gurx**: `packages/gurx/README.md` or `packages/gurx/docs/*.md`\n- **message-list**: `packages/message-list/README.md` or `packages/message-list/docs/*.md`\n\n## Plugin Distribution\n\nThis repo ships `virtuoso-skills` as a Claude Code plugin from `packages/virtuoso-skills/`, a Codex plugin from `plugins/virtuoso-skills/`, and a root `skills/` mirror for `npx skills`.\n\nEdit source skill content in `packages/virtuoso-skills/skills/<name>/SKILL.md`. Do not edit `packages/virtuoso-skills/skills/*/references/`, root `skills/`, or `plugins/virtuoso-skills/skills/` directly; regenerate them with:\n\n```bash\npnpm build:skills\n```\n\nAfter merge, public Codex plugin install uses:\n\n```bash\ncodex plugin marketplace add petyosi/react-virtuoso --ref main --sparse .agents/plugins --sparse plugins/virtuoso-skills\ncodex plugin add virtuoso-skills@virtuoso\n```\n\nDo not commit `.agents/skills/` for Codex/OpenCode/Cursor unless the cross-agent install plan changes. `npx skills` owns that target path.\n\n## Monorepo Structure\n\n```text\npackages/\n  react-virtuoso/    - Main virtualization library\n  gurx/             - urx state management (fork/variant)\n  masonry/          - Masonry layout component\n  message-list/     - Chat/message list component\n  tooling/          - Shared build tooling\n\napps/\n  virtuoso.dev/     - Starlight/Astro documentation site\n\nexamples/            - Ladle stories for testing/development\n```\n\n## Architecture\n\n### State Management: urx System\n\nThe codebase uses **urx**, a custom reactive state management system built on streams/observables. Core concepts:\n\n- **Systems**: Stateful data-processing machines composed of streams\n- **Streams**: Can be stateless (signals) or stateful (depots that persist values)\n- **Depots**: Implicit state maintained in stateful streams, transformers (combineLatest), or operators (withLatestFrom, scan)\n- **Input/Output**: Systems receive input via input streams, process via transformers/operators, emit via output streams\n\nKey urx files: `src/urx/` directory contains:\n\n- `system.ts` - System creation and composition\n- `streams.ts` - Stream primitives\n- `pipe.ts` - Stream operators and transformers\n- `actions.ts` - Publishing/emitting\n- `transformers.ts` - Stream transformation utilities\n\n### Component Architecture\n\nThe virtualization logic is split into modular systems in `src/`:\n\n**Core Systems:**\n\n- `listSystem.ts` - Composes all feature systems into the main list system\n- `sizeSystem.ts` - Tracks and manages item sizes (critical for variable-height items)\n- `listStateSystem.ts` - Manages visible item ranges and scrolling state\n- `domIOSystem.ts` - DOM measurements and interactions\n\n**Feature Systems:**\n\n- `groupedListSystem.ts` - Grouped lists with sticky headers\n- `scrollToIndexSystem.ts` - Programmatic scroll positioning\n- `followOutputSystem.ts` - Auto-scroll for chat/feed UIs\n- `initialTopMostItemIndexSystem.ts` - Initial scroll position\n- `scrollSeekSystem.ts` - Placeholder rendering during fast scrolling\n- `windowScrollerSystem.ts` - Window-scrolling mode\n- And many more in `src/*System.ts` files\n\n**React Integration:**\n\n- `react-urx/` - Bridges urx systems to React components\n- `Virtuoso.tsx` - Main list component\n- `VirtuosoGrid.tsx` - Grid layout component\n- `TableVirtuoso.tsx` - Table virtualization component\n- Component interfaces in `component-interfaces/`\n\n### Size Calculation\n\nVariable-sized items work automatically via `sizeSystem.ts`:\n\n- Uses ResizeObserver for measurements\n- Maintains size ranges and estimates\n- No manual height specification needed\n- `correctItemSize()` utility in `utils/` handles size corrections\n\n### E2E Testing\n\nE2E tests in `packages/react-virtuoso/e2e/`:\n\n- Test files: `*.test.ts` (Playwright tests)\n- Example pages: `examples/*.tsx` (rendered in browser for tests)\n- Use Ladle (`pnpm run ladle`) to preview examples during development\n\n## Code Style\n\n- Never use `data-testid` attributes for CSS styling selectors. `data-testid` is reserved for testing only. Use `data-table-element-role` or other semantic data attributes for styling hooks.\n- TypeScript with strong typing; avoid `any`\n- oxfmt: 140 char width, single quotes, no semicolons\n- Naming: camelCase for variables/functions, PascalCase for components\n- Imports: React first, external libs, then internal modules\n- Functional components with hooks preferred\n- Use urx system patterns for state management\n- Error handling: prefer early returns\n\n## Markdown Style Guide\n\nWhen writing or editing markdown documentation:\n\n### Formatting Rules\n\n- Headings: ATX-style (`# Heading` not `Heading\\n=======`)\n- Code blocks: Always use fenced blocks with language specifiers\n\n```typescript\nconst foo = 'bar'\n```\n\n- Lists: Use `-` for unordered lists, indent nested items by 2 spaces\n- Emphasis: Use `_single underscore_` for emphasis, `**double asterisk**` for strong\n- Links: Prefer inline links `[text](url)` for readability\n\n### Content Guidelines\n\n- Start with clear, descriptive headings (H1 for title, H2 for major sections)\n- Use code blocks for all code examples, terminal commands, and file paths\n- Include language identifiers in fenced code blocks (`typescript`, `bash`, `json`)\n- Break long paragraphs into shorter ones (3-5 sentences max)\n- Use tables for structured data comparison\n- Add blank lines before and after headings, lists, code blocks, and tables\n\n### Special Cases\n\n- Inline HTML allowed for badges, complex layouts, or special formatting\n- Bare URLs allowed in reference sections and changelogs\n- Line length not enforced (practical for existing docs)\n- Multiple H1 headings allowed (document sections)\n\n### Linting\n\n- Run `pnpm lint:md` to check markdown files\n- Run `pnpm lint:md:fix` to auto-fix issues\n- Pre-commit hooks automatically lint staged .md files\n- Configuration: `.markdownlint.json` and `.markdownlintignore`\n- If necessary, use `markdownlint` CLI directly, but prefer pnpm scripts\n\n## Code Change Checklist\n\nAfter making code changes, run these commands to verify quality:\n\n### Required (always run)\n\n- `pnpm lint` - Lint and type check (oxlint --type-aware --type-check)\n- `pnpm format` - Format code with oxfmt\n- `pnpm test` - Run unit tests (vitest)\n\n### Conditionally Required\n\n- `pnpm lint:md` - If editing markdown files\n- `pnpm lint:md:fix` - Auto-fix markdown issues\n- `pnpm run e2e` - For UI/behavior changes (Playwright tests)\n- `pnpm run ladle` - To visually inspect component changes\n\n### Quick Full Validation\n\n- `pnpm ci` - Run complete CI pipeline (setup, build, lint, lint:md, test, e2e)\n- `pnpm format:check` - Check if files are formatted without modifying them\n\n### Fixing Issues\n\nFormat issues are auto-fixed by `pnpm format`. oxlint issues must be fixed manually. Configure your editor to:\n\n- Format on save using oxfmt (140 char width, single quotes, no semicolons)\n- Show oxlint warnings/errors\n\nPre-commit hooks will block commits if lint (which includes type checking) fails.\n\n## Development Workflow\n\n1. Make changes in `packages/react-virtuoso/src/`\n2. Run `pnpm format && pnpm lint && pnpm test`\n3. Check examples with `pnpm run ladle` if UI changes\n4. Run `pnpm e2e` for end-to-end validation if needed\n5. Add changeset with `pnpm changeset-add` for versioned changes\n\n## Git Hooks\n\nThis project uses [lefthook](https://github.com/evilmartians/lefthook) for git hooks.\n\n### Pre-commit Checks\n\nOn every commit, the following checks run automatically on staged files:\n\n- **Code formatting**: Formats `.ts/.tsx/.js/.jsx` files with oxfmt and `.astro` files with prettier; changes are auto-staged via `stage_fixed`\n- **Markdown linting**: Validates .md files with markdownlint\n- **Code linting**: Validates code files with oxlint\n\n### Skipping Hooks\n\nIf you need to skip hooks (e.g., WIP commits):\n\n```bash\nLEFTHOOK=0 git commit -m \"WIP: work in progress\"\n# Or use git commit --no-verify (not recommended)\n```\n\n### Hook Management\n\n- Configuration: `lefthook.json`\n- Install hooks: `pnpm exec lefthook install`\n- Uninstall hooks: `pnpm exec lefthook uninstall`\n- Run manually: `pnpm exec lefthook run pre-commit`\n","AGENTS.md":"# AGENTS.md\n\nRepo-specific guidance for agents working in `react-virtuoso`.\n\nUse this file for repo-specific navigation, validation, and documentation rules only. Keep it short, concrete, and limited to information that helps an agent make better decisions in this repository.\n\nIf a rule here appears to conflict with `package.json`, the actual filesystem, or a more specific instruction file in scope, trust the repo state and the more specific instruction.\n\n## High-Signal Rules\n\n- This is a `pnpm` workspaces monorepo. Prefer running commands from the repo root unless you need package-local scope.\n- Root `pnpm lint` does **not** run type checking. Run `pnpm typecheck` separately when you need type validation.\n- Internal working artifacts belong in Notion, not in repo markdown files.\n  - Use Notion for PRPs, plans, clarifications, execution notes, verification notes, prompts, investigations, reports, audits, and exported findings that are not product docs.\n  - Do not create or keep repo markdown artifacts in folders like `plans/`, `prompts/`, `reports/`, or similar ad hoc locations.\n  - Create new internal artifacts from the shared Notion template at `https://www.notion.so/3461834d8eff81318a4cccaf19b0de51` instead of creating free-form pages from scratch.\n  - The template's visual settings such as `Small text` and `Full width` are maintained manually in Notion. Preserve them by duplicating the template when possible.\n  - If the user asks for a PRP workflow, create or update the artifact in Notion instead of creating `plans/*.md`.\n  - If the user asks for a report or findings export, prefer a Notion page unless they explicitly ask for a repo file.\n  - Set a page icon that matches the artifact type or content when creating the page. Prefer clear, stable icons such as `📗` for PRPs/plans, `📊` for reports, `🔎` for investigations, `✍️` for prompts, and `🛠️` for execution notes.\n  - If an existing markdown file looks ambiguous, ask before deleting or migrating it.\n- Never use `data-testid` as a styling hook. It is reserved for tests. Use semantic attributes such as `data-table-element-role` instead.\n\n## NPM Registry Queries\n\nThis repo uses `devEngines.packageManager` with `\"onFail\": \"error\"` in the root `package.json`. `pnpm info` and `pnpm view` can fail because they delegate to npm and npm 11 rejects the request in this setup.\n\nUse npm from outside the repo instead:\n\n```bash\n(cd /tmp && npm info <package> version)\n```\n\n## Workspace Layout\n\n### Main packages\n\n- `packages/data-table` - virtualized data table package; currently the most active package in this repo\n- `packages/react-virtuoso` - main virtualization library\n- `packages/message-list` - chat/message list package\n- `packages/masonry` - masonry layout package\n- `packages/gurx` - reactive state library used by older Virtuoso internals\n- `packages/reactive-engine-*` - lower-level engine packages used by `data-table`\n\n### Apps and examples\n\n- `apps/virtuoso.dev` - Astro/Starlight docs site\n- `examples` - separate workspace for shared Ladle/integration examples\n- `packages/react-virtuoso/examples` - example pages used by `packages/react-virtuoso/e2e`\n\n## Plugin Distribution\n\n- This repo ships `virtuoso-skills` as a Claude Code plugin from `packages/virtuoso-skills/`, a Codex plugin from `plugins/virtuoso-skills/`, and a root `skills/` mirror for `npx skills`.\n- After merge, public Codex plugin install is:\n\n  ```bash\n  codex plugin marketplace add petyosi/react-virtuoso --ref main --sparse .agents/plugins --sparse plugins/virtuoso-skills\n  codex plugin add virtuoso-skills@virtuoso\n  ```\n\n- Source skill files live at `packages/virtuoso-skills/skills/<name>/SKILL.md`.\n- Do not edit `packages/virtuoso-skills/skills/*/references/`, root `skills/`, or `plugins/virtuoso-skills/skills/` directly. They are generated by `pnpm build:skills`.\n- Do not commit `.agents/skills/` for Codex/OpenCode/Cursor unless the cross-agent install plan changes. `npx skills` owns that target path.\n\n## Commands\n\n### Root\n\n- `pnpm build` - build all workspaces\n- `pnpm build:skills` - regenerate skill references and public skill mirrors\n- `pnpm validate:skills` - validate Claude and Codex plugin manifests\n- `pnpm typecheck` - run type checking across workspaces\n- `pnpm lint` - run package lint scripts across workspaces\n- `pnpm format` - format with `oxfmt`\n- `pnpm format:check` - check formatting with `oxfmt`\n- `pnpm test` - run workspace test scripts\n- `pnpm e2e` - run workspace e2e scripts\n- `pnpm lint:md` / `pnpm lint:md:fix` - markdown lint / fix\n- `pnpm ci` - full CI sequence: setup, build, typecheck, lint, markdown lint, test, e2e\n- `pnpm dev:docs` - start the docs site\n- `pnpm changeset-add` - add a changeset\n\n### `packages/data-table`\n\n- `pnpm build` - `tsc && vite build`\n- `pnpm typecheck` - `tsgo -b --noEmit`\n- `pnpm lint` - `oxlint --type-aware --type-check`\n- `pnpm test` - `vitest run --browser.headless`\n- `pnpm check` - `format:check + lint + typecheck`\n- `pnpm dev` - run Ladle serve mode\n- `pnpm dev:build` / `pnpm dev:preview` - Ladle build / preview\n\n### `packages/react-virtuoso`\n\n- `pnpm build` - Vite build\n- `pnpm typecheck` - `tsgo --noEmit`\n- `pnpm lint` - `oxlint --type-aware --type-check`\n- `pnpm test` - Vitest\n- `pnpm test:watch` - Vitest watch\n- `pnpm e2e` - Playwright\n- `pnpm ladle` - preview examples in Ladle\n\n### `apps/virtuoso.dev`\n\n- `pnpm dev` - Astro dev server\n- `pnpm build` - `shadcn build && astro build`\n- `pnpm lint` - `oxlint --type-aware --type-check && astro check`\n- `pnpm format` / `pnpm format:check` - `oxfmt` plus Prettier for `.astro`\n\n## Documentation Workflow\n\nThe docs site contains generated package docs. Do not edit the generated content under:\n\n- `apps/virtuoso.dev/src/content/docs/data-table/`\n- `apps/virtuoso.dev/src/content/docs/react-virtuoso/`\n- `apps/virtuoso.dev/src/content/docs/masonry/`\n- `apps/virtuoso.dev/src/content/docs/gurx/`\n- `apps/virtuoso.dev/src/content/docs/message-list/`\n\nEdit the source docs in the package instead:\n\n- `packages/data-table/README.md` and `packages/data-table/docs/*.md`\n- `packages/react-virtuoso/README.md` and `packages/react-virtuoso/docs/*.md`\n- `packages/message-list/README.md` and `packages/message-list/docs/*.md`\n- `packages/masonry/README.md`\n- `packages/gurx/README.md`\n\nAfter product docs changes:\n\n- run `pnpm lint:md` from the repo root\n- if docs-site content or registry code changed, run `pnpm --filter @virtuoso.dev/virtuoso.dev lint`\n\n## Validation Guidance\n\nChoose the narrowest validation that matches the change:\n\n- `packages/data-table` code changes: start with `pnpm check && pnpm test` in `packages/data-table`\n- `packages/react-virtuoso` code changes: run `pnpm lint && pnpm typecheck && pnpm test`, add `pnpm e2e` when behavior changes\n- docs-only markdown changes: run `pnpm lint:md`\n- docs site or registry changes: run `pnpm --filter @virtuoso.dev/virtuoso.dev lint`\n- broad cross-package changes: run root `pnpm typecheck && pnpm lint && pnpm test`\n\n## Architecture Notes\n\n- `packages/react-virtuoso` uses the custom `urx` stream/state system under `packages/react-virtuoso/src/urx`. If you touch its internals, follow existing `*System.ts` and `react-urx/` patterns.\n- `packages/data-table` is a separate package built on the `reactive-engine-*` workspaces. When working there, prefer matching existing engine/cell/stream patterns instead of borrowing directly from `react-virtuoso` internals.\n\n## Git Hooks\n\nThis repo uses `lefthook`. Pre-commit hooks format and lint staged files. If you need to skip them for a WIP commit:\n\n```bash\nLEFTHOOK=0 git commit -m \"WIP: ...\"\n```\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## NPM Registry Queries\n\nThis project uses `devEngines.packageManager` with `\"onFail\": \"error\"` in `package.json`, which causes `pnpm info` and `pnpm view` to fail because they delegate to npm, and npm 11 rejects the request. To check package versions, run npm from outside the project directory:\n\n```bash\n(cd /tmp && npm info <package> version)\n```\n\n## Build Commands\n\nThis is a pnpm workspaces monorepo. Run commands from the root or within specific workspace packages.\n\n### Root-level commands\n\nRun from repository root for all packages:\n\n- Build all: `pnpm build`\n- Lint all (includes type checking): `pnpm lint`\n- Format all: `pnpm format` (oxfmt)\n- Format check: `pnpm format:check`\n- Test all: `pnpm test`\n- E2E tests all: `pnpm e2e`\n- Markdown lint: `pnpm lint:md` / fix: `pnpm lint:md:fix`\n- Full CI: `pnpm ci` (setup, build, lint, lint:md, test, e2e)\n- Release: `pnpm release` (build + publish with changesets)\n- Add changeset: `pnpm changeset-add`\n- Dev docs site: `pnpm dev:docs`\n\n### react-virtuoso package (packages/react-virtuoso/)\n\n- Build: `pnpm run build` (uses vite)\n- Test: `pnpm run test` (vitest)\n- Test watch: `pnpm run test:watch`\n- Run single test: `pnpm vitest <test-file-path>` or `pnpm vitest -t \"<test-name>\"`\n- E2E tests: `pnpm run e2e` (playwright)\n- Lint (includes type checking): `pnpm run lint`\n- Format: `pnpm run format` (oxfmt)\n- Format check: `pnpm run format:check`\n- Dev/preview examples: `pnpm run ladle` (launches Ladle server for browsing examples/ folder)\n\n### virtuoso.dev docs app (apps/virtuoso.dev/)\n\n- Dev server: `pnpm run dev`\n- Build: `pnpm run build`\n- Format: `pnpm run format` (oxfmt + Prettier for .astro files)\n\nAfter docs changes: run `pnpm lint` from the app directory or root.\n\n**IMPORTANT - Documentation Locations:**\n\n**DO NOT EDIT** the following auto-generated directories:\n\n- `apps/virtuoso.dev/src/content/docs/data-table/`\n- `apps/virtuoso.dev/src/content/docs/react-virtuoso/`\n- `apps/virtuoso.dev/src/content/docs/masonry/`\n- `apps/virtuoso.dev/src/content/docs/gurx/`\n- `apps/virtuoso.dev/src/content/docs/message-list/`\n\nThese are auto-synced from source files + TypeDoc API via the `docsSync` integration. Any edits will be overwritten.\n\n**To edit package documentation**, modify the source files in each package:\n\n- **data-table**: `packages/data-table/docs/*.md`\n- **react-virtuoso**: `packages/react-virtuoso/README.md` or `packages/react-virtuoso/docs/*.md`\n- **masonry**: `packages/masonry/README.md` or `packages/masonry/docs/*.md`\n- **gurx**: `packages/gurx/README.md` or `packages/gurx/docs/*.md`\n- **message-list**: `packages/message-list/README.md` or `packages/message-list/docs/*.md`\n\n## Plugin Distribution\n\nThis repo ships `virtuoso-skills` as a Claude Code plugin from `packages/virtuoso-skills/`, a Codex plugin from `plugins/virtuoso-skills/`, and a root `skills/` mirror for `npx skills`.\n\nEdit source skill content in `packages/virtuoso-skills/skills/<name>/SKILL.md`. Do not edit `packages/virtuoso-skills/skills/*/references/`, root `skills/`, or `plugins/virtuoso-skills/skills/` directly; regenerate them with:\n\n```bash\npnpm build:skills\n```\n\nAfter merge, public Codex plugin install uses:\n\n```bash\ncodex plugin marketplace add petyosi/react-virtuoso --ref main --sparse .agents/plugins --sparse plugins/virtuoso-skills\ncodex plugin add virtuoso-skills@virtuoso\n```\n\nDo not commit `.agents/skills/` for Codex/OpenCode/Cursor unless the cross-agent install plan changes. `npx skills` owns that target path.\n\n## Monorepo Structure\n\n```text\npackages/\n  react-virtuoso/    - Main virtualization library\n  gurx/             - urx state management (fork/variant)\n  masonry/          - Masonry layout component\n  message-list/     - Chat/message list component\n  tooling/          - Shared build tooling\n\napps/\n  virtuoso.dev/     - Starlight/Astro documentation site\n\nexamples/            - Ladle stories for testing/development\n```\n\n## Architecture\n\n### State Management: urx System\n\nThe codebase uses **urx**, a custom reactive state management system built on streams/observables. Core concepts:\n\n- **Systems**: Stateful data-processing machines composed of streams\n- **Streams**: Can be stateless (signals) or stateful (depots that persist values)\n- **Depots**: Implicit state maintained in stateful streams, transformers (combineLatest), or operators (withLatestFrom, scan)\n- **Input/Output**: Systems receive input via input streams, process via transformers/operators, emit via output streams\n\nKey urx files: `src/urx/` directory contains:\n\n- `system.ts` - System creation and composition\n- `streams.ts` - Stream primitives\n- `pipe.ts` - Stream operators and transformers\n- `actions.ts` - Publishing/emitting\n- `transformers.ts` - Stream transformation utilities\n\n### Component Architecture\n\nThe virtualization logic is split into modular systems in `src/`:\n\n**Core Systems:**\n\n- `listSystem.ts` - Composes all feature systems into the main list system\n- `sizeSystem.ts` - Tracks and manages item sizes (critical for variable-height items)\n- `listStateSystem.ts` - Manages visible item ranges and scrolling state\n- `domIOSystem.ts` - DOM measurements and interactions\n\n**Feature Systems:**\n\n- `groupedListSystem.ts` - Grouped lists with sticky headers\n- `scrollToIndexSystem.ts` - Programmatic scroll positioning\n- `followOutputSystem.ts` - Auto-scroll for chat/feed UIs\n- `initialTopMostItemIndexSystem.ts` - Initial scroll position\n- `scrollSeekSystem.ts` - Placeholder rendering during fast scrolling\n- `windowScrollerSystem.ts` - Window-scrolling mode\n- And many more in `src/*System.ts` files\n\n**React Integration:**\n\n- `react-urx/` - Bridges urx systems to React components\n- `Virtuoso.tsx` - Main list component\n- `VirtuosoGrid.tsx` - Grid layout component\n- `TableVirtuoso.tsx` - Table virtualization component\n- Component interfaces in `component-interfaces/`\n\n### Size Calculation\n\nVariable-sized items work automatically via `sizeSystem.ts`:\n\n- Uses ResizeObserver for measurements\n- Maintains size ranges and estimates\n- No manual height specification needed\n- `correctItemSize()` utility in `utils/` handles size corrections\n\n### E2E Testing\n\nE2E tests in `packages/react-virtuoso/e2e/`:\n\n- Test files: `*.test.ts` (Playwright tests)\n- Example pages: `examples/*.tsx` (rendered in browser for tests)\n- Use Ladle (`pnpm run ladle`) to preview examples during development\n\n## Code Style\n\n- Never use `data-testid` attributes for CSS styling selectors. `data-testid` is reserved for testing only. Use `data-table-element-role` or other semantic data attributes for styling hooks.\n- TypeScript with strong typing; avoid `any`\n- oxfmt: 140 char width, single quotes, no semicolons\n- Naming: camelCase for variables/functions, PascalCase for components\n- Imports: React first, external libs, then internal modules\n- Functional components with hooks preferred\n- Use urx system patterns for state management\n- Error handling: prefer early returns\n\n## Markdown Style Guide\n\nWhen writing or editing markdown documentation:\n\n### Formatting Rules\n\n- Headings: ATX-style (`# Heading` not `Heading\\n=======`)\n- Code blocks: Always use fenced blocks with language specifiers\n\n```typescript\nconst foo = 'bar'\n```\n\n- Lists: Use `-` for unordered lists, indent nested items by 2 spaces\n- Emphasis: Use `_single underscore_` for emphasis, `**double asterisk**` for strong\n- Links: Prefer inline links `[text](url)` for readability\n\n### Content Guidelines\n\n- Start with clear, descriptive headings (H1 for title, H2 for major sections)\n- Use code blocks for all code examples, terminal commands, and file paths\n- Include language identifiers in fenced code blocks (`typescript`, `bash`, `json`)\n- Break long paragraphs into shorter ones (3-5 sentences max)\n- Use tables for structured data comparison\n- Add blank lines before and after headings, lists, code blocks, and tables\n\n### Special Cases\n\n- Inline HTML allowed for badges, complex layouts, or special formatting\n- Bare URLs allowed in reference sections and changelogs\n- Line length not enforced (practical for existing docs)\n- Multiple H1 headings allowed (document sections)\n\n### Linting\n\n- Run `pnpm lint:md` to check markdown files\n- Run `pnpm lint:md:fix` to auto-fix issues\n- Pre-commit hooks automatically lint staged .md files\n- Configuration: `.markdownlint.json` and `.markdownlintignore`\n- If necessary, use `markdownlint` CLI directly, but prefer pnpm scripts\n\n## Code Change Checklist\n\nAfter making code changes, run these commands to verify quality:\n\n### Required (always run)\n\n- `pnpm lint` - Lint and type check (oxlint --type-aware --type-check)\n- `pnpm format` - Format code with oxfmt\n- `pnpm test` - Run unit tests (vitest)\n\n### Conditionally Required\n\n- `pnpm lint:md` - If editing markdown files\n- `pnpm lint:md:fix` - Auto-fix markdown issues\n- `pnpm run e2e` - For UI/behavior changes (Playwright tests)\n- `pnpm run ladle` - To visually inspect component changes\n\n### Quick Full Validation\n\n- `pnpm ci` - Run complete CI pipeline (setup, build, lint, lint:md, test, e2e)\n- `pnpm format:check` - Check if files are formatted without modifying them\n\n### Fixing Issues\n\nFormat issues are auto-fixed by `pnpm format`. oxlint issues must be fixed manually. Configure your editor to:\n\n- Format on save using oxfmt (140 char width, single quotes, no semicolons)\n- Show oxlint warnings/errors\n\nPre-commit hooks will block commits if lint (which includes type checking) fails.\n\n## Development Workflow\n\n1. Make changes in `packages/react-virtuoso/src/`\n2. Run `pnpm format && pnpm lint && pnpm test`\n3. Check examples with `pnpm run ladle` if UI changes\n4. Run `pnpm e2e` for end-to-end validation if needed\n5. Add changeset with `pnpm changeset-add` for versioned changes\n\n## Git Hooks\n\nThis project uses [lefthook](https://github.com/evilmartians/lefthook) for git hooks.\n\n### Pre-commit Checks\n\nOn every commit, the following checks run automatically on staged files:\n\n- **Code formatting**: Formats `.ts/.tsx/.js/.jsx` files with oxfmt and `.astro` files with prettier; changes are auto-staged via `stage_fixed`\n- **Markdown linting**: Validates .md files with markdownlint\n- **Code linting**: Validates code files with oxlint\n\n### Skipping Hooks\n\nIf you need to skip hooks (e.g., WIP commits):\n\n```bash\nLEFTHOOK=0 git commit -m \"WIP: work in progress\"\n# Or use git commit --no-verify (not recommended)\n```\n\n### Hook Management\n\n- Configuration: `lefthook.json`\n- Install hooks: `pnpm exec lefthook install`\n- Uninstall hooks: `pnpm exec lefthook uninstall`\n- Run manually: `pnpm exec lefthook run pre-commit`\n","category":"root","tokens":2674},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nRepo-specific guidance for agents working in `react-virtuoso`.\n\nUse this file for repo-specific navigation, validation, and documentation rules only. Keep it short, concrete, and limited to information that helps an agent make better decisions in this repository.\n\nIf a rule here appears to conflict with `package.json`, the actual filesystem, or a more specific instruction file in scope, trust the repo state and the more specific instruction.\n\n## High-Signal Rules\n\n- This is a `pnpm` workspaces monorepo. Prefer running commands from the repo root unless you need package-local scope.\n- Root `pnpm lint` does **not** run type checking. Run `pnpm typecheck` separately when you need type validation.\n- Internal working artifacts belong in Notion, not in repo markdown files.\n  - Use Notion for PRPs, plans, clarifications, execution notes, verification notes, prompts, investigations, reports, audits, and exported findings that are not product docs.\n  - Do not create or keep repo markdown artifacts in folders like `plans/`, `prompts/`, `reports/`, or similar ad hoc locations.\n  - Create new internal artifacts from the shared Notion template at `https://www.notion.so/3461834d8eff81318a4cccaf19b0de51` instead of creating free-form pages from scratch.\n  - The template's visual settings such as `Small text` and `Full width` are maintained manually in Notion. Preserve them by duplicating the template when possible.\n  - If the user asks for a PRP workflow, create or update the artifact in Notion instead of creating `plans/*.md`.\n  - If the user asks for a report or findings export, prefer a Notion page unless they explicitly ask for a repo file.\n  - Set a page icon that matches the artifact type or content when creating the page. Prefer clear, stable icons such as `📗` for PRPs/plans, `📊` for reports, `🔎` for investigations, `✍️` for prompts, and `🛠️` for execution notes.\n  - If an existing markdown file looks ambiguous, ask before deleting or migrating it.\n- Never use `data-testid` as a styling hook. It is reserved for tests. Use semantic attributes such as `data-table-element-role` instead.\n\n## NPM Registry Queries\n\nThis repo uses `devEngines.packageManager` with `\"onFail\": \"error\"` in the root `package.json`. `pnpm info` and `pnpm view` can fail because they delegate to npm and npm 11 rejects the request in this setup.\n\nUse npm from outside the repo instead:\n\n```bash\n(cd /tmp && npm info <package> version)\n```\n\n## Workspace Layout\n\n### Main packages\n\n- `packages/data-table` - virtualized data table package; currently the most active package in this repo\n- `packages/react-virtuoso` - main virtualization library\n- `packages/message-list` - chat/message list package\n- `packages/masonry` - masonry layout package\n- `packages/gurx` - reactive state library used by older Virtuoso internals\n- `packages/reactive-engine-*` - lower-level engine packages used by `data-table`\n\n### Apps and examples\n\n- `apps/virtuoso.dev` - Astro/Starlight docs site\n- `examples` - separate workspace for shared Ladle/integration examples\n- `packages/react-virtuoso/examples` - example pages used by `packages/react-virtuoso/e2e`\n\n## Plugin Distribution\n\n- This repo ships `virtuoso-skills` as a Claude Code plugin from `packages/virtuoso-skills/`, a Codex plugin from `plugins/virtuoso-skills/`, and a root `skills/` mirror for `npx skills`.\n- After merge, public Codex plugin install is:\n\n  ```bash\n  codex plugin marketplace add petyosi/react-virtuoso --ref main --sparse .agents/plugins --sparse plugins/virtuoso-skills\n  codex plugin add virtuoso-skills@virtuoso\n  ```\n\n- Source skill files live at `packages/virtuoso-skills/skills/<name>/SKILL.md`.\n- Do not edit `packages/virtuoso-skills/skills/*/references/`, root `skills/`, or `plugins/virtuoso-skills/skills/` directly. They are generated by `pnpm build:skills`.\n- Do not commit `.agents/skills/` for Codex/OpenCode/Cursor unless the cross-agent install plan changes. `npx skills` owns that target path.\n\n## Commands\n\n### Root\n\n- `pnpm build` - build all workspaces\n- `pnpm build:skills` - regenerate skill references and public skill mirrors\n- `pnpm validate:skills` - validate Claude and Codex plugin manifests\n- `pnpm typecheck` - run type checking across workspaces\n- `pnpm lint` - run package lint scripts across workspaces\n- `pnpm format` - format with `oxfmt`\n- `pnpm format:check` - check formatting with `oxfmt`\n- `pnpm test` - run workspace test scripts\n- `pnpm e2e` - run workspace e2e scripts\n- `pnpm lint:md` / `pnpm lint:md:fix` - markdown lint / fix\n- `pnpm ci` - full CI sequence: setup, build, typecheck, lint, markdown lint, test, e2e\n- `pnpm dev:docs` - start the docs site\n- `pnpm changeset-add` - add a changeset\n\n### `packages/data-table`\n\n- `pnpm build` - `tsc && vite build`\n- `pnpm typecheck` - `tsgo -b --noEmit`\n- `pnpm lint` - `oxlint --type-aware --type-check`\n- `pnpm test` - `vitest run --browser.headless`\n- `pnpm check` - `format:check + lint + typecheck`\n- `pnpm dev` - run Ladle serve mode\n- `pnpm dev:build` / `pnpm dev:preview` - Ladle build / preview\n\n### `packages/react-virtuoso`\n\n- `pnpm build` - Vite build\n- `pnpm typecheck` - `tsgo --noEmit`\n- `pnpm lint` - `oxlint --type-aware --type-check`\n- `pnpm test` - Vitest\n- `pnpm test:watch` - Vitest watch\n- `pnpm e2e` - Playwright\n- `pnpm ladle` - preview examples in Ladle\n\n### `apps/virtuoso.dev`\n\n- `pnpm dev` - Astro dev server\n- `pnpm build` - `shadcn build && astro build`\n- `pnpm lint` - `oxlint --type-aware --type-check && astro check`\n- `pnpm format` / `pnpm format:check` - `oxfmt` plus Prettier for `.astro`\n\n## Documentation Workflow\n\nThe docs site contains generated package docs. Do not edit the generated content under:\n\n- `apps/virtuoso.dev/src/content/docs/data-table/`\n- `apps/virtuoso.dev/src/content/docs/react-virtuoso/`\n- `apps/virtuoso.dev/src/content/docs/masonry/`\n- `apps/virtuoso.dev/src/content/docs/gurx/`\n- `apps/virtuoso.dev/src/content/docs/message-list/`\n\nEdit the source docs in the package instead:\n\n- `packages/data-table/README.md` and `packages/data-table/docs/*.md`\n- `packages/react-virtuoso/README.md` and `packages/react-virtuoso/docs/*.md`\n- `packages/message-list/README.md` and `packages/message-list/docs/*.md`\n- `packages/masonry/README.md`\n- `packages/gurx/README.md`\n\nAfter product docs changes:\n\n- run `pnpm lint:md` from the repo root\n- if docs-site content or registry code changed, run `pnpm --filter @virtuoso.dev/virtuoso.dev lint`\n\n## Validation Guidance\n\nChoose the narrowest validation that matches the change:\n\n- `packages/data-table` code changes: start with `pnpm check && pnpm test` in `packages/data-table`\n- `packages/react-virtuoso` code changes: run `pnpm lint && pnpm typecheck && pnpm test`, add `pnpm e2e` when behavior changes\n- docs-only markdown changes: run `pnpm lint:md`\n- docs site or registry changes: run `pnpm --filter @virtuoso.dev/virtuoso.dev lint`\n- broad cross-package changes: run root `pnpm typecheck && pnpm lint && pnpm test`\n\n## Architecture Notes\n\n- `packages/react-virtuoso` uses the custom `urx` stream/state system under `packages/react-virtuoso/src/urx`. If you touch its internals, follow existing `*System.ts` and `react-urx/` patterns.\n- `packages/data-table` is a separate package built on the `reactive-engine-*` workspaces. When working there, prefer matching existing engine/cell/stream patterns instead of borrowing directly from `react-virtuoso` internals.\n\n## Git Hooks\n\nThis repo uses `lefthook`. Pre-commit hooks format and lint staged files. If you need to skip them for a WIP commit:\n\n```bash\nLEFTHOOK=0 git commit -m \"WIP: ...\"\n```\n","category":"root","tokens":1905}]}