Web Editor Playground
Relevant source files
The following files were used as context for generating this wiki page:
The Web Editor Playground serves as the central development UI and integration harness for the chemd project. It provides a real-time, interactive environment where users can author Markdown-based chemical documents and immediately visualize the rendered results. The playground is designed as a "workbench" that integrates core language parsing, semantic resolution, and multi-format rendering into a single user interface.
Sources: chemd-v0.1-architecture.md:3.6, apps/web/src/app/page.tsx:112-115
Within the overall architecture, the playground acts as the primary consumer of the @chemd/compiler and various renderer packages. It demonstrates the project's core philosophy: maintaining a plain Markdown source of truth that drives human-readable previews, machine-readable JSON, and professional export formats like DOCX.
Sources: chemd-v0.1-architecture.md:1, apps/web/src/app/page.tsx:162-167
Architecture and Design
The playground follows a "pipeline architecture" where user input is processed through multiple stages before being displayed. The main application state is managed in a React-based workbench that coordinates the editor, a compilation scheduler, and multiple preview panes.
Sources: chemd-v0.1-architecture.md:5, apps/web/src/app/page.tsx:43-52
System Overview Diagram
The following diagram illustrates how the Playground integrates the various layers of the chemd system, moving from source input to final output rendering.
Key Components
The playground is structured into three primary visual areas:
- Overview/Topbar: Displays document metadata (title, date), compilation status (sync status, diagnostics count), and the active Render Profile.
- Editor Panel: A text-editing interface where users write Markdown and
chemdblocks. It includes specialized tools like OCR import and integrated status messaging. - Preview Panel: A multi-tabbed output area showing the live HTML preview, the normalized JSON AST, and DOCX export options.
Sources: apps/web/src/app/page.tsx:120-185, apps/web/tests/page.test.tsx:10-25
| Component | Responsibility | Relevant Files |
|---|---|---|
EditorShell | Handles text input and integration with OCR/Structure editors. | apps/web/src/app/page.tsx:173-181 |
PreviewShell | Manages tabs for HTML, JSON, and DOCX outputs. | apps/web/src/app/page.tsx:182-211 |
KetcherDialog | Provides a graphical molecule editor for structure updates. | apps/web/src/app/page.tsx:213-255 |
CompileScheduler | Throttles and manages the asynchronous compilation pipeline. | apps/web/src/app/page.tsx:82-95 |
Data Flow and Interaction
The Playground manages data flow through a "reactive loop." As the user types in the EditorShell, the deferredSource value triggers a compilation cycle via the scheduler. This ensures the UI remains responsive even during complex chemical rendering tasks.
Sources: apps/web/src/app/page.tsx:82-95
Interactive Structure Editing
A unique feature of the playground is the ability to launch a graphical structure editor (Ketcher) directly from the preview pane. When a user clicks to edit a molecule, the following sequence occurs:
Compilation and Diagnostics
The compileChemd function is the core of the playground's logic. It returns a CompileResult object that contains the processed document and any issues found during the various parsing stages.
Sources: apps/web/src/app/page.tsx:41-41
Diagnostic Severity
The playground provides visual feedback on document health through a status pill and a diagnostics list.
- Success (Clean Compile): No errors or warnings in the AST.
- Warning: Issues such as
W_UNRESOLVED_REFERENCEorW_UNKNOWN_FIELD. - Error: Critical issues like
E_DUPLICATE_IDorE_MISSING_REQUIRED_FIELD.
Sources: chemd-v0.1-architecture.md:15.2, apps/web/src/app/page.tsx:102-106
Example Compilation Output (JSON)
The JSON tab in the preview pane displays the normalized AST, ensuring that chemical objects are represented as structured data rather than loose text.
{
"type": "molecule",
"id": "mol-ethanol",
"smiles": "CCO",
"name": "ethanol",
"role": "reactant"
}
Sources: chemd-v0.1-spec.md:23.2
Features and Capabilities
The playground serves as a showcase for the "Semantic vs. Rendering Style" architectural boundary. Users can switch the render_profile in the YAML frontmatter (e.g., from eln-default to publication-acs) to see visual changes in bond widths or font sizes without modifying the underlying chemical data.
Sources: chemd-v0.1-spec.md:5, apps/web/src/app/page.tsx:143-146
- Real-time Preview: Synchronous rendering of KaTeX equations (
:chem[...]) and RDKit-backed molecule/reaction SVGs. - OCR Integration: Ability to import or paste images of chemical structures, which are converted to SMILES and inserted into the editor.
- Template Expansion: Automatic resolution and expansion of
:::templateand:::useblocks into standard Markdown and chemical AST nodes. - DOCX Handoff: Generation of a "DOCX Bridge" payload intended for downstream processing by tools like Pandoc.
Sources: apps/web/src/app/page.tsx:120-125, apps/web/src/app/page.tsx:183-185, chemd-v0.1-architecture.md:3.3-3.5, packages/renderer-html/src/index.ts:1078-1090
Conclusion
The Web Editor Playground is the essential interface for the chemd ecosystem. By strictly separating semantic chemical content from rendering styles and providing a robust compilation pipeline, it enables a workflow where chemical documentation is both human-readable and machine-actionable. It serves as both a functional ELN authoring tool and a diagnostic suite for the project's underlying packages.
Sources: chemd-v0.1-architecture.md:25, apps/web/src/app/page.tsx:135-138