Web App

SnapTeX Web uses CodeMirror for editing and the shared SnapTeX preview runtime for rendering. The editor, preview, project explorer, settings, and split-pane layout all run in the browser.

No account is needed for local folders, imported workspaces, or the demo. Authentication appears only when a server-enabled deployment opens a remote project.

Welcome page choices

Action	Result	Save destination
Open Folder	Uses a browser-granted directory handle	Selected local files
Import Folder	Copies supported files into a browser workspace	IndexedDB
Open Demo	Creates/reopens the bundled example workspace	IndexedDB
Open Server	Opens a named project in a server-enabled deployment	Authenticated remote project API

The static public edition keeps the Open Server entry as deployment guidance but does not call a missing project API.

Choose by desired storage behavior:

1. Use Open Demo when learning the interface.
2. Use Open Folder when edits must write directly to an existing directory and the browser supports directory handles.
3. Use Import Folder when you want broad browser compatibility or an isolated browser copy.
4. Use Open Server only on a server-enabled deployment when files should remain on that server.

Opening and importing are not equivalent. Open Folder keeps a live browser-granted handle; Import Folder copies files into IndexedDB.

Open Folder

In browsers that implement the File System Access API, Open Folder keeps handles to the selected local directory. Saving writes the changed text back to the selected files after the browser grants permission.

This option is hidden when the browser does not expose directory handles.

Opened folders appear in History when the browser permits directory handles to be stored. SnapTeX stores the handle, not a copy of the directory; the browser may ask for file permission again when a historical entry is reopened.

Import Folder

Import Folder copies supported project files into an IndexedDB workspace. It works independently of direct folder-write support and avoids turning every save into a download.

Imported workspaces:

• persist after closing the tab;
• keep a distinct generated project ID, so folders with the same name do not overwrite each other;
• can be reopened from History;
• can be re-imported with conflict detection;
• can be exported as ZIP.

Browser storage can still be cleared by the user, private-browsing policy, or storage pressure. Export important work regularly.

Re-importing a folder creates or updates a browser workspace through conflict detection. It does not grant write access back to the original directory.

Demo workspace

The bundled demo is imported into the same browser workspace store. It is not a writable server directory and does not require a login.

Changes are saved to the demo's IndexedDB workspace, so Ctrl+S does not download a file. Use Export ZIP when you want a portable copy.

Project history

History is one list of recently opened projects, regardless of how they were opened:

• imported projects and the demo reopen their IndexedDB workspaces;
• local folders reopen a browser-stored directory handle and may require renewed permission;
• server projects reopen by project name and still require a valid server login.

The preview root and active editor file are remembered separately for each project and restored the next time it opens. Local and server history entries contain only their source reference and these project-relative paths, never project-file copies or login credentials. Forget removes only the history entry. Delete on an imported workspace removes its browser-managed project data, so export important work first.

Static and server editions

The same UI supports two build modes:

• static enables local folders, imports, project history, demo, ZIP export, and offline PWA use;
• server adds authenticated named projects through the same-origin project API.

The server process corrects the deployment marker in served HTML from its actual project API configuration, so the UI cannot accidentally present a static-only state when remote projects are enabled.

Offline behavior

The static build installs a service worker that caches application assets. Open the app online once and allow the first load to finish before relying on offline use. Local and imported projects remain browser-managed data and are not uploaded by the static edition.

Remote server projects require a network connection to their server even when the application shell is cached.

Workspace layout

The top toolbar stays hidden until you move a mouse or hover-capable pen over the top edge, or tap that edge with a finger. Mouse and pen hover menus close when you move away; touch-opened controls stay available until you tap outside. The same behavior applies on desktop, tablet, and phone layouts.

Explorer floats above the workspace without resizing either panel. Collapsing an editor or preview panel leaves only its restore button at the edge, with no persistent divider line. The button dims when idle and changes vertical position about every 90 seconds to reduce static display exposure. Hovering, pressing, or focusing it restores its opacity and pauses movement; the system's reduced-motion preference disables movement.

