# AGENTS.md — `@yaoc1996/js-tools`

Entry point for AI coding agents. **Reading this from `node_modules/@yaoc1996/js-tools/` in a consumer app?** See [`UPGRADING.md`](./UPGRADING.md) for the upgrade workflows. **Reading this from the repo root?** See the "Working in this repo" section below.

## What this package is

`@yaoc1996/js-tools` is a multi-module utility library. The public API surface is the set of **subpath exports** declared in `package.json`:

| Subpath | Purpose |
|---|---|
| `@yaoc1996/js-tools` | Pure JS utilities (algorithms, geometry, browser, misc) |
| `@yaoc1996/js-tools/three-utils` | Three.js helpers |
| `@yaoc1996/js-tools/react-utils` | React components, hooks, state |
| `@yaoc1996/js-tools/react-three` | Three.js + React |
| `@yaoc1996/js-tools/mapbox` | Mapbox utilities |
| `@yaoc1996/js-tools/react-mapbox` | Mapbox + React |
| `@yaoc1996/js-tools/google` | Google Maps utilities |
| `@yaoc1996/js-tools/react-google` | Google Maps + React |
| `@yaoc1996/js-tools/las` | LAS point-cloud parsing |
| `@yaoc1996/js-tools/ifc` | IFC geometry |
| `@yaoc1996/js-tools/tailwind` | Tailwind preset |
| `@yaoc1996/js-tools/eslint` | ESLint plugin |
| `@yaoc1996/js-tools/workers/*` | Pre-bundled web workers (`las`, `ifc`, `mapbox`) |

Type declarations for every subpath live at `node_modules/@yaoc1996/js-tools/dist/<subpath>.d.ts` (root export = `dist/index.d.ts`). Per-symbol documentation lives at `node_modules/@yaoc1996/js-tools/docs/public/<module>/<symbol>.md` when shipped.

---

## Working in this repo (in-repo agents)

If you're editing this package and your change touches a public-facing signature, removes/renames an export, or alters runtime behavior of an exported symbol, follow [`.claude/contexts/breaking-changes.md`](./.claude/contexts/breaking-changes.md). That file also contains the **pre-publish checklist** — run through it before every `npm publish` to catch test/type drift like the 2.0.6 regression.

Summary:

1. Add a bullet under `[Unreleased] ### Breaking changes` in `CHANGELOG.md`.
2. If the migration is more than one line, create `docs/migrations/v<current>-to-v<next>.md`.
3. Where feasible, mark the old API with `@deprecated` JSDoc naming the replacement (only if you're keeping the old API around for one minor release; if you're removing it outright, skip this step).
4. The next release must be a major version bump.
5. Run the pre-publish checklist in `.claude/contexts/breaking-changes.md` before `npm publish`.
