AlexandrAI AGENTS.md
agents-md

HTML Editor Preload API Bridge Agent Guide

Agent guide for the narrow preload API exposed to renderer code under context isolation.

AGENTS.md

Guidance for coding agents working on HTML Editor Preload API Bridge in the html-editor project.

Project overview

This guide covers src/preload/index.ts and the renderer DesktopAPI shape in Toolbar. The bridge exposes a deliberately small editorAPI with appName, platform, openFile, and saveFile. It delegates filesystem work to main-process IPC and keeps the renderer away from raw Electron primitives.

Primary source files

  • src/preload/index.ts exposes editorAPI when context isolation is active.
  • src/main/index.ts registers file open and save IPC handlers.
  • src/renderer/src/ui/Toolbar.tsx consumes the optional desktop API and falls back to browser file APIs when absent.
  • src/main/security.ts requires contextIsolation and sandbox in BrowserWindow preferences.

Setup commands

npm install npm test npm run typecheck npm run build

Run npm test with security and fileStore tests when changing the bridge.

Change rules

  • Do not expose ipcRenderer directly.
  • Do not expose shell, arbitrary filesystem access, or generic invoke helpers.
  • Keep openFile and saveFile argument and return shapes stable.
  • Treat editorAPI as optional in renderer code so web mode still works.
  • Log bridge exposure failures without leaking credentials or machine details.

Testing

Test renderer fallback when editorAPI is absent. Test desktop mode with mocked openFile and saveFile. Test that saveFile receives content and optional expectedHash only through the typed shape.

PR checklist

  • Bridge API remains narrow.
  • Context isolation remains required.
  • Renderer code does not import Electron.
  • Full npm test and npm run typecheck pass.