AlexandrAI AGENTS.md
agents-md

HTML Editor Command History Agent Guide

Module-specific agent guide for EditCommand, applyCommand, invertCommand, and EditorHistory.

AGENTS.md

Guidance for coding agents working on HTML Editor Command History in the html-editor project.

Project overview

This guide covers src/model/command.ts. The editor represents user and model edits as small EditCommand records with before and after snapshots. The same command layer supports box geometry, text, style, cells, grids, charts, slide children, section blocks, top-level nodes, and batched multi-object operations.

Primary source files

  • src/model/command.ts owns EditCommand, applyCommand, invertCommand, and EditorHistory.
  • src/renderer/src/state/editorStore.ts holds the document and delegates all mutations to EditorHistory.
  • src/renderer/src/ui/Canvas.tsx creates commands for drag, resize, duplicate, delete, align, distribute, and inline commits.
  • src/renderer/src/ui/PropertyPanel.tsx creates commands for geometry, style, grid, chart, and section edits.

Setup commands

npm install npm test npm run typecheck npm run build

For command-layer changes, use npm test -- src/model/command.test.ts when scoped validation is available, then run the full suite and typecheck.

Change rules

  • Every command that mutates state must be invertible.
  • Store enough before data to restore the previous document without recomputing from the current tree.
  • Keep applyCommand immutable. Return new arrays and objects instead of mutating existing nodes.
  • Use batch for multi-object operations so a single alignment or distribution action undoes in one step.
  • Reset history when loading a new document from disk or import.

Testing

For every command type, test apply, invert, undo, and redo. For batch, verify reverse-order inversion. For grid and cell commands, test both top-level sheets and slide-contained tables. For remove commands, confirm the original index and payload are sufficient to reinsert the item.

Failure modes

  • A command without a full before snapshot makes undo lossy.
  • A mutable update can bypass React state expectations and make selection overlays stale.
  • A new command added to the union but not to invertCommand breaks redo safety.

PR checklist

  • New command types are handled by apply and invert switches.
  • Undo and redo state flags update through EditorHistory.
  • Multi-object UI actions use batch.
  • Full npm test and npm run typecheck pass.