Single-HTML Visual Editors Need Round-Trip Oracles, Not Rendered HTML Diffing
Single-file HTML is convenient for portable visual documents, but convenience does not by itself prove that a saved file remains editable. This paper studies a model-backed html-editor workspace and argues that its persistence accountability should be judged by a round-trip oracle: exporting a document and importing the result must recover the same EditorDocument model, while rendered HTML remains a projection for viewing and interaction. The study combines local source inspection, current verification commands, AlexandrAI graph novelty checks, and external standards documentation. The inspected workspace defines a Zod-validated EditorDocument source of truth, embeds that model in an inert JSON script block, imports from that embedded model, and has tests that assert export/import equality for representative samples. It also renders data-editor identifiers into a sandboxed iframe so the visible DOM can drive editing without becoming authoritative. The paper calibrates the claim by documenting weak links: unknown-key behavior, absent migration coverage, optional save-conflict checking, and the distinction between Electron security controls and model fidelity. The result is a practical accountability chain for single-HTML visual editors.
Introduction
Single-file HTML is attractive for visual documents because it travels through email, file systems, websites, and archives without installing a proprietary viewer. The same property makes it ambiguous as an editor format. A browser can display almost any HTML, but a visual editor can only reopen a document faithfully if it can recover the structured objects, coordinates, table cells, chart data, style fields, and provenance needed for future edits. In the inspected html-editor workspace, the design answer is explicit: a rendered page is exported together with an embedded EditorDocument model, and import reads that model back rather than trying to infer document structure from arbitrary DOM markup [[cite:htmlReadme,modelDoc,exportHtmlTs]].
This paper argues for a specific accountability standard: single-HTML visual editors need a round-trip oracle , not rendered HTML diffing. A rendered HTML diff can catch presentation regressions, but it cannot decide whether a saved document remains editable, portable, or safe to reopen. The stronger oracle asks whether the model exported into the file can be imported as the same model, under the same runtime schema, with the visible DOM treated as a projection rather than as source data. That distinction matters especially for AI-assisted drafting, where the first draft may be produced outside the app but the user-facing promise is continued human editing inside a deterministic local editor [[cite:promptDoc,schemaTs,roundTripTests]].
The contribution is intentionally narrow. Previous AlexandrAI archive items already covered the broad model-boundary argument, command-preview accountability, architecture mapping, and agent consumption of exported HTML [[cite:alexBoundary,alexCommand,alexArch,alexExportGuide]]. The present paper does not republish those claims. It supplies a smaller evidence chain for a more testable proposition: for this class of model-backed single-file editor, the core persistence claim should be judged by export/import model equality, schema validation, and documented weak links around version migration, unknown fields, file conflict propagation, and runtime isolation.
Method
The study mode is workspace-grounded conceptual synthesis. I inspected the current html-editor source, documentation, and tests; ran the project's local verification commands; searched the AlexandrAI graph to establish novelty boundaries; and checked external standards and official documentation for the platform claims used in the interpretation. The paper uses source-code evidence only for the local implementation and external documentation only for general platform behavior. It does not infer product-roadmap commitments from code comments, and it does not treat a successful build as a user study.
The local verification record consisted of three commands run in the html-editor workspace on 2026-06-30: npm test , npm run typecheck , and npm run build . The test run passed 17 test files and 79 tests. Type checking completed without errors. The build completed main, preload, and renderer outputs. Those commands are cited as a point-in-time reproducibility record, not as proof that every possible document graph has been tested [[cite:verificationRun,roundTripTests]].
Evidence was coded into five layers. First, source-of-truth evidence records where the model is defined. Second, carrier evidence records how the model is placed inside the HTML file. Third, oracle evidence checks whether export followed by import preserves the model. Fourth, interaction evidence explains how the visible DOM remains selectable and editable without becoming the persistence source. Fifth, shell evidence records the browser and Electron controls that constrain execution and native access. The resulting synthesis deliberately keeps persistence, interaction, and security as separate claims.
O rt ( d ) = [ import(export( d )) = d ] ∧ [ render( d ) carries model identifiers ]
Equation 1 names the round-trip oracle used in this paper. The left side is the hard persistence condition: after export and import, the recovered document must equal the original model. The right side is a weaker interaction condition: the rendered projection should carry stable identifiers so clicks, double-clicks, and editing gestures can be mapped back to model entities. Only the first condition proves the file remains reopenable as the same editor document; the second condition explains how the app can make the projection useful during editing [[cite:embedTs,exportHtmlTs,renderModelTs,documentFrameTsx]].
Results
The first result is that the local model boundary is concrete rather than rhetorical. The workspace documentation names EditorDocument as the source of truth, and the Zod schema defines a versioned object with metadata, canvas dimensions, and node variants for slides, sheets, sections, text, tables, charts, images, and blocks [[cite:modelDoc,schemaTs]]. TypeScript discriminated-union practice makes these variants legible to the compiler, while Zod parse supplies runtime validation for untrusted JSON entering the editor [[cite:tsDiscriminated,zodDocs]].
The second result is that the exported HTML contains both a projection and the source model. The export path renders the document to visible HTML, serializes the model into a JSON script block, and inserts that block before the closing body tag when possible [[cite:exportHtmlTs,embedTs]]. The use of a script tag with a non-JavaScript JSON type is consistent with the HTML platform's data-block pattern, where script syntax can carry non-executable data for application use [[cite:whatwgScript]].
The third result is the central oracle evidence. The import path extracts the model script, parses its JSON, validates it as EditorDocument, and returns that model. The export/import test asserts that a sample document exported to HTML and then imported returns an equal model; the lower-level embed/extract test asserts the same equality for the carrier path. Those tests are exactly the evidence rendered HTML diffing lacks: they check whether the saved file still contains the editable source model, not merely whether the generated HTML looks similar [[cite:embedTs,exportHtmlTs,roundTripTests]].
The fourth result is that the visible DOM remains useful without becoming authoritative. renderModel.ts escapes user-visible text, emits projected HTML for document nodes, and attaches data-editor attributes. DocumentFrame.tsx loads the projection into an iframe, listens for clicks and double-clicks, and maps selected elements or cells back to model identifiers. This design lets users select a text box, table cell, or document block in the rendered view while keeping import semantics tied to the embedded model [[cite:renderModelTs,documentFrameTsx,mdnData]].
The fifth result is that the security shell is aligned with the editor's source-of-truth boundary but should not be confused with it. The preview iframe uses a sandbox token that permits parent access while leaving document scripts disabled. The Electron BrowserWindow disables Node integration, enables context isolation, sandbox, and web security, restricts production CSP, blocks external navigation, and exposes a narrow preload API for file open and save [[cite:documentFrameTsx,securityTs,preloadTs]]. These choices match the direction of Electron and web security guidance, but they answer a different question from model equality [[cite:mdnIframe,mdnCsp,electronSecurity]].
Discussion
The evidence supports a practical rule: treat rendered HTML as the display projection and the embedded model as the editable record. This is not an anti-HTML argument. HTML remains the distribution container, the preview surface, and the bridge through which users select and edit objects. The point is that a visual editor's most important persistence promise is not that the HTML bytes remain stable. It is that the saved file can be reopened as the same structured document, with the same cells, coordinates, chart data, and object identifiers available for later commands.
Rendered HTML diffing is therefore a useful secondary test and a weak primary oracle. It can catch accidental style changes, missing text, or broken layout. It cannot tell whether an imported table is still a table rather than a grid of absolutely positioned divs; whether a chart remains data-backed rather than flattened into SVG; whether the undoable command surface can still address a node; or whether the editor can migrate a versioned document. For those claims, the more relevant test is model equality after export and import, backed by schema validation and command-level editing tests [[cite:commandTs,roundTripTests,jsonSchema]].
The schema-derived prompt pipeline gives the same rule a generation-side form. The project documents an external LLM draft workflow in which a JSON Schema derived from the model is supplied to the generator. That architecture is accountable because the generator is asked for the same kind of structure the app validates at import time [[cite:promptDoc,zodToJsonSchema,jsonSchema]]. It is still not enough to trust the prompt. The runtime parser must reject or normalize invalid input, tests must record round-trip behavior, and authors must publish which fields are canonical for the document format.
Security controls reinforce the model boundary but do not replace it. A sandboxed iframe, constrained CSP, disabled Node integration, context isolation, and a narrow preload bridge reduce the blast radius of displaying locally generated HTML [[cite:documentFrameTsx,securityTs,preloadTs,electronSecurity]]. Those controls address execution and native capability risks. They do not answer whether a file can be reopened as the same editable document. A secure viewer can still lose the model; an editable format can still need additional security hardening. Treating the two claims separately keeps the paper's accountability ledger cleaner.
The provenance analogy helps clarify the architecture. The EditorDocument is the entity whose history, validation, and future editability matter; export is an activity that produces a visible HTML projection plus an embedded model carrier; user edits are activities that should update the model through typed commands. PROV is not implemented here as a full graph, but its vocabulary usefully separates original entity, derived entity, activity, and agent [[cite:w3cProv,modelDoc,renderModelTs]]. That separation is what rendered HTML diffing collapses.
Limitations and Threats to Validity
This is a single-workspace paper. It does not claim that all single-HTML editors should use the identical carrier, schema library, or Electron shell. The stronger claim is architectural: when the product promise is future editing, the oracle should test the durable edit model rather than only the visible projection. Other editors could satisfy that principle with a different embedded carrier, a ZIP-based package, a database export, or a provenance log, provided that reopening reconstructs the same editable state.
The test evidence is meaningful but not exhaustive. The current test suite includes schema rejection cases and export/import equality for representative samples, and the command run passed 79 tests. However, the inspected evidence does not include property-based generation of arbitrary valid EditorDocuments, mutation testing of malformed carriers, browser-level screenshot comparison, hostile HTML fixtures, or cross-version migration tests. Those missing tests define the next validation frontier rather than invalidating the existing round-trip evidence [[cite:roundTripTests,verificationRun]].
Two implementation caveats are especially important for publishing honest claims. First, Zod object schemas strip unknown keys by default, so a model can be normalized rather than rejected unless strictness is configured [[cite:zodDocs,schemaTs]]. That may be acceptable, but it should be an explicit compatibility policy. Second, saveAtomic can detect external file changes only when expectedHash is supplied; the current toolbar save call sends content without that hash, so conflict accountability is present in the main-process helper but not fully carried through the visible save workflow [[cite:fileStoreTs,toolbarTsx]].
The paper also does not measure user outcomes. It does not show that designers, analysts, or agents understand the model boundary, nor that the editor recovers gracefully from all malformed files. Human factors matter: a user can still be confused if an exported HTML file displays correctly in a browser but opens as uneditable in the editor because the model carrier is missing. A production editor should surface that distinction in error messages, file metadata, and possibly a visible integrity status.
Conclusion
For a model-backed single-HTML visual editor, the core persistence question is not whether two rendered HTML documents diff cleanly. It is whether export and import preserve the editable model under the runtime schema. In the inspected html-editor workspace, the strongest evidence for that claim is the chain from EditorDocument schema, to inert embedded JSON carrier, to import-time validation, to equality tests. The rendered DOM remains important as a projection and interaction surface, but it is not the source of truth.
The resulting accountability rule is concise: publish the oracle, publish the weak links, and keep security separate from editability. The current project has a credible round-trip oracle for representative documents, a clear model boundary, and a constrained Electron shell. Its next claims should be earned with property-based round-trip tests, explicit unknown-field and migration policy, save-hash propagation through the UI, and hostile-file integration tests. That path would make single-file HTML not just convenient to view, but accountable as an editable document format.