Oct 6, 2026 · @mfroehli
The product is a desktop host that opens single-file HTML documents, runs them safely and saves them in place without file pickers.
Every kind of data gets its own dedicated UX, generated on the spot for its specific purpose. An hours sheet could be edited in Excel, but Excel is overkill; a purpose-built editor is much nicer to work with. So the document brings its UX with it. Documents are generated by Claude, following a simple document specification and supported by a skill (to be defined later). A user asks for an hours sheet, a checklist or a small database, receives a document that is its own dedicated editor, opens it in the host and works with it.
Behaviour is cheap to create and replace; data is durable. The user changes the data through the document's UX, and improves the UX itself through agentic coding when it falls short. The document carries both forward: the refined behaviour and the accumulated data live on in the same file.
Guiding principles:
- The host is the product. It must be robust, safe and pleasant for any document that follows the specification, including documents nobody has seen before.
- The specification is the contract. A short, precise document spec defines what a document contains and how it talks to the host. Generated documents are only as good as this spec and the skill built on it.
- Thin, stable contract. The host API stays small, versioned and backwards compatible. Data saved today must still open in a host years from now, even if the behaviour around it is regenerated.
- Generated documents are untrusted code. Nobody reviews a generated document line by line, so the host's sandbox is the safety net.
- Data outlives behaviour. The data block is what the user cares about; behaviour can always be regenerated around it.
The existing hours-sheet.html serves as the first test fixture and as the reference example for the document specification and the skill.
Terms are defined in docs/reference/glossary.md, the single source of truth.
The single-user host (M1–M3) is a tool for one user. Team use is an explicit later goal: decisions for the single-user host must not block it, but need not deliver it. Its design was decided on 2026-10-10 (see Collaboration): a small team that trusts each other, on a team server it controls, built after M4.
As a user, I ask Claude for a simple hours sheet and receive a generated document. I double-click it, add today's work session and press Ctrl+S, so that the hours are saved into that same file without any file dialog or permission prompt.
Acceptance criteria:
- Double-clicking a document file (or dropping it on the host) opens it in the host and selects it in the document list. (M1: drag and drop and command line; M2, 2026-10-09: opens as a tab in the focused pane, selected in the tab strip and the document list; M3, 2026-10-10: double-click on an installed 0.1.0-beta.2 once EverythingApp is the default for HTML, and Open With.)
- The document renders exactly as it does in Chrome. (M1, 2026-10-06: hours sheet captured at 1100×768 @2x in headless Chrome and the host; identical layout and computed colours, apart from the Save button, status line and save hint, which the document shows only in the browser. The host capture is tagged with the display profile; converted to sRGB it matches Chrome to the pixel except text anti-aliasing.)
- Ctrl/Cmd+S and File → Save write the current data into the opened file. No dialog appears. The document shows no Save button of its own while running in the host. (M1, 2026-10-07: manual check — Cmd+S and File → Save wrote without a dialog, the dirty marker cleared, only the data block changed on disk; no Save button in the host.)
- After saving, reopening the file shows the new rows.
- Saving changes only the data block on disk. All other bytes of the file stay identical. (From 0.2.0, the first save of a new document also writes its document id.)
- Closing a document with unsaved changes asks: Save, Don't save, Cancel. (M1, 2026-10-07: manual check — Cancel kept the window, Don't save closed without writing, Save wrote and closed.)
- A failed write leaves the original file intact and shows an error.
- Any document that conforms to the specification works in the host without host changes; the hours sheet is only the first fixture.
The single-user host proves the loop open → edit → save in place for any document that follows the specification, tested with the hours sheet as the first fixture.
It is delivered in three milestones. Each one is usable on its own; the code session plan follows M1 → M2 → M3.
M1 · Loop: open → edit → save in place, safely.
- Electron host for macOS and Windows, built on
BaseWindow+WebContentsViewfrom the start: open via dialog, command-line argument and drag-and-drop; one document per window until M2. - Host API v1 (pull model): the document answers save requests with its data and signals changes; the host owns saving and the dirty state.
- Atomic writes plus a version store: before every write the host keeps the previous file in a central store in the app data folder (last N saves plus one per day). Nothing but the short-lived
.tmpis ever written next to a document. - External-change detection: watch the open file, react per section (reload on behaviour change, never silently overwrite a changed data block).
- Sandboxed, offline document execution.
- Conformance check on open: refuse every file that breaks the specification (frame, sections, kit, data block, line endings, API version). The error lists the violations with a "Copy report" button (for an agent to repair) and points to opening the file in Chrome, where the fallback still works.
- Kit: recognition of published kits by hash (the "Update kit" command follows in M2).
- Document specification v1 as a standalone file (
docs/document-spec.md), written so that a skill can follow it later. - Hours sheet adapted to the specification as the first fixture.
M2 · Workspace: several documents in one window, with host UI that no document can imitate. Design decided on 2026-10-07; plan in docs/plans/m2-workspace.md.
- One workspace. The host has a single window. Its document area splits into panes as in Obsidian: nested in both directions, made by dragging a tab onto a pane's edge or with Split right / Split down (which move the active document), resized by dragging the dividers. Each pane has a tab strip; tabs move between panes by dragging. A document is open at most once: one tab in one pane. An emptied pane disappears, except the last one, which shows an empty state (Open…, drop a document here). Each document is its own
WebContentsView; the host tracks which path belongs to which view. - Document list. A collapsible list on the side with every open document, grouped by pane, as a compact list or as thumbnails (like a PDF viewer's page sidebar). Tabs and list show the file name (full path on hover, parent folder added when two names are equal), the unsaved marker and badges.
- Host UI outside every document. The list, tab strips, splitters and banners are drawn by one host-UI view beneath the document views (plain HTML and JavaScript, its own session and preload). The workspace model (layout, tabs, active document) lives in the main process. Everything the host tells or asks appears only in host areas, never in or over a document; documents cannot show native dialogs. See ADR 0001.
- Banners and sheets. What happens to a document while the user is not acting on it (changed on disk while unsaved, data changed on disk, moved or deleted, no longer conforming, errors while checking the disk) becomes a banner in its pane and a badge on its tab and list entry. What the user just did (save conflict, failed save, reload, close) is answered in a sheet on the window. A clean document that reloads after an external change shows a short "Updated from disk" banner.
- Hidden documents keep running with Chromium's background throttling. Thumbnails are captured when a document is hidden, after every save and reload, 2 seconds after the last change while it is visible, and once after it first loads; they are held in memory only.
- Workspace restore. On quit the host writes
workspace.jsonto the app data folder (open paths, layout, tabs, active document, list mode, window size). The next start reopens every file through the conformance check and names missing or refused files in one notice. Unsaved changes are never carried over. - Closing. Cmd/Ctrl+W closes the active document. Closing the window quits the host on every platform. With several unsaved documents, closing shows the close summary: Save all / Review each / Cancel; a failed save stops closing on that document.
- Kit 1.1.0, fallback save UI. The document marks its Save button and status line (
data-ev-fallback); the kit hides them in the host and wires them up in the browser. Replaces the rule that the document itself decides fromdoc.hosted(kept for compatibility). - Kit update. A document with an outdated kit gets a badge, File → Update kit… and, once per run, a banner. After the user confirms, the host replaces only the kit (and saves unsaved data in the same write); the previous file stays in the version store, and Undo brings the old kit back until the document is closed.
Not in M2: several windows, the same document in two panes, autosave, unsaved changes across a restart, Open Recent, tab previews, search or sorting in the list, pinned tabs, updating every kit at once, putting hidden documents to sleep, OS notifications.
M3 · Distribution: installed, associated, self-updating, for the user and a small circle of testers who install from a link. Design decided on 2026-10-10; plan in docs/plans/m3-distribution.md.
- Releases. The code and its releases live in the public repository
telemersion/EverythingApp, released the same way as Telemersive Gateway (telemersion/telemersive-portbay): pushing av*tag runs CI, which checks, builds, signs and publishes a GitHub Release withlatest.ymlandlatest-mac.yml. Each milestone ships as a minor release (the end of M3 is 0.1.0, fixes are patch releases);v0.1.0-beta.Ntags try the pipeline and a real update first. The bundle id isch.zhdk.telemersion.everythingapp; the name stays EverythingApp, so the data folder does not move. - Installers. macOS: DMG and ZIP for x64 and arm64, signed with the ZHdK Developer ID and notarised. Windows: an x64 NSIS installer that installs per user without administrator rights, unsigned for now (one SmartScreen warning on first install). Electron fuses turn off running as Node,
NODE_OPTIONSand the inspect flags, and check the integrity of the app archive. - CI. Every push to
mainruns the unit tests, the probe and the smoke test on macOS and Windows. A release build runs them too, then runs the probe against the packaged app, before anything is uploaded. - Host updates.
electron-updaterchecks 2 seconds after start and on Help → Check for updates, downloads a new release in the background and installs it when the host quits. A notice in the document list says the update is ready and offers Restart now, which quits through the close summary and restores the workspace. On macOS, a host that runs outside the Applications folder offers at start, before restoring the workspace, to move there, because updates cannot install anywhere else. The refusal for a newer API version offers the same check. - File association. The host registers as a possible handler for
.htmland.htm(Open With); the user makes it the default, and Help → Use EverythingApp for HTML documents… shows how (neither operating system lets an app do this itself). A file is a document if and only if its content contains theev-host-apimeta tag, whatever its extension; naming documents<name>.ev.htmlis a recommended convention, not a rule. A non-document that the operating system sent (double-click, Open With) is handed to the default browser, the app that handleshttps://, never back through the file association; a non-document that was dropped or picked in Open… gets the "not an EverythingApp document" sheet. - Version store clean-up once per start, after the restore, in the background: each entry has a
meta.json(absolute path, file name,ev-doc-type, data block hash, last seen). Volume not mounted → skip; file missing on a mounted volume (also when its folder is gone) → mark orphaned; orphaned for 90 days → delete. A total size cap of 500 MB removes the oldest orphans first, then the oldest versions of live documents, never a document's newest version. Errors of this and the update check go to the host log (<userData>/logs/host.log, Help → Show log), never into a sheet.
Not in M3: Windows code signing, update channels, delta updates beyond electron-builder's blockmaps, staged rollouts or rollback, making EverythingApp the default for HTML from inside the app, crash reporting or telemetry of any kind, app store builds, and document renderer crash handling.
After M3 the order is (decided 2026-10-10; milestone numbers are assigned when each one is planned):
- Format groundwork: a kit and document specification release that makes every document generated from then on ready for collaboration: document id, module slots, declared text fields, data design rules. See Collaboration, "Format groundwork"; designed on 2026-10-10, released as 0.2.0, plan in docs/plans/format-groundwork.md.
- Workbench and agent connector (single user): behaviour is developed in a workbench through a local agent connector. Answers the open question "Where generation happens".
- M4 · Privileges (not part of the single-user host): documents can request privileges beyond the sandbox, and the user can grant them. See the open question "Privileges requested by a document".
- Collaboration, in several milestones: team server and sync; roles and approvals; Library and history.
Non-goals for the single-user host, besides the skill that generates documents (defined once the specification is stable):
- Template upgrade (regenerate behaviour, keep data).
- Documents that rewrite their own code through the host API. The host never creates or changes behaviour: in the single-user host it writes only the data block (and replaces the kit, which is frame, after the user confirms); behaviour is improved outside the host by an agent editing the file on disk. From collaboration on, the host also installs behaviour versions that carry a maintainer's approval, and behaviour is developed in a workbench (see Collaboration).
- Attachments, multiple data blocks, network access, multi-user sync (designed, see Collaboration).
- Linux packaging.
- Re-linking the history of a moved document (match an orphaned store entry by file name,
ev-doc-typeand data block hash).meta.jsonalready records what is needed. - "Save as…" and "Follow moved documents": when a document's file is moved or deleted, the host now only says so; later it can save the open data to a new file or follow the file to its new place.
- A host-drawn confirmation:
evHost.confirm(message)in a later API version (feature-detected), shown in the document's banner row and labelled with its file name; the kit could routeconfirm()through it. Until then documents ask for confirmation inside their own UI (M2 turns off native dialogs). - "Revert to version" in the host UI (for now: restore by copying from the version store manually).
- Stashing unsaved local data across a reload, showing a diff against a changed data block on disk and suggesting a merge (later; the single-user host only offers keep mine / take disk / cancel). The merge step also offers "Save mine as a copy".
Every document, hand-written or generated, must satisfy this specification; it is the contract between the host and whatever produces documents, and v1 lives as docs/document-spec.md.
A document is a fixed frame with exactly four named sections: style, manifest, data and script. The frame is defined by this specification and is the same for every document, apart from a few frame fields (title, language, document type, document id) and the modules it uses. It includes the kit, the spec-defined script that loads the data, talks to the host and implements the fallback save. Everything a generator or agent writes goes into a section.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="ev-host-api" content="1">
<meta name="ev-doc-type" content="hours-sheet" data-version="1.0">
<meta name="ev-doc-id" content="">
<title>Hours sheet</title>
<style id="ev-style">/* style section */</style>
<script type="application/json" id="ev-manifest">{"textFields":["rows.*.note"]}</script>
</head>
<body>
<div id="ev-app"></div>
<script type="application/json" id="ev-data">{"rows":{}}</script>
<script id="ev-kit">/* kit: part of the frame, verbatim per API version */</script>
<script id="ev-module-codemirror">/* zero or more modules, sorted by name, verbatim */</script>
<script id="ev-script">/* script section */</script>
</body>
</html>| Section | Element | Written by | Contains |
|---|---|---|---|
| Style | <style id="ev-style"> |
Generator / agent | All CSS |
| Manifest | <script type="application/json" id="ev-manifest"> |
Generator / agent | What the host must know without running the document: the text fields (ADR 0005) |
| Data | <script type="application/json" id="ev-data"> |
Host (and fallback) | The data block |
| Script | <script id="ev-script"> |
Generator / agent | All JavaScript; renders the UI into #ev-app |
Rules:
-
Namespace. Every identifier defined by this specification starts with
ev(ev-for meta names and ids,evfor JavaScript globals:window.evHost,EvKit). The script section must not define its own identifiers with this prefix. -
Frame. Nothing outside the frame, its modules and its four sections. No additional elements, scripts, styles or comments.
-
Kit.
<script id="ev-kit" data-kit-version="1.0.0">is part of the frame. Every published kit version has a fixed text, and the host checks the kit against the hashes of all published kits for the document'sev-host-apiversion; unknown or modified kits are rejected. The script section uses it (EvKit.init(...)) and never reimplements loading, host wiring or saving. -
Sections. Exactly one of each section, identified by its id. Behaviour lives only in the style, manifest and script sections; data lives only in the data section.
-
Data block. The data section's content is valid JSON with every
<written as\u003c, so data can never close the script tag. -
Runtime UI. All UI is rendered by the script section into
#ev-appat load time.#ev-appis empty in the saved file. -
Host owns saving. When
window.evHostis present, the document shows no Save button and registers neither a Ctrl/Cmd+S handler norbeforeunload; it signals changes viaevHost.markDirty(). The host owns the save command, the dirty marker and the close prompt. Only without a host does the document show its own Save button and wire up the fallback (keyboard shortcut,beforeunload). -
Self-contained. No external scripts, stylesheets, fonts or images. Assets are inlined or embedded as data URIs.
-
API version.
<meta name="ev-host-api">declares the host API version the document expects. -
Document type.
<meta name="ev-doc-type">names the type and its behaviour version. Used later for template upgrades. -
Data shape. Top-level JSON object, designed for merging (see "Format groundwork" under Collaboration). The hours sheet uses
{"rows":{"<id>":{"date","person","task","hours","note"}}}withdateasYYYY-MM-DDandhoursas a number. -
Document id (from 0.2.0).
<meta name="ev-doc-id">is empty in a new document or holds 32 lowercase hex characters. Generators leave it empty; the host assigns an id on open and writes it with the first save, the kit on the first fallback save. -
Manifest (from 0.2.0). Always present (
{}when empty), part of the behaviour, checked strictly: only the keys this specification defines. -
Modules (from 0.2.0). Zero or more
<script id="ev-module-{name}" data-module-version="{version}">between the kit and the script, sorted by name, each the exact text of a published module (ADR 0003). The script reaches them throughEvKit.module(name, major).
Recommendations for generators (the future skill builds on these):
- Render an empty data block gracefully, so a fresh document starts usable.
- Keep behaviour readable rather than minified, so a person can inspect what a generated document does.
- Keep the data shape flat and documented in a comment at the top of the script section.
The host exposes window.evHost through Electron's contextBridge. It is a pull API: the host decides when to save and asks the document for its data; the document never starts a write and never sends a file path.
| Member | Signature | Semantics |
|---|---|---|
version |
number |
Host API version, 1 for this spec. |
onSaveRequest |
(handler: () => string) => void |
Registers the function the host calls when the user saves (menu, Ctrl/Cmd+S, close prompt). It returns the current data as JSON. |
markDirty |
() => void |
One-way signal: the data changed since the last save. Drives the title marker and the close prompt. |
Dirty state belongs to the host. Each markDirty() bumps a change counter; a save records the counter at the moment it takes the snapshot. After a successful write the host clears the dirty marker only if no markDirty() arrived after that snapshot, so an edit made while saving is never marked as saved.
Preload (host side):
const { contextBridge, ipcRenderer } = require('electron');
let saveHandler = null;
let changes = 0;
ipcRenderer.on('doc:request-save', (_e, requestId) => {
if (saveHandler) ipcRenderer.send('doc:save-data', { requestId, json: saveHandler(), changes });
});
contextBridge.exposeInMainWorld('evHost', {
version: 1,
onSaveRequest: (fn) => { saveHandler = fn; },
markDirty: () => ipcRenderer.send('doc:dirty', ++changes),
});Document side:
The kit does this wiring; the script section only hands it the data and reports changes. Inside the kit:
if (window.evHost) {
evHost.onSaveRequest(() => JSON.stringify(getData())); // host drives saving; no Save button, key binding or beforeunload
} else {
showSaveButton(fallbackSave); // see Browser fallback
bindSaveKey(fallbackSave);
guardUnload();
}In the script section (illustrative; the kit's exact interface is defined in the Document specification):
const doc = EvKit.init({ getData: () => data });
const data = doc.data; // parsed data block
// … render into #ev-app …
doc.changed(); // wherever data changes → evHost.markDirty() or fallback dirty stateThe main process owns all file access; it maps each document view to exactly one file path and never takes a path from the document.
- Open. Sources: File → Open dialog, command-line argument, drag-and-drop onto the app or window, and file association (double-click). The host first reads the file's head: without the
ev-host-apimeta tag the file is not a document (any extension). A non-document that the operating system sent (file association, Open With, command-line argument) is handed to the default browser, the app that handleshttps://, and never back through the file association, which would send it to the host again; one that was dropped or picked in the Open dialog gets a sheet saying it is not an EverythingApp document. For documents, the host runs the conformance check; on any violation it refuses to open the document and shows the report. Otherwise it creates aWebContentsViewand storeswebContents.id → absolute path. - Load. The document's view loads it from the custom protocol
ev-doc://<random-id>/(see Security model), never viafile://. The document gets its ownWebContentsView, a tab right of the active tab in the focused pane, and an entry in the document list; a file dropped onto a document opens in that document's pane. The window title shows the active document's file name, prefixed with•while it is dirty. Thumbnails are captured from the live view (capturePage) when a document is hidden, after each save and reload, 2 seconds after the last change while it is visible, and once after its first load; they are held in memory only. - Save. File → Save, Ctrl/Cmd+S or the close prompt sends
doc:request-saveto the active document's view. The document answers withdoc:save-data; the host looks up the path for the sending view, reads the current file from disk, replaces only the data block content and writes it (step 5). - Dirty state.
doc:dirtymarks the document dirty (its tab, its list entry and, while it is active, the window title). After a successful write, the host clears the marker only if the snapshot's change counter is still the latest one. - Write safely. Copy the current file into the version store (
<app data>/EverythingApp/versions/<hash of absolute path>/), write the new content to<name>.tmpin the same folder, then rename it over the original. On any error the original stays untouched and the error is returned to the document. - External change. The host watches each open file and hashes the data block and everything outside it on load and after every save. When the file changes on disk (M2: as a banner in the document's pane and a badge on its tab and list entry, never a dialog):
- Anything outside the data block changed (behaviour, kit or frame fields), document clean → reload automatically and show a short "Updated from disk" banner.
- Anything outside the data block changed, document dirty → banner: "This document was updated on disk. Save my data and reload / Reload and discard my changes / Later".
- Data block changed, document dirty → banner at once: Keep mine / Take the version on disk. Never overwrite silently: if the conflict is still open at the next save, the save asks the same in a sheet (plus Cancel). The write itself checks again that the data on disk is still what the host last saw; if it is not, the same prompt appears.
- File moved or deleted → banner ("moved or deleted"): changes exist only in the window, put the file back at its path and save again. The last saved version stays in the version store.
- Reload (View → Reload) with unsaved changes asks in a sheet: Save and reload / Discard and reload / Cancel.
- Close. Closing a document (Cmd/Ctrl+W) that is dirty shows Save / Don't save / Cancel; Save triggers step 3. A document closes only when nothing is left unsaved: a failed save, or an edit made while saving, keeps it open. Save, close and reload run one at a time per document; close and reload wait for a running save. A save requested while another runs waits and then saves again with fresh data; if the running save fails or is cancelled, the waiting one is dropped. Closing the window or quitting with one dirty document shows that document's prompt; with several, the close summary: Save all / Review each / Cancel. Save all stops at the first document that fails, is cancelled or is dirty again, and makes it active; Review each asks per document, and Cancel anywhere keeps everything open. Closing the window quits the host on every platform, after writing
workspace.json. Ctrl/Cmd+S and File → Save always act on the active document. - Unexpected errors. Any failure not handled elsewhere (opening, checking the disk, closing, reloading) shows an error dialog with a "Copy report" button: file, action, message, stack trace, host and Electron version.
- Menu. File: Open, Save, Close, Close window, Update kit…, Reveal in folder. View: Document list (show/hide), List / Thumbnails, Split right, Split down, Reload, Developer tools (dev builds only). Window: next and previous tab, tab by position, neighbouring pane. Help: Check for updates, Use EverythingApp for HTML documents…, Show log, About EverythingApp (Windows; macOS has it in the app menu).
Splicing the data block (main process, doc-host/src/splice.js):
function splice(html, json) {
if (typeof json !== 'string') throw new TypeError('The data must be a JSON string.');
JSON.parse(json); // reject invalid JSON
const frame = parseDocument(html); // locate sections through the frame
if (!frame.ok) throw new Error('The file does not match the document frame.');
return buildDocument({ ...frame.parts, data: escapeJson(json) });
}The data block is located through the frame parser, never by searching for its tag: the kit's own source contains the text <script type="application/json" id="ev-data"> (it builds the frame for the browser fallback), so a text search finds a second, false data block. Because a conforming file is exactly buildDocument(parseDocument(file).parts), rebuilding it changes only the data block. No regex replacement is involved, so $ sequences in the data stay literal.
Without a host, the document saves a new copy of itself. hours-sheet.html pioneered this; the specification keeps the idea but replaces its DOM-clone serialisation.
| Browser | Mechanism | User experience |
|---|---|---|
| Chrome, Edge | File System Access API (showSaveFilePicker, createWritable); handle stored in IndexedDB keyed by location.href |
Pick the file once; later at most an "Allow editing" prompt per session |
| Firefox, Safari | Blob + <a download> |
New copy lands in Downloads; the user replaces the original manually |
Serialisation without a host: rebuild the file from the frame, never from the live DOM. The fallback lives in the kit, so every document carries the same implementation. It reads the frame fields from the <meta> tags and <html lang>, takes the original text of the style, manifest and script sections and the modules (textContent of #ev-style, #ev-manifest, #ev-script and each ev-module-*, which the runtime never touches) and inserts the escaped JSON as the data section. On the first fallback save of a document with an empty document id, it fills in a new one. The output always conforms, and a fallback save produces the same bytes as a host save.
Why not a DOM clone: anything the script changes at runtime (body classes, injected nodes such as datalists, a changed title) would leak into the saved file and break the frame, and DOM serialisation reformats the whole file.
Constraint this imposes: the parser normalises CRLF to LF inside sections, so documents use LF line endings only (checked on open).
Known limits: fetch of sibling files is blocked on file://; the stored handle breaks when the file moves; clearing site data forgets it. The first save dialog cannot start in the document's own folder (a page does not know where its file is; Chrome opens Downloads), so the user must find the original file there, or the save lands in a new copy (observed in the M1 manual check; a candidate for the kit 1.1 fallback save UI).
Every document is untrusted code: it may only render itself and save its own data block, nothing else.
Microsoft's HTA format is the cautionary precedent: HTML documents ran with full system rights and became a common malware vector. The host must never grant documents more power than a web page has.
Required settings and checks:
webPreferences:contextIsolation: true,sandbox: true,nodeIntegration: false,webSecurity: true.- No path from the page. The path is resolved in the main process from
event.sender.id. The API has no path parameter. - No navigation. Block
will-navigateandwill-redirect; denysetWindowOpenHandler; open no new windows. - Custom protocol, closed by default. Documents are served by the main process under
ev-doc://<random-id>/(protocol.handle), a fresh random id per opened document. The handler answers exactly that one URL with the file content and a CSP header (default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; img-src data: blob:; font-src data:); every other request on the scheme returns 404.file://,http(s)://and all other schemes are blocked for document sessions. The document never learns its real path. - Network. The host resolves no names except the update host names (
host-resolver-rulesmaps every name to "not found" and excludes exactly those names, without wildcards), so documents cannot leak data through DNS lookups such as dns-prefetch. The rules apply to the whole app, document sessions included; a document could at most look up one of the fixed update names, which carries no data. WebRTC UDP is disabled, and every document session and the host-UI session go through a proxy that refuses every connection. The only network access in the whole host is the host update, made by the main process (not by any document session) to the fixed update feed on GitHub. Collaboration adds a second connection, also from the main process only: sync with the team server. Document sessions never get network access; collaboration is a host feature, not a document privilege. - No input to subframes. The host injects a user style that gives iframes and frames no pointer input, so a file dropped onto one lands on the document itself, where the host opens it. A document does not receive dropped files; it can import files through a file picker or paste. Known limit of M1: the drop guard is a set of event listeners the preload adds to the page, and
document.open()removes every listener on the page. A document that calls it once its own parsing is done (from a timer or an event handler) can then receive files the user drops onto it (their contents, not their paths); confirmed with a real drag in the M1 manual check (2026-10-07). Patchingdocument.openfrom the preload is not a reliable guard (another frame's copy of the function would likely bypass it); closing this needs a guard outside the page (M4). - Size limits. Documents over 60 MB are refused on open; data blocks over 50 MB are not written. The 60 MB limit is checked only on open in M1.
- No permissions.
setPermissionRequestHandlerdenies camera, microphone, geolocation, notifications, fullscreen etc. - No native dialogs (M2).
webPreferences.disableDialogs:alert()does nothing andconfirm()returnsfalse. Electron shows them as native message boxes that look like the host's own and name no document, and it offers no way to show them anywhere else, so they are turned off. Documents ask for confirmation inside their own UI. - Host UI outside the document (M2). Host messages appear only in host areas (document list, tab strips, banner rows); a document's view never overlaps them. The host-UI view only accepts its own messages (
ui:*) and documents only theirs (doc:*), told apart by the sending view. - Validate writes. The host rejects
doc:save-datawith non-string input, invalid JSON and payloads over a size limit (e.g. 50 MB). - Data, not code (permanent). The Host API is data-only in every version. The host writes the data block on save and the kit on a user-confirmed kit update; it never writes the style, manifest or script section on behalf of a document (it does write the document id, a frame field, with the first save). Kit text comes only from the host's own list of published kits, never from the document, so a document cannot rewrite any code through the API. From collaboration on, the host also installs module versions from its own list and behaviour versions that carry a maintainer's approval; neither ever comes from the running document.
- Origin isolation. The random id gives each opened document its own origin, so documents cannot read each other's storage.
- No persistent browser storage. Document sessions run in memory (no
persist:partition):localStorage, IndexedDB and caches are empty on every open and leave no traces on disk. View state (filters, scroll position) lasts one session; whatever should survive belongs in the data block.
The host never breaks an old document: API versions are only ever added, and documents degrade gracefully when a feature is missing. This promise starts with 0.2.0: the format groundwork amended API 1 in place (document id, manifest, modules), because no API 1 documents existed outside the test fixtures.
- API versions. The host reads
ev-host-apibefore loading. It supports every version it has ever shipped. A document asking for a newer version than the host knows is refused, like any other conformance violation: "This document needs a newer EverythingApp (API v2). Update the host, or open it in Chrome." - Host releases. Release numbers (0.1.0, 0.2.0, …) count the host's milestones and are independent of the host API version and the kit version; a host release never changes a document.
- Feature detection. Documents check
window.evHostandevHost.versionand keep a working browser path. - Data versus behaviour. Because data lives in one block, a document's behaviour can be replaced while its content stays. The
ev-doc-typemeta tag identifies which behaviour a file carries. - Template upgrade (after the single-user host). The host offers "Upgrade document": regenerate the behaviour, or take a newer template, for the same
ev-doc-type, insert the old data block, keep the previous file in the version store. If the data shape changed, the new template ships amigrate(oldData, fromVersion)function that runs once on load.
Designed on 2026-10-10 in a design interview; built after M4 (see the order under Scope). Terms are in the glossary's Collaboration section. The decisions with lasting trade-offs are recorded in ADR 0002, ADR 0003 and ADR 0004.
Goal. A small team works on the same purpose-built documents, online or offline. Each copy stays the member's own file, only approved code runs, and within those two limits working together should feel effortless.
When the goals conflict, ownership comes first, then trust, then flow:
- Ownership. Every copy is the member's own file. It works on its own in a browser, years from now, and nothing removes it without the member's consent.
- Trust. No shared code runs unless a maintainer approved it, and the team server alone cannot change that.
- Flow. Within those limits, syncing and merging go unnoticed: rows simply arrive.
Audience. A small team whose members know and trust each other, on a team server the team controls. Strangers never get in. One person with several devices is a team of one.
- Setup. Felix runs the team server and is its Root maintainer. He defines the access types Invoice and Hours, and invites Anna, Ben, Carla and Max; each one's host registers a device key.
- Create and share. Anna asks Claude for an hours sheet. It carries a document id, the published kit and modules, and rows with stable ids. She chooses Share to team and confirms the suggested access type Hours. Its history moves to the server; her file is pristine again.
- Get a copy. Ben opens the document URL from the team chat; his host places a copy under his team root. Dora from accounting has no host: the same URL shows her a read-only view in her browser.
- Offline. Ben adds rows on the train; his file carries the unsynced history. Anna adds hers at the office. At home Ben's host is running with the sheet closed, and his rows go up. Anna's clean sheet reloads with "Ben added 3 rows". One of Ben's saves has the note "corrected week 41".
- Behaviour change. Carla wants weekly totals. In a workbench, Claude develops them through the agent connector on a private copy of the data. Carla clicks Propose; Anna, a maintainer, reviews the diff and approves, which signs it. Every host checks the signature and installs the new behaviour: "Updated by Carla, approved by Anna". Ben's old script kept the field it did not know.
- History. At month's end Anna scrubs back to 1 October and sees the sheet through the behaviour of that time, finds who changed row 7, and restores Ben's deleted rows as a new save.
- Leaving. Max leaves the team. His host reports the removed access; he declines the Trash and keeps a revoked copy, cut off from the document's future history. Later Anna's laptop is stolen: Felix removes that device key and re-approves the behaviour versions it signed, in one batch.
┌─ Copy (file on disk) ──────────────────────────────────────────┐
│ frame: document id · document type · kit · modules │
│ sections: style · manifest (text fields) · data (JSON │
│ snapshot) · script │
│ unsynced history (what the team server does not have yet) │
└────────────────────────────────────────────────────────────────┘
▲ writes data, unsynced history and approved versions only
┌─ Host ─────────────────────────────────────────────────────────┐
│ renderer per document: sandboxed, no network (unchanged) │
│ UI: workspace · Library (This computer, Team) · workbench │
│ main process: │
│ copy registry (document id → path) · member settings file │
│ merge engine (snapshot diff → changes; text per character) │
│ history cache (synced history per id) · version store │
│ approval check (current maintainers' device keys) │
│ agent connector (MCP, local, workbench only) │
│ sync client ──────────────────────────────┐ │
└─────────────────────────────────────────────┼──────────────────┘
▼
┌─ Team server ──────────────────────────────────────────────────┐
│ accounts, sign-in, device keys · members, roles, access types │
│ role-change history · team folders · document URLs │
│ history store (copies without modules) · role check per change │
│ behaviour proposals · read-only web view (own sandboxed origin)│
└────────────────────────────────────────────────────────────────┘
The rules that tie it together: data merges, behaviour is approved; the team server checks roles, every host checks approvals; a file always works on its own; nothing is removed without consent.
- A document has a document id in its frame. Files with the same id are copies of one document, possibly at different points of its history; copies merge whenever they meet. A copy is never a new document.
- When the host sees a second copy of a document on the same machine at a different point of its history (typically duplicated in Finder), it asks once: Same document / New document. New document from this… gives a copy a new id and no history.
- A document is shared with at most one team. Another team gets a new document made from it.
- One history per document: data saves merge; behaviour versions (with their approvals), kit updates and module updates are whole versions that replace each other.
- A copy's file carries exactly the unsynced history: all of it before the first share, nothing right after a confirmed sync, the offline tail in between (ADR 0002). The host trims it only after the team server confirms it stored the changes, and caches the synced history keyed by document id.
- Every save reaches the team as soon as the host is online. Save with note… (⇧⌘S) adds an optional save note. Drafts, branches that merge back later, are the next step after the first collaborative version.
- The history panel lists saves (author, time, note), shows who changed a field, and restores an earlier state as a new save; nothing is ever rewound. A slider shows any past moment read-only, through the behaviour of that time if its approval is still valid, otherwise through today's behaviour with a notice.
- Sync runs in the host's main process. Documents never get network access; collaboration is not a privilege.
- While it runs, the host syncs every copy it knows about (copy registry: document id → path), open or closed, in both directions.
- The host compares each saved snapshot with the last one and turns the difference into changes. Strings merge as whole values, except fields the document declares as text, which merge per character. A finer change API (
doc.change(…)) follows in Host API v2. - Incoming changes: a clean document reloads with the merged data and a banner ("Anna added 2 rows"); a dirty one shows "Anna's changes are waiting · Merge now" and merges at the next save. Host API v2 pushes the merged data and the changes as patches through the kit, so the script updates in place (CodeMirror keeps the cursor).
- Per team, the host asks once for a team root (default
~/Documents/EverythingApp/<Team>/). New copies land there, mirroring the team folders; afterwards the member moves and renames them freely. Team folders are administrative only. - A copy that is missing at start is searched for by id in its team root; otherwise the Library shows it as moved or deleted, with Locate… and Forget this copy.
- The Library has two tabs: This computer (every known copy, arranged in member-defined groups, with badges for missing, unsynced, revoked and updates) and Team (the team folders, with Get a copy). The document list keeps showing only the open documents.
- Member settings (groups, team connections, trust decisions) live in one file in the host's data folder, keyed by document id, so they can later become a synced personal document.
- A document URL opens the document in the host. In a browser it shows a read-only view, served from its own sandboxed origin, with Open in EverythingApp and Download copy (the full file, modules included).
Behaviour and trust (ADR 0004)
- Data merges; behaviour is approved. A maintainer's own behaviour change counts as approved; anyone else's is a behaviour proposal that runs only in their own copy until a maintainer approves it.
- The team server checks every change against the member's role. Every host checks the approval (a maintainer's signature over the behaviour) against the current maintainers' device keys before it runs shared behaviour.
- An approval counts only while its signer is a maintainer and the device key is registered. When a maintainer leaves or a key is removed, its approvals end; copies keep the behaviour they already run, and the remaining maintainers re-approve in one batch.
- The host installs approved behaviour versions and never creates or changes behaviour itself.
- Behaviour is developed in a workbench through the agent connector (see the open questions "Where generation happens" and "Agent connector").
- A script keeps every data field it does not know and writes it back unchanged.
Modules (ADR 0003)
- Third-party scripts such as CodeMirror are curated modules, published with the kit and pinned by hash like the kit. They can grow into a whole toolbox that behaviours build on.
- The team server stores and syncs copies without modules; the host inserts the modules whenever it writes a file to disk, and Download copy delivers the full file. Every file on any disk works in a browser. Module updates are offered like kit updates.
- Roles: Reader (opens, gets copies, sees the history; changes do not sync), Editor (also changes data and may propose behaviour), Maintainer (also approves behaviour).
- A member holds roles on a document directly, through its access type, and through Root. Roles only add up; the highest one counts; there are no exclusions.
- Access types (Invoice, Contract; Root for all documents, None for documents given no type) are defined by the team. The team server suggests one from the document type through a mapping the team keeps, and the sharing member confirms or picks one. Changing it later needs Maintainer on the old and the new type. The document type never decides access.
- Root maintainers manage the team: members, access types and team roles. Every role change is kept in the team's history, visible to all members.
- A member joins through an invitation, gets one account on the team server and one device key per device. Sign-in is the team server's concern (invitation and passkey first, organisation sign-on later); device keys are the host's.
- When access is revoked, the host reports it. Accept moves the copy to the Trash; declining keeps it as a revoked copy, cut off from the document's future history. The team is not notified. If access returns, syncing resumes. A downgrade (Editor → Reader) only shows a banner. The team server judges changes when they arrive: changes rejected after a revocation stay in the member's file.
- Hard rule: the host never deletes or removes a copy without the member's consent, whatever the team server says.
- A view is part of the behaviour and shows only its own document's data ("Edit", "Monthly report"); adding one is a behaviour change. Views over other documents need the M4 privilege "reading another document's data".
- Strangers or public links: only members.
- Live co-typing with remote cursors (comes with Host API v2).
- Drafts (the next step).
- Views across documents (an M4 privilege).
- Agents editing data (later, separately enabled).
- Sync while the host is not running.
- Synced personal settings (designed for).
- Exclusions in roles.
- Peer-to-peer sync: hosts sync only through a team server.
- End-to-end encryption: the team server can read the documents it keeps, because it builds their read-only browser views.
- A document shared with more than one team.
The document specification release after M3 (0.2.0), designed on 2026-10-10 after the technical tests; plan and decisions in docs/plans/format-groundwork.md. It changes only the format: nothing records history yet. The first collaboration milestone adds the history marker and the unsynced history to the frame under a new host API version; documents made before then start their history deterministically from their data block.
- A document id frame field (
ev-doc-id, 32 lowercase hex), left empty by generators and assigned by the host on open (written with the first save) or by the kit on the first fallback save. The version store records it too. - Module slots in the frame, checked by hash like the kit;
codemirror1.0.0 (a minimal editor: state, view, undo history, standard keys) as the first module. The script asks the kit for a module and the major version it was written for,EvKit.module('codemirror', 1). Minor and patch versions will be updated like the kit after the user confirms; a major version needs a behaviour change. - A manifest section that declares the text fields that merge per character (
{"textFields":["rows.*.note"]},*matching any array item or map key), with instructions for generators on how to design collaborative text (blocks with ids, CodeMirror for longer text). See ADR 0005. - Designing data for merging, rules for generators (the host never enforces them; it never refuses a user's data because of its shape):
- Every item in a list lives under a stable id key, created once with
EvKit.newId()and never reused. The id is the key only, not repeated inside the item. - A list of items is an object keyed by id, never an array (ADR 0006). Arrays are for small lists of plain values that change as a whole.
- Where order matters, each item has a string sort key made with
EvKit.orderBetween(a, b); a move changes only the moved item's key. Scripts list items withEvKit.ordered(map). - Store nothing derived: totals, counts and sums are computed by the script. Sorting for display (by date, by name) is a view, not stored.
- No counters as plain numbers: record entries and let the script count them.
- One fact in one place.
- Split long text into items (paragraphs, a note per row), so edits to different items merge; declare free text that people edit as a text field.
- Keep every field the script does not know, and write it back unchanged.
- Name fields as identifiers (letters, digits,
_), so text-field paths can name them. - Deleting an item removes its key; the history keeps what was deleted.
- Every item in a list lives under a stable id key, created once with
Run on 2026-10-10 as spikes; results in docs/plans/format-groundwork.md.
- Whether Automerge can record new changes on top of a snapshot without the full history (the case of a pristine file opened with no cache and no connection). No; the fallback works: record such offline edits as data changes and replay them with
changeAtat the file's marker once the history is available. - Character-level merging of text from snapshot diffs. Works, with the usual text-CRDT limits; the host needs a bounded, grapheme-safe diff.
- Merge quality of snapshot comparison on lists with stable ids (insert, delete, reorder). Good for insert, delete and edit; reorder needs a map keyed by id with sort keys.
- The size of a minimal CodeMirror 6 bundle as a module. About 270 KB minified (89 KB gzip); runs under the document CSP.
We build the host with Electron, because it ships its own Chromium and so renders every document identically on every machine and over time.
Since the host is the product, its engine defines what every document can rely on. One known Chromium version also gives the specification and the skill a single, fixed target to generate for.
| Criterion | Electron | Tauri |
|---|---|---|
| Web engine | Bundled Chromium, same everywhere | System webview: WebKit on macOS, WebView2 on Windows, WebKitGTK on Linux |
| Rendering consistency | Identical across platforms | Can differ per OS and OS version |
| Installer size | about 100 MB | about 5–10 MB |
| Backend language | JavaScript (Node.js) | Rust |
| Fit for the single-user host | Fast start, same engine as the Chrome fallback | Revisit if size or memory become a problem |
The idea has a solid lineage; TiddlyWiki with TiddlyDesktop is the closest working example to study before coding.
| Project | What it shows | Lesson for us |
|---|---|---|
| TiddlyWiki + TiddlyDesktop | Single HTML file with data, behaviour and UI that saves itself; desktop host for seamless saving | The pattern works and lasts; look at its saver modules |
| HyperCard | Stacks as documents carrying their own interface and scripts | Documents as end-user programs |
| Microsoft HTA | HTML files run as desktop programs by mshta.exe |
Full system rights made it a malware vector; sandbox strictly |
| Ink & Switch (malleable and local-first software) | Research on user-owned, adaptable software and data | Ownership and longevity as design goals |
| Webstrates | Shareable, editable web documents as software | Documents as the unit of software |
| Patchwork (Ink & Switch, 2026) | Local-first platform where documents, tools and their source code are all synced documents; any tool can open any data | A shared tool whose code syncs and runs at once is a supply-chain risk: know who can change the code you run (ADR 0004). Its history slider and drafts inform the collaboration design |
| Automerge | CRDT library with a compact format and a sync protocol; the change history is part of the document | Most likely CRDT library for collaboration; history as a feature, not a cost. To verify in the technical tests |
| Local-first software (Kleppmann et al., 2019) | The essay that defined local-first: offline work, ownership, longevity, collaboration | The source of the ownership goal in the collaboration design |
- Where generation happens. Resolved (2026-10-10): on the user's computer, by an agent (such as Claude) that works through the host's agent connector in a workbench: the draft behaviour runs on a private copy of the data that never syncs, and the agent can edit, reload, read console output and run tests there. The host does not call Claude itself. A person ends the work with Apply (unshared document), Propose or Approve and publish (shared document). Delivered by the "Workbench and agent connector" milestone; see Collaboration.
- Skill scope. Should the skill only generate documents, or also inspect and repair documents that fail the conformance check (the host's copyable report is its natural input)? Note: the skill should target the API version of the user's installed host, so newer-API refusals stay rare.
- File extension. Resolved: any extension; a file is a document by content (the
ev-host-apimeta tag).<name>.ev.htmlis a recommended convention. The host registers as a possible handler for.html(the user makes it the default) and passes non-documents that the operating system sent to the default browser. - Self-modifying documents. Resolved: never. A document cannot write its own behaviour through the Host API, in any API version. Behaviour changes come only from outside the document: an agent or the skill editing the file, or the host's own kit and template updates.
- Privileges requested by a document (target: M4). A document has no privileges unless the user grants them. Design questions: where a request is declared (statically in the document, or at runtime); what a grant is bound to (path, document type, or a hash of the behaviour; an agent that rewrites the behaviour must not inherit a grant); where grants are stored and how the user revokes them (needs host UI, so after M2); how the browser fallback differs. First candidate privileges: drag-and-drop import into a document (in M1, dropped files and folders do not reach a document, except through the
document.open()limit in the security model), network to one fixed origin, reading another document's data (views and dashboards across documents; decided 2026-10-10 as the path for cross-document views). Shared editing is not a privilege: sync runs in the host, and documents never get network access for it. Already possible without a privilege, because the user controls them: importing through a file picker (<input type="file">) and paste. Requirement for M4: the host handles file drops outside the page, before the document's renderer sees them, so that a document cannot remove the guard (thedocument.open()limit of M1). - Agent connector. Resolved (2026-10-10): the host exposes a local MCP connector, an agent-facing channel that is not part of the Host API documents see. First scope: workbenches only. An agent reads the behaviour and the private data snapshot, writes the draft behaviour, reloads, reads console output and runs tests; it never reads or changes a copy, never saves, and never proposes, approves or applies (only a person clicks those). The workbench offers "Use sample data" for confidential documents, because the agent's provider sees what the agent reads. Still open, as a later, separately enabled feature: agents editing the data of real copies (attribution "Carla (via Claude)" in the history, undoing all of an agent's edits, confirmation per session).
- Trust indicator. For team documents, decided (2026-10-10): approvals, that is maintainer signatures that every host checks before running shared behaviour (see Collaboration). Still open for files that arrive from outside a team: show the OS origin flag (macOS quarantine, Windows Mark-of-the-Web) as a banner on first open.
- Concurrent edits. Resolved: watch the file, react per section (see Host behaviour, step 6). Later: stash local data, show a diff, suggest a merge.
- Update manifest. Resolved: GitHub Releases with
electron-updater(electron-builder); CI builds, signs, notarises and uploads, the host readslatest.yml/latest-mac.yml. The releases must be publicly readable (public repo or a separate public releases repo). The releases are public intelemersion/EverythingApp, which also holds the code (2026-10-10). macOS builds are signed with the ZHdK Developer ID, the same Apple team as Telemersive Gateway; Windows builds are unsigned for now. - Backups. Resolved: central version store in the app data folder, keyed by path; no sibling files (safe in Git repos, shared and synced folders).
- Persistent per-document settings. Resolved: none in the single-user host; view state is per session, durable state lives in the data block. A host-managed
evHost.viewStatemay follow in a later API version (feature-detected). The M2workspace.jsonis host state (which files are open and where), not per-document settings.
Facts established during the design review. Carry them over when this spec is split; each goes next to the rule it explains.
| Fact | Explains | Destination |
|---|---|---|
The host identifies a document by its real file path: the registry looks documents up by path (open.js), and the version store names its folders after a hash of the absolute path (write.js). Collaboration changes this to "identified by document id, found at a path". |
Copy registry, history cache and member settings keyed by document id | Architecture document (when the format groundwork starts) |
Host API v1 is pull-only: the host asks for the whole data as a JSON snapshot on save (preload.js) and never pushes data into a document. |
Snapshot comparison for merging; push of merged data and patches in Host API v2 | Architecture document (when the format groundwork starts) |
On an outside change the host reloads a clean document and shows a banner on a dirty one (document.js, external-change handling). Collaboration reuses this path, with an automatic merge in place of the "Keep mine / Take the version on disk" choice. |
Incoming changes while a document is open | Architecture document (when collaboration starts) |
Automerge's changeAt(doc, heads, …) does not throw for heads the document does not know: it silently records a change without dependencies. Check A.hasHeads(doc, heads) first (spike 1, Automerge 3.5). |
Replaying offline saves of a pristine file at its marker | Architecture document (when collaboration starts) |
A.updateText grows roughly quadratically when the strings differ a lot (49 s for 100,000 characters rewritten). diff-match-patch with a timeout is fast but splits surrogate pairs; running it over graphemes is correct and stays under 1 s (spike 2). |
The merge engine's text diff, off the main thread | Architecture document (when collaboration starts) |
A history started with an actor derived from the document id, time: 0, a fixed message and sorted keys gives byte-identical first changes on every host, so copies with identical data blocks share a root (spike 5). |
Starting the history of documents made before collaboration | Architecture document (when collaboration starts) |
| A whole-list sort written into the data scatters concurrent inserts, and a move in an array loses a concurrent edit of the moved item (spike 3). | Data design rules 2–4, ADR 0006 | Architecture document (when collaboration starts) |
Carried over: the CRLF and beforeunload facts now live in docs/document-spec.md (rules 4 and 5). The M3 facts (Squirrel.Mac and signing, resolver rules, App Translocation, default handlers, Windows code-signing keys, GitHub secrets) live in docs/architecture/distribution.md and docs/guides/releasing.md.
Start with the host skeleton and the save loop, and write the document specification alongside it, since the specification defines what the host accepts.
Repository layout: EverythingApp/ is the repository root for the whole system. docs/ serves the whole system; each component (the host now, the skill later) gets its own top-level folder.
EverythingApp/
docs/
SPEC.md # this document (currently firstSpec.md at the root)
document-spec.md # normative spec for documents (input for the future skill)
reference/glossary.md
plans/ # implementation plans per milestone
doc-host/ # the host (Electron app)
package.json
src/
main.js # BaseWindow + WebContentsView, path map, menu, IPC
preload.js # window.evHost (API v1)
protocol.js # ev-doc:// handler, CSP, closed-by-default
security.js # navigation, permissions, scheme blocking
splice.js # data block parse + replace (pure, unit-tested)
conformance.js # frame, sections, kit hash, line endings, API version
write.js # version store, temp file, rename
watch.js # external-change detection, section hashes
kit/
ev-kit-1.0.0.js # published kit texts; hashes generated at build time
fixtures/
hours-sheet.ev.html # first conforming document
invalid/ # broken documents for conformance tests
test/
splice.test.js
conformance.test.js
kit.test.js # fallback rebuild == host save, byte for byte
hours-sheet.html # the original prototype, kept until task 10
M1 tasks, in order:
- Scaffold the Electron app on
BaseWindow+WebContentsView; open a document via dialog, command-line argument and drag-and-drop. - Write
docs/document-spec.mdv1 from the "Document specification" and "Host API v1" sections, including the frame and theevnamespace. - Write kit 1.0.0 (data loading, host wiring, fallback rebuild from the frame) and
kit.test.js. - Implement
splice.jswith tests: single data block,<escaping,$in data, invalid JSON, missing or duplicate data block. - Implement
conformance.jswith tests againstfixtures/invalid/; run it on open; refusal dialog with "Copy report" and the Chrome hint. - Implement
protocol.jsandsecurity.js; verify that a document cannot navigate, open windows, reach the network or readfile://. - Implement
preload.js, thedoc:save-datahandler with change counter, andwrite.js(version store, temp file, rename). - Add the menu (Ctrl/Cmd+S →
doc:request-save), dirty marker in the title and the close prompt. - Implement
watch.js: section hashes, auto-reload on behaviour change, conflict prompt on data change. - Adapt
hours-sheet.htmlto the specification (frame, sections, kit,evnames, no own Save button under the host) and use it as the first fixture. - Walk through the acceptance criteria in the user story.
M1 passed its acceptance criteria on 2026-10-07. M2 passed its acceptance walk-through on 2026-10-09, results in docs/plans/m2-workspace.md; M3 passed its acceptance walk-through on 2026-10-10 (Windows by hand still open), results in docs/plans/m3-distribution.md.