WebTools/AGENTS.md

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.