# Web Tools Agent Guide

Before changing this project, read `README.zh-CN.md` in full. Its architecture constraints, extension procedure, validation checklist, and release steps are authoritative.

Key rules:

- Preserve the anonymous, no-login, no-database design. Tool calculations are isolated in each browser tab; only navigation order is shared globally.
- Never send tool input, keys, text, or images to the server or a third party.
- Keep each tool independently lazy-loaded through `src/tools/registry.ts`.
- Put testable computation in `src/lib/` and cover it in `tests/`.
- Preserve the documented file, record, image, random-output, syntax-rendering, and request-size limits. Update the limits table and tests when any limit changes.
- Preserve the firmware Hash byte stream contract: sorted effective blocks without gap filling, or an 8-byte binary uint32 address/length header per block; lengths exclude headers and Big Endian is the default.
- Treat every Intel HEX address and length operation as checked uint32 arithmetic. Reject overflow, conflicting overlap, malformed control records, excessive records and excessive blocks before allocating result buffers.
- Treat asynchronous replacement and clearing as race-sensitive: stale Worker, file, image, or key-generation results must never replace current state.
- Keep IDs synchronized across `shared/tool-catalog.json`, `shared/default-navigation.json`, and `src/tools/registry.ts`.
- Use the shared UI components and existing responsive styles.
- Do not edit generated `dist/` directly; rebuild it from source.
- Do not overwrite or delete `data/navigation.json`.
- Run `npm run check` after every change. Run `npm audit --audit-level=low` before a release.
- For UI changes, verify desktop and mobile portrait layouts in a real browser.
- A release must update all version references and `CHANGELOG.md`, rebuild the delivery ZIP, and regenerate SHA-256.