armand1m · armand1m · Apr 8, 2026 · Apr 8, 2026 · Apr 8, 2026 · Apr 8, 2026
diff --git a/.eslintrc.js b/.eslintrc.js
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -1,41 +1,33 @@
-name: CI
-on: [push]
-jobs:
-  build:
-    name: Build, lint, and test on Node ${{ matrix.node }} and ${{ matrix.os }}
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
 
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        node: ['12.x', '14.x']
-        os: [ubuntu-latest, macOS-latest]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout repo
-        uses: actions/checkout@v2
+      - name: Checkout
+        uses: actions/checkout@v5
 
-      - name: Use Node ${{ matrix.node }}
-        uses: actions/setup-node@v1
+      - name: Setup Node
+        uses: actions/setup-node@v6
         with:
-          node-version: ${{ matrix.node }}
-
-      - name: Install deps and build (with cache)
-        uses: bahmutov/npm-install@v1
+          node-version: 20
+          cache: npm
 
-      - name: Lint
-        run: yarn lint
+      - name: Install dependencies
+        run: npm install
 
-      - name: Test
-        run: yarn test --ci --coverage --maxWorkers=2
+      - name: Validate library
+        run: npm run validate
 
-      - name: Build
-        run: yarn build
+      - name: Install example dependencies
+        run: npm --prefix example install
 
