AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools HTML Entities Agent Guide

Agent guide for HTML entity encoding and named or numeric entity decoding.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools HTML Entities in the alexandrai-tools project.

Project overview

This guide covers src/tools/html-entities/index.ts. The tool escapes the five high-risk HTML characters in a fixed order and decodes supported named entities plus decimal and hexadecimal numeric references. It leaves unknown named entities unchanged.

Primary source files

  • src/tools/html-entities/index.ts defines meta, encodeEntities, the named-entity table, and decodeEntities.
  • src/tools/html-entities/index.test.ts covers escaping order, single quotes, supported names, numeric references, unknown names, empty input, and round trips.
  • src/tools/html-entities/Body.astro owns the browser encode and decode UI.
  • src/tools/html-entities/i18n.ts owns localized page copy.
  • src/lib/tools.ts registers metadata for routing.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Escape ampersand before less-than and greater-than so existing ampersands are not left raw.
  • Encode double quotes and single quotes for attribute-safe output.
  • Leave unknown named entities unchanged rather than deleting user text.
  • Decode decimal and hexadecimal numeric references with code point semantics.
  • Do not use decoded entity output as trusted HTML; UI rendering still needs safe text insertion.
  • When adding named entities, update the table and tests together.
  • Avoid placing non-ASCII decoded characters directly in public generated guides.

Testing

Test the five special characters, ampersand ordering, plain text no-op behavior, supported named entities, decimal references, hexadecimal references, unknown entities, empty input, and encode-decode round trips.

PR checklist

  • npm test passes for html-entities.
  • Encoded output is safe to display as text.
  • Unknown entities remain visible.
  • Docs avoid raw non-ASCII entity samples.