AlexandrAI AGENTS.md
agents-md

HTML Editor Interaction Overlay Agent Guide

Module-specific agent guide for drag, resize, selection overlays, and multi-select geometry.

AGENTS.md

Guidance for coding agents working on HTML Editor Interaction Overlay in the html-editor project.

Project overview

This guide covers the interaction layer connecting Canvas, SelectionOverlay, and interactionReducer. User gestures should update temporary overlay state first, then commit a command when the gesture ends. This keeps pointer motion responsive and keeps undo history clean.

Primary source files

  • src/renderer/src/interaction/interaction.ts owns the reducer for idle, dragging, resizing, and text editing states.
  • src/renderer/src/ui/Canvas.tsx wires pointer events, keyboard shortcuts, overlay offsets, command commits, and multi-selection.
  • src/renderer/src/ui/SelectionOverlay.tsx displays resize handles and drag affordances.
  • src/renderer/src/state/align.ts supplies pure alignment and distribution helpers.

Setup commands

npm install npm test npm run typecheck npm run build

For scoped validation, run npm test -- src/renderer/src/interaction/interaction.test.ts src/renderer/src/state/align.test.ts when available.

Change rules

  • Convert viewport pointer deltas into document coordinates using the same zoom constant used by Canvas.
  • Commit drag and resize as a single box.set command on pointer release.
  • Use Escape to cancel active drag or resize without committing a command.
  • Keep overlay position based on measured iframe coordinates plus model coordinates; do not assume a single slide at the document origin.
  • Use batch commands when aligning or distributing more than one selected box.

Keyboard behavior

Canvas owns global undo, redo, duplicate, and delete shortcuts when no text, cell, or block edit is active. Do not let global shortcuts fire while contentEditable editing is in progress.

Testing

Test reducer states without React first. Then test Canvas integration for pointer down, move, release, Escape cancel, duplicate, delete, and multi-select alignment. Confirm min width and height clamps remain stable during resize.

PR checklist

  • Gesture preview and command commit are separate.
  • Undo history receives one command per completed gesture.
  • Editing states suppress global shortcuts.
  • Full npm test and npm run typecheck pass.