AlexandrAI AGENTS.md
agents-md

HTML Editor EditorDocument Schema Agent Guide

Module-specific agent guide for maintaining the html-editor EditorDocument Zod schema.

AGENTS.md

Guidance for coding agents working on HTML Editor EditorDocument Schema in the html-editor project.

Project overview

This guide covers the model contract in src/model/schema.ts. The editor is built around EditorDocument version 1, a metadata object, a default canvas, and top-level slide, sheet, and section nodes. Slide children are discriminated BoxNode values for text, image, shape, chart, and table content. Sheet and table nodes share cell records with zero-based row and column indexes.

Primary source files

  • src/model/schema.ts owns the Zod schemas and exported TypeScript types.
  • src/model/command.ts depends on these shapes for edit commands and undo snapshots.
  • src/renderer/src/render/renderModel.ts consumes the parsed model to produce self-contained HTML.
  • src/model/embed.ts validates embedded model JSON by calling editorDocument.parse.

Setup commands

npm install npm test npm run typecheck npm run build

For schema-only changes, start with npm test -- src/model/schema.test.ts when that test file exists, then run the full test and typecheck commands before publishing or saving generated output.

Change rules

  • Keep kind as the discriminator for all node unions.
  • Add new visual node kinds by updating the Zod schema, TypeScript type consumers, renderer switch statements, command coverage, and property panel behavior together.
  • Preserve the version literal until an importer migration is implemented.
  • Keep generated or LLM-provided input behind editorDocument.parse; do not trust raw JSON from an exported file.
  • Treat optional style fields as an extension surface and avoid making old documents invalid without a migration path.

Testing

Cover accepted and rejected documents. Include at least one slide child, one top-level sheet, one section block, and one invalid discriminated union. If a new node kind is added, also test render output, command application, and import from embedded HTML.

Security

The schema is the first public boundary for LLM-created documents. Do not add fields that execute code, fetch remote resources, or bypass the renderer escape path. Image sources and block image sources should remain data that the renderer handles explicitly.

PR checklist

  • Zod schema and exported types are in sync.
  • Renderer and command switches are exhaustive for any new kind.
  • Import/export still validates through editorDocument.parse.
  • Full npm test and npm run typecheck pass.