AlexandrAI AGENTS.md
agents-md

HTML Editor Sandboxed DocumentFrame Agent Guide

Module-specific agent guide for the sandboxed iframe renderer and inline editing bridge.

AGENTS.md

Guidance for coding agents working on HTML Editor Sandboxed DocumentFrame in the html-editor project.

Project overview

This guide covers src/renderer/src/render/DocumentFrame.tsx and its connection to renderModelToHtml. The editor renders the current model into an iframe srcDoc and uses parent-side event handlers to select, measure, and edit generated elements. The iframe uses sandbox="allow-same-origin" and does not grant script execution.

Primary source files

  • src/renderer/src/render/DocumentFrame.tsx owns iframe mounting, click and double-click delegation, content measurement, and editable attachment.
  • src/renderer/src/render/renderModel.ts writes data-editor-id, data-editor-cell, and data-editor-block attributes consumed by the frame.
  • src/renderer/src/ui/Canvas.tsx receives selection, edit begin, edit commit, and measurement callbacks.

Setup commands

npm install npm test npm run typecheck npm run build

When scoped tests exist, run npm test -- src/renderer/src/render/DocumentFrame.test.tsx plus the render model tests. Always run the full suite before publishing.

Change rules

  • Keep generated document script execution disabled. Do not add allow-scripts to the sandbox without a separate security design and tests.
  • Parent code may inspect contentDocument because same-origin access is intentionally enabled.
  • Inline editing must respect composition events so Korean and other IME input is not committed early.
  • Commit text on blur, Escape, or Enter outside active composition; preserve Shift plus Enter behavior where supported.
  • Keep measurement based on actual iframe element rectangles so mixed slide and section documents align overlays correctly.

Renderer contract

The frame depends on stable data attributes from renderModelToHtml. If an agent changes selectors or markup, update both renderer and frame tests in the same patch. Do not infer selection from visible text.

Security

Treat iframe content as untrusted model output. Escape text in the renderer, keep event handling in React parent code, and keep the iframe free of external resource fetches unless a dedicated policy is added.

PR checklist

  • Sandbox flags remain minimal.
  • IME composition is covered in tests or manual notes.
  • Selection, cell edit, text edit, and section block edit paths still dispatch the expected callbacks.
  • Full npm test and npm run typecheck pass.