-      - name: Pack Inspect
-        run: yarn pack:inspect
-
-      - name: Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: yarn semantic-release
+      - name: Build example
+        run: npm run example:build
diff --git a/.github/workflows/size.yml b/.github/workflows/size.yml
diff --git a/.prettierrc b/.prettierrc
@@ -1,5 +1,4 @@
 {
-  "jsxBracketSameLine": true,
   "printWidth": 70,
   "singleQuote": true,
   "trailingComma": "es5"

diff --git a/.storybook/main.js b/.storybook/main.js
diff --git a/.storybook/preview.js b/.storybook/preview.js
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,41 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`src/` contains the published library. The low-level grouped-filter engine lives in `src/core.ts` and `src/hooks/useQueryFilters.ts`, while the recommended consumer API lives in `src/schema.ts` and `src/hooks/useFilterBuilder.ts`. Keep `src/index.tsx` focused on stable public exports. The demo app in `example/src/` should always reflect the recommended integration path, not internal-only APIs. Build output goes to `dist/` and is generated.
+
+## Build, Test, and Development Commands
+
+Use `npm` for local work.
+
+- `npm run dev`: watch the library build with `tsup`.
+- `npm run build`: create ESM/CJS bundles and declarations in `dist/`.
+- `npm run test`: run Vitest with coverage.
+- `npm run lint`: run ESLint.
+- `npm run typecheck`: run TypeScript for both library and example.
+- `npm run example`: start the Vite example app.
+- `npm run validate`: run formatting checks, lint, typecheck, tests, and build.
+
+## Design & Architecture Principles
+
+Keep the library headless, but optimize for low-friction usage. The primary API should hide tree complexity behind schema helpers and typed controllers so developers do not need to manually traverse nodes, juggle ids, or learn tree internals before they can ship a UI. Favor a schema-first builder facade for onboarding and keep raw tree utilities as an advanced layer.
+
+Type safety is non-negotiable. New APIs should improve autocomplete quality, preserve typed field keys and value shapes, and avoid consumer-side casts such as `as Binding` or `as OperationType`. Do not require manual coercion like `Boolean()`, `String()`, or `Number()` in example or recommended consumer code; prefer typed controller props and native-friendly adapters instead.
+
+Recursive groups are a core capability, but the mental model should stay simple. Group combinators belong to groups, not to each row. When adding abstractions, prefer controller methods such as `addCondition()`, `addGroup()`, `setField()`, and `setValue()` over generic tree mutation helpers.
+
+## Coding Style & Naming Conventions
+
+Use TypeScript, React, 2-space indentation, LF line endings, and single quotes. Follow Prettier and `eslint.config.js`. Use named exports. Keep public API names intention-revealing and beginner-friendly. Reserve terse or highly generic helpers for internal code only if they are not part of the recommended surface.
+
+## Example App Guidelines
+
+The example app is a DX artifact, not just a demo. It should show the easiest correct integration with native elements first, use the builder facade instead of low-level hooks, and stay compact and desktop-friendly. Prefer icon-assisted controls, realistic grouped-filter flows, and immediate starter state over empty onboarding screens. If consumer code in the example feels verbose or needs casts/parsing, treat that as a library DX bug.
+
+## Testing Guidelines
+
+Tests use Vitest and `@testing-library/react`. Add tests next to implementation as `*.test.tsx`. Cover recursive behavior, controlled/uncontrolled state, controller helpers, schema inference, and any API intended for direct consumer use. Changes to the recommended DX path should include example-facing or facade-facing tests, not only low-level tree tests.
+
+## Commit & Pull Request Guidelines
+
+Follow Conventional Commits such as `feat:`, `fix:`, and `test:`. Keep commits scoped to a coherent behavior change. Pull requests should explain user-facing DX impact, especially when changing the public API, example integration path, or type surface. Call out breaking changes and migration implications explicitly.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,177 +1,33 @@
+# Contributing
 
-## Commands
+## Local setup
 
-TSDX scaffolds your new library inside `/src`, and also sets up a [Parcel-based](https://parceljs.org) playground for it inside `/example`.
-
-The recommended workflow is to run TSDX in one terminal:
+This project targets Node 20+ and modern React tooling.
 
 ```bash
-npm start # or yarn start
+npm install
+npm run validate
 ```
 
-This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`.
-
-Then run either Storybook or the example playground:
-
-### Storybook
-
-Run inside another terminal:
-
-```bash
-yarn storybook
-```
-
-This loads the stories from `./stories`.
-
-> NOTE: Stories should reference the components as if using the library, similar to the example playground. This means importing from the root project directory. This has been aliased in the tsconfig and the storybook webpack config as a helper.
-
-### Example
-
-Then run the example inside another:
-
-```bash
-cd example
-npm i # or yarn to install dependencies
-npm start # or yarn start
-```
-
-The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**, we use [Parcel's aliasing](https://parceljs.org/module_resolution.html#aliases).
-
-To do a one-off build, use `npm run build` or `yarn build`.
-
-To run tests, use `npm test` or `yarn test`.
-
-## Configuration
-
-Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly.
-
-### Jest
-
-Jest tests are set up to run with `npm test` or `yarn test`.
-
-### Bundle analysis
-
-Calculates the real cost of your library using [size-limit](https://github.com/ai/size-limit) with `npm run size` and visulize it with `npm run analyze`.
-
-#### Setup Files
-
-This is the folder structure we set up for you:
-
-```txt
-/example
-  index.html
-  index.tsx       # test your component here in a demo app
-  package.json
-  tsconfig.json
-/src
-  index.tsx       # EDIT THIS
-/test
-  blah.test.tsx   # EDIT THIS
-/stories
-  Thing.stories.tsx # EDIT THIS
-/.storybook
-  main.js
-  preview.js
-.gitignore
-package.json
-README.md         # EDIT THIS
-tsconfig.json
-```
-
-#### React Testing Library
-
-We do not set up `react-testing-library` for you yet, we welcome contributions and documentation on this.
-
-### Rollup
-
-TSDX uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details.
-
-### TypeScript
-
-`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `react` for `jsx`. Adjust according to your needs.
+## Key commands
 
-## Continuous Integration
+- `npm run dev`: watch the library build with `tsup`
+- `npm run build`: create ESM/CJS bundles and declarations in `dist/`
+- `npm run typecheck`: run TypeScript in strict mode
+- `npm run test`: run Vitest with coverage
+- `npm run lint`: run ESLint
+- `npm run example`: start the Vite example app
 
-### GitHub Actions
+## Contribution guidelines
 
-Two actions are added by default:
+- Keep the published package headless. UI libraries belong in examples, not in the public runtime surface.
+- Prefer pure helpers plus thin React glue. Derived behavior should be testable without DOM-specific handlers.
+- Add or update tests for every behavioral change, especially around field typing, operation availability, and filter normalization.
+- Use Conventional Commits such as `feat:`, `fix:`, or `refactor:`.
 
-- `main` which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix
-- `size` which comments cost comparison of your library on every pull request using [size-limit](https://github.com/ai/size-limit)
-
-## Optimizations
-
-Please see the main `tsdx` [optimizations docs](https://github.com/palmerhq/tsdx#optimizations). In particular, know that you can take advantage of development-only optimizations:
-
-```js
-// ./types/index.d.ts
-declare var __DEV__: boolean;
-
-// inside your code...
-if (__DEV__) {
-  console.log('foo');
-}
-```
-
-You can also choose to install and use [invariant](https://github.com/palmerhq/tsdx#invariant) and [warning](https://github.com/palmerhq/tsdx#warning) functions.
-
-## Module Formats
-
-CJS, ESModules, and UMD module formats are supported.
-
-The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found.
-
-## Deploying the Example Playground
-
-The Playground is just a simple [Parcel](https://parceljs.org) app, you can deploy it anywhere you would normally deploy that. Here are some guidelines for **manually** deploying with the Netlify CLI (`npm i -g netlify-cli`):
-
-```bash
-cd example # if not already in the example folder
-npm run build # builds to dist
-netlify deploy # deploy the dist folder
-```
-
-Alternatively, if you already have a git repo connected, you can set up continuous deployment with Netlify:
-
-```bash
-netlify init
-# build command: yarn build && cd example && yarn && yarn build
-# directory to deploy: example/dist
-# pick yes for netlify.toml
-```
-
-## Named Exports
-
-Per Palmer Group guidelines, [always use named exports.](https://github.com/palmerhq/typescript#exports) Code split inside your React app instead of your React library.
-
-## Including Styles
-
-There are many ways to ship styles, including with CSS-in-JS. TSDX has no opinion on this, configure how you like.
-
-For vanilla CSS, you can include it at the root directory and add it to the `files` section in your `package.json`, so that it can be imported separately by your users and run through their bundler's loader.
-
-## Publishing to NPM
-
-This project has `semantic-release` setup, so there is no manual publish.
-
-Stick to the conventional commit standard when contributing with changes. Your PR will be squashed as well.
-This is used to bump according to semantic versioning, setup the release on github and to write changes to the changelog.
-
-## Usage with Lerna
-
-When creating a new package with TSDX within a project set up with Lerna, you might encounter a `Cannot resolve dependency` error when trying to run the `example` project. To fix that you will need to make changes to the `package.json` file _inside the `example` directory_.
-
-The problem is that due to the nature of how dependencies are installed in Lerna projects, the aliases in the example project's `package.json` might not point to the right place, as those dependencies might have been installed in the root of your Lerna project.
-
-Change the `alias` to point to where those packages are actually installed. This depends on the directory structure of your Lerna project, so the actual path might be different from the diff below.
-
-```diff
-   "alias": {
--    "react": "../node_modules/react",
--    "react-dom": "../node_modules/react-dom"
-+    "react": "../../../node_modules/react",
-+    "react-dom": "../../../node_modules/react-dom"
-   },
-```
+## Pull requests
 
-An alternative to fixing this problem would be to remove aliases altogether and define the dependencies referenced as aliases as dev dependencies instead. [However, that might cause other problems.](https://github.com/palmerhq/tsdx/issues/64)
+- Describe the behavior change clearly.
+- Link the related issue when relevant.
+- Include screenshots or short recordings for example-app UI changes.
+- Call out any breaking API changes in the PR description and README updates.