The toolbar's full-screen button expands the workspace to fill the display. Use it again, or press Esc, to leave full screen. The button is shown when the browser supports the Fullscreen API.

Remote changes and conflicts

An open server project receives Server-Sent Events (SSE) from a shared filesystem watcher, rather than polling its manifest. SnapTeX downloads changed text files conditionally using their ETags. Local folders use a browser filesystem observer when available, or check file metadata every five seconds while the tab is visible.

Only files already opened or read by the preview are checked in local folders; unrelated notes and unused resources stay unread until needed. Opening a local folder still lists its filenames for Explorer, without loading every file's metadata or contents. Like server projects, local folder discovery skips hidden entries and node_modules; independent subdirectories are scanned with bounded concurrency. Explorer starts with all folders collapsed and creates file rows only while visible.

Temporary failures do not discard pending changes: server reads retry with increasing delays, and local observer failures are retried while the tab is visible. Each retry reads the latest file content rather than replaying the failed snapshot. A failed file read retries that file without downloading the full project manifest again. Server reconnection, restored connectivity, or returning to the tab triggers a fresh revision check to catch up missed updates. Successful recovery stops retries; normal server synchronization remains notification-driven.

Local monitoring also checks once after starting, to catch edits made during project loading. A failed file does not prevent other changed files from updating. Remote text and manifest reads have a 30-second timeout, and closing the project cancels outstanding watcher requests and retries.

File synchronization and preview rendering are separate: a missing or unreadable image/PDF is reported without blocking the surrounding text. Binary file notifications refresh matching images/PDF canvases and their cached heights, or an open PDF and its SyncTeX sidecar; they do not replace editor text or its undo history. Resources that have not been requested remain lazy.

Requested resources are read completely before updating their preview URL. Temporary network or file-read failures retain the last usable resource and retry the latest file through the existing watcher. Missing files and denied access are reported without automatic read retries. Once bytes have been received, invalid image/PDF data is a decoding/rendering error: no retry is scheduled until another file change. Unexpected TeX-rendering failures are diagnosed and reset the renderer for its next request, rather than requeueing delivered text.

SnapTeX keeps the last synchronized text as a merge base. A server change replaces an unchanged browser copy directly, and edits made to different lines are merged automatically. If browser and server edits overlap, the editor displays LOCAL, BASE, and REMOTE conflict markers and the Diagnostics panel reports the affected path. Resolve and remove those markers before saving.

Remote saves use the file's ETag as an optimistic lock. If the server changes after the latest check but before a save, the server rejects the stale write and the same merge process runs; the browser never silently overwrites the newer server text.

The same saved-text baseline is checked before writing local folders and IndexedDB workspaces. External text updates apply a minimal editor change instead of reloading the file, preserving the selection and undo history.

Automatic saving

Settings > Auto save is enabled by default. Save delay (s) defaults to one second: every edit restarts the delay, and saving happens only after you stop typing for that long. This is event-driven, not periodic polling. SnapTeX writes only changed, writable text files to their source: the server's disk for server projects, the local directory for local folders, or IndexedDB for browser workspaces. Manual Ctrl+S saves immediately through the same queue. These settings are shared across projects and remembered by the browser.

Non-overlapping changes merge before saving. Overlapping changes insert conflict markers and block saving until they are resolved. Local folder checks are best-effort: browser file APIs cannot atomically compare and replace a file while an unrelated disk process writes it. Imported/demo workspaces check their version in an IndexedDB transaction, and the remote API serializes version checks and writes from browser clients.

Browser capability summary

Capability	Direct folder	Imported/demo workspace	Server project
Works without directory-handle support	No	Yes	Yes
Writes to an original local directory	Yes	No	No
Persists after closing the tab	Browser permission dependent	Yes, in IndexedDB	Yes, on the server
Works fully offline	Yes after the app shell is cached	Yes after the app shell is cached	No
Portable backup	Copy the directory	Export ZIP	Server backup policy

Next

• Read Projects and Files for root selection, saving, and supported file types.
• Read Static Web and PWA to deploy a browser-only edition.
• Read Deployment Overview before enabling remote projects.