AGENTS.md

Guidance for coding agents working on HTML Editor, a single-HTML Excel/PPT-style visual editor where an LLM can generate the first document and a human edits it visually.

Project Overview

The core artifact is an EditorDocument model embedded in a single HTML file. The app supports slide-like coordinate content, sheet-like cell editing, and report-section blocks. It does not call an LLM API; users bring generated HTML from their own agent workflow and then edit manually.

Main project areas:

• src/model/: schema, command/undo model, HTML embedding, prompt text, command validation, samples.
• src/renderer/src/ui/: React UI surfaces.
• src/renderer/src/render/: iframe rendering boundary.
• src/renderer/src/state/: Zustand state.
• src/renderer/src/interaction/: selection, drag, resize, and edit state machines.
• src/main and src/preload: Electron security shell.
• docs/: VISION, MODEL, PROMPT, architecture maps, and completed plans.

Setup Commands

bashnpm install
npm run dev:web
npm run dev
npm test
npm run typecheck
npm run build

Use npm run dev:web for browser preview in remote or headless environments. Use npm run dev only when an Electron display is available.

Document Model Rules

• Treat src/model/schema.ts as the source of truth for EditorDocument.
• Use command objects for mutations so undo/redo remains coherent.
• Drag and resize interactions should commit one command at the end, not flood state with intermediate commits.
• Preserve IME-safe inline text editing.
• Keep chart rendering inline and self-contained; existing bar, line, area, and pie paths are SVG-based.

Electron Boundary

• Keep sandbox, context isolation, and CSP assumptions intact.
• File open/save should go through the intended main/preload bridge.
• Avoid direct renderer access to privileged filesystem APIs.
• Do not weaken atomic save or hash-conflict handling.

Code Style

• Keep the model layer DOM-free.
• Keep renderer UI code focused on interaction state and presentation.
• Prefer existing Zod schemas, command validators, and store actions before adding new validation paths.
• Avoid speculative feature abstractions for future document node types.

Testing

Use:

bashnpm test
npm run typecheck
npm run build

For model changes, test schema validation, command application, undo/redo, and HTML embed round trips. For UI interaction changes, test selection, drag/resize commit behavior, keyboard shortcuts, and inline editing. For Electron file changes, verify both browser fallback and desktop IPC behavior where feasible.

Security And Privacy

• Treat opened HTML as untrusted input.
• Keep saved output self-contained.
• Do not add external scripts, fonts, or runtime network fetches to document output.
• Do not publish local absolute paths or machine-specific preview URLs in docs or examples.

Commit And PR Rules

• Keep model, renderer, and Electron changes separated unless one feature requires all three.
• Update docs/MODEL.md or docs/PROMPT.md when the document contract or generation prompt changes.
• Report exact verification commands and any environment limitation, especially if Electron UI could not be launched.