AlexandrAI AGENTS.md
agents-md

HTML Editor Export and Embed Agent Guide

Module-specific agent guide for single-HTML export, inert model embedding, and import validation.

AGENTS.md

Guidance for coding agents working on HTML Editor Export and Embed in the html-editor project.

Project overview

This guide covers the single-file export and import boundary. The app renders the visual document to HTML and embeds the source model as inert JSON in a fixed script tag. Import restores only by extracting that script and validating it through the Zod schema.

Primary source files

  • src/renderer/src/render/exportHtml.ts combines rendered HTML with the embedded model script.
  • src/model/embed.ts owns MODEL_SCRIPT_ID, serializeModelToScript, and extractModelFromHtml.
  • src/renderer/src/render/renderModel.ts creates the visible exported document.
  • src/model/schema.ts validates imported model data.
  • src/main/fileStore.ts saves and loads the HTML string through Electron IPC.

Setup commands

npm install npm test npm run typecheck npm run build

For scoped validation, run npm test -- src/model/embed.test.ts src/renderer/src/render/exportHtml.test.ts when available.

Change rules

  • Keep the model script type as application/json; it is storage data, not executable code.
  • Keep the script id stable unless an importer migration supports old and new ids.
  • Preserve schema validation on import and surface invalid files as import errors.
  • Export visible HTML and model JSON together so a saved document can be reopened for editing.
  • Do not add machine-specific paths, secrets, or local endpoints to exported sample documents.

Import behavior

extractModelFromHtml searches for the fixed model script, parses its JSON, and calls editorDocument.parse. Missing script tags and invalid model data should fail closed. A plain HTML document without the model script is not an editable project file.

Testing

Test export with body insertion, fallback append when no body tag exists, successful round trip, missing model script, malformed JSON, and schema-invalid JSON.

PR checklist

  • Export remains a single self-contained HTML string.
  • Import rejects documents outside the editor model contract.
  • Embedded JSON remains inert.
  • Full npm test and npm run typecheck pass.