Skip to content
xus-stuPublic

About

Zero-dependency RTF / TXT / Markdown reader with a native macOS app (WKWebView). No build step, no node_modules.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

21 Commits

Folders and files

Repository files navigation

DocViewer

DocViewer

An offline multi-file reader for RTF, TXT and Markdown, plus a native macOS app.

The front end is plain HTML, CSS and JavaScript and runs straight from index.html. A small Swift shell wraps it into an ordinary .app with a native window, a native file picker and the ability to write edits back to the source files.

There is no build step, no bundler, no node_modules and no third-party runtime code. Nothing is uploaded anywhere.

Quick start

git clone https://github.com/xus-stu/DocViewer.git
cd DocViewer

open index.html                      # browser path, no build step
# or
./run.sh

# native macOS app
./packaging/mac/build_native.sh ~/Desktop
open ~/Desktop/DocViewer.app

Requirements: any recent browser for the browser path; macOS with Xcode Command Line Tools (swiftc) for the native app; Python 3 with Pillow only if you want to regenerate the icon.


Features

Files and browsing

  • .rtf, .txt, .md, and common source or config files (.java, .kt, .py, .js, .ts, .go, .rs, .c, .cpp, .cs, .swift, .rb, .php, .sh, .sql, .html, .css, .json, .xml, .yml, .toml, .gradle, .properties, …). Source files are shown as plain text.
  • Plugins: every folder in the plugin directory is a plugin. Write it in JavaScript (add toolbar buttons, side panels, settings sections, or change easing curves and animation durations) or in Python / any language that speaks line-delimited JSON over stdin/stdout. Settings has import (.zip or folder), per-plugin switches and rescan; enabled plugins load automatically on every launch. See docs/plugins.md
  • Read-only previews for images (PNG / JPEG / GIF / WebP / TIFF / BMP / HEIC / SVG), PDF, Word (.docx / .doc) and Pages (.pages). These types have no editing and no write-back - they are there to be looked at.
  • Open several files at once, import a folder recursively, or drag files and folders onto the window. Directory packages such as .pages are picked up as a single document instead of exposing their internal files.
  • The sidebar lists files with a type icon, size, type label, a delete button on hover and a name filter. Selecting and switching only rewrites class names in place, so the list is not rebuilt and no entry animation replays.
  • The sidebar can be collapsed on its own (⌘B, the ‹ button, or the settings panel) and leaves a handle to bring it back. The state is remembered.
  • Session memory: reopening restores the previous file list and text. Each file can also remember its own reading position.

Merging files

Several files can be combined into one reading view for cross-reading or comparison. The original files are never touched.

  1. Select two or more files in the sidebar (Ctrl/⌘ click, Shift click, drag rows to reorder).
  2. Click "Merge into one" on the selection bar, or press ⌘M.
  3. A merged entry appears and the source entries fold away. Nothing on disk changes.

The merged view supports segment headings, jumping between segments (Alt+← / Alt+→), copying the combined text, exporting HTML, and splitting back into the original entries. Merges can be nested and can mix Markdown, text and RTF.

A merged entry holds references to the original entries and builds its HTML at render time. It does not copy the text and does not write to disk. The session stores the sources as well, so after reopening the merged view still has its segments and can still be split.

Formats and encoding

Format Handling
.md Built-in renderer: headings, lists and task lists, tables, quotes, code blocks with language highlighting, links, images, rules, table of contents
.rtf Built-in parser: font and color tables, bold / italic / underline / strike, super and subscript, font sizes, foreground and background colors, alignment and indents, \par \line \tab, lists, simple tables, \'hh and \uN escapes
images Scaled to the window width; click to toggle fit-to-window / actual size; pixel size under the title
.pdf Rendered page by page with PDFKit, only when scrolled into view, with a short page cache
.docx / .doc The page unpacks the ZIP and parses word/document.xml itself: headings, paragraphs, bold / italic / underline / strike, colors, alignment, lists, tables, super/subscript, and embedded images (relationships + media → data URLs, sized from the EMU extents). .doc and parse failures fall back to a Quick Look preview image. Body text uses the reader font and size by default (heading levels are kept); the setting turns that off to follow the document layout
.pages Rendered through the system Quick Look generator (modern Pages files are directory packages too); if that fails, the preview.jpg embedded in the file is used
others Monospaced plain-text view

Images, PDF, Word and Pages are preview-only: no caret, no search, no merging, and nothing is ever written back.

Encoding is detected by trying, in order: BOM, strict UTF-8, GB18030/GBK, Big5, Windows-1252. If everything fails the file is opened as non-fatal UTF-8, so a file always shows something instead of an error.

RTF \'hh bytes follow the code page declared by the file:

  • \ansicpg936 is decoded as GBK, 950 as Big5, 932 as Shift-JIS, 1252 as CP1252.
  • Without \ansicpg, the font table's \fcharset decides: 134 is treated as GBK, 136 as Big5, 0/1/2 as 1252.
  • If neither is present, 936 is assumed.
  • Under a multi-byte code page, bytes that do not form a valid sequence are dropped. They are never reinterpreted as CP1252, which would turn a stray \'97 in a cp936 file into an em dash inside Chinese prose.

Consecutive \'hh escapes are collected into a byte sequence and decoded as a whole, because GBK and Big5 are multi-byte encodings and per-byte decoding only produces U+FFFD.

Editing (off by default)

The default mode is read-only: no caret, and no file is ever modified. Switching to Editable makes the text editable in place; about 1.5 minutes after you stop typing the change is written back to the source file. You can also click Save in the toolbar to write immediately. A .bak copy is created on the first write. Writing back never re-renders the document, so the scroll position and the caret stay where they are.

  • RTF is edited as rich text and serialized back on save. The font table, color table and stylesheet at the top of the file are preserved, the body reuses the file's own \fN / \fsN, and Chinese is written as \uN?.
  • Text and source files are edited as plain text and written back in the file's own encoding.
  • Markdown is not editable and always keeps its rendered view.

Appearance and settings (⌘,)

Group Contents
Language Chinese / English. Interface text, status bar and debug panel labels all follow.
Theme Dark, Blue, Green, Light, Sepia and Custom, applied as a whole set
Custom takes four base colors (background, panel, text, accent) and derives the rest with color-mix()
Accent color, text color and reading background can each be picked from eight swatches; the reading background only affects the reading area
Body, secondary and faintest text of all five palettes pass WCAG AA, with regression tests
Fonts System, Songti, Kaiti, Heiti, Yuanti, monospace, custom, plus eight Western fonts
Typography Font size 11–30px, line height 1.3–2.6, column width 520–1200px, padding 0–80px, all live
Documents Remember session, remember the reading position of each file, use the reader's font and size for RTF, follow the source line breaks in RTF
Editing Read-only / editable; the switch and the Save button live in the settings panel and toolbar
Title bar Whether to show the top title bar, and which fields appear under the file name (path, size, encoding, type, lines, characters)
Focus mode Toggle and column width
Animation and frame rate Animation level, speed, frame-rate cap, plus live readings
Tools Debug panel, diagnostics report, export the current file as HTML, reset to defaults

Settings live in localStorage and the panel has a Reset. Visual settings are written as CSS custom properties and body[data-*] attributes, so theme, font and colors combine freely and switching them never rebuilds the document.

Remember the reading position of each file is on by default: reopening a file, or restarting the app, returns to where you left off, in read-only mode as well. Writing back never re-renders the document, so the position and the caret are left alone. Turning the setting off always starts at the top.

Focus mode

Hides the title bar, sidebar, toolbar and status bar and leaves only the text with extra vertical padding. Moving the mouse reveals a floating control strip (progress, previous and next file, font size, exit) that fades after 2.2 seconds. Use its exit button, or the Focus button in the toolbar, to return.

F3 debug panel

Press F3 (or ⌘D, F12) to open the right-hand drawer. Four tabs:

Tab Contents
Performance Frame-rate graph, display refresh rate, average frame interval, worst frame, dropped frames, scheduler probe, render time, DOM node count, JS heap usage, page uptime
Document Name, path, type, bytes, encoding, lines, characters, parse and injection timings, view mode, font size and wrap state, parser warnings
Environment User agent, language, platform, CPU threads, window and screen size, DPR, color depth, Web API support, GBK decoding, startup and ready timings
Log Timestamped, leveled log with auto-scroll, copy and clear

On frame rates: requestAnimationFrame is tied to the display refresh rate, so a 60Hz screen only produces 60fps. The animation loop is therefore driven by setTimeout(1000/cap) while requestAnimationFrame only samples the delivered rate. The 120, 180 and 240 caps really do run at those intervals; the screen still shows about 60 images per second and the benefit is a finer time step for easing and scrolling. Measured CPU use was 7.9% at 60fps and 8.1% at 240fps.


Keyboard shortcuts

One shortcut:

Key Action
F3 Open or close the debug panel

Everything else is a button in the interface (toolbar, top of the sidebar, settings panel), so typing in the document can never trigger an action by accident. The old unmodified keys were removed for that reason: a single n used to jump to the next file.

Command line

Flag Meaning
--theme=<id> Start with dark, blue, green, light, sepia or custom
--lang=zh|en Interface language
--edit=ro|rw Start read-only or editable
--fps=<n> Frame-rate cap
--w/--h, --x/--y, --br/--bl Window size and position; the default is 75% of the screen, centered
--debug / --settings / --plugins Open the debug / settings / plugin section on launch
--wipe Clear local data, as if launched for the first time

A document path can be given directly, and open -a DocViewer <file> works too. The native shell only treats a positional argument as the web root when that directory actually contains index.html; otherwise it always uses the bundled web/.


Project structure

index.html              single-page shell (title bar / sidebar / content / debug drawer)
css/hmcl.css            theme variables and all component styles
js/util.js              namespace, inline icons, formatting, toasts, leveled log
js/i18n.js              Chinese/English dictionary and DOM re-translation
js/welcome.js           the two built-in first-run documents
js/frames.js            frame scheduler (timer-driven animation, rAF sampling)
js/settings.js          settings model, persistence, theme derivation
js/md.js                Markdown renderer
js/office.js            Word (DOCX) and ZIP parsing for the preview
js/rtf.js               RTF parser and the serializer used for write-back
js/debug.js             F3 panel
js/ui-settings.js       settings panel and focus mode
js/plugins.js           plugin system (scan / load / API / manager UI)
js/app.js               file list, decoding, rendering, merging, editing, shortcuts
plugins-sdk/dvplugin.py Python plugin SDK (shipped with the app, `import dvplugin`)
examples/               sample documents and the two example plugins
docs/plugins.md         plugin format, API and wire protocol
examples/               sample files
packaging/mac/          Swift shell and build script
packaging/make_icon.py  generates the whole icon set
tests/                  Node test suites and the native writer test

Tests

node tests/parse.test.js      # parser            (144 assertions)
node tests/smoke.test.js      # whole app         (556 assertions)

# everything at once (parser + app + native writer)
bash tests/run-all.sh

No test framework: plain Node scripts. smoke.test.js contains a hand-written mini-DOM, so the real app.js runs inside Node and the suite covers startup, import, switching, search, merge and split, session persistence, encoding detection, editing rules, theme contrast and translation coverage. The native test covers encoding round-trips, backups and RTF byte preservation.

Implementation notes

  • The window takes 75% of the screen and is centered. setFrameAutosaveName is not used, so an old frame cannot override the default.
  • On first run, with no local data, two built-in documents are loaded: README(EN).md and README(ZH).md.
  • The native shell registers the docviewer:// scheme and serves the bundled assets through a WKURLSchemeHandler. Responses carry Cache-Control: no-store and the WebKit caches are cleared on launch, so edited CSS or JavaScript is not served from a stale cache.
  • A merged entry only holds references and builds its HTML at render time. Selecting or checking files rewrites class names instead of rebuilding the list.
  • The RTF parser splits text runs whenever the style signature changes or a group closes. \pntext only writes an internal marker; the <ul><li> structure is created when the text is flushed.
  • RTF line breaks: real files often contain no \par at all, only the editor's hard wrapping and bare newlines. Every source line break is emitted as <br> by default, and the setting "follow the source line breaks in RTF" switches back to the strict behavior.
  • The first color table entry in RTF is empty and means automatic. The parser stores it as null and emits no color, so the text follows the reader palette. Colors with less than 3:1 contrast against the reading background also fall back to the reader palette.
  • Markdown lists are parsed into a tree before rendering, which avoids invalid nesting from string post-processing.

Write-back safety

Editing only rewrites the body text, and these cases are blocked or protected:

Case Behaviour
The file has images, headers/footers, footnotes or fields (skipped by the parser, never in the DOM) Blocked by default, with a list of what would be lost; you can still pick "save anyway (loses content)"
The new content is empty but the file was not The native writer refuses (no truncating a file to zero bytes)
A backup cannot be written (permissions, .bak taken by a directory) Write is aborted, never an unbacked overwrite
Non-UTF-8 files (GBK / Big5 / UTF-16 / cp1252) Written back in the original encoding; an unknown encoding name is an error, never a silent fallback to UTF-8
Raw bytes in the RTF preamble Passed through byte for byte, an \ansicpg936 file is never re-encoded as UTF-8
The file changed on disk after it was opened Content hash is compared, so it is not blindly overwritten; you get "reload from disk / cancel / overwrite anyway"
A UTF-8 or UTF-16 BOM Preserved - the first save no longer strips it
A file with hard links Written in place so every link name sees the new content (the inode is not replaced)
Extended attributes (e.g. kMDItemWhereFroms) Copied over after the atomic replace
The target path is a symlink Resolved first, the link is not replaced by a regular file
Unsaved edits while re-rendering / closing / clearing the list / resetting / closing the window Flushed first

Two backups are kept: .bak is the original version from before the first write (written once), .bak.prev is the previous version of every subsequent write.

Known limitations

  • RTF covers the common subset produced by TextEdit, WordPad and Word. Fields, footnotes, headers and footers, embedded images and revision marks are skipped.
  • RTF tables only restore basic rows and columns; border styles and merged cells are ignored.
  • The Markdown renderer is deliberately small and does not resolve reference-style link definitions or math.
  • The Word preview does not show footnotes, headers/footers or revision marks; tables only restore rows, columns and column spans; images are limited to PNG / JPEG / GIF / BMP / WebP / TIFF / SVG (EMF/WMF vector images inside Word are skipped).
  • Word "Heading" styles are often used as plain formatting in exam papers and handouts, so a "heading" paragraph longer than 60 characters is laid out as body text; real short headings keep their level, and Word headings are rendered at a restrained ~1.3em instead of the reader's own h1 size.
  • Word text colours that "follow the theme" (w:themeColor) are ignored, and any other colour with less than 3:1 contrast against the reading background falls back to the reader palette so dark themes never produce invisible text.
  • The Pages preview is a whole-page bitmap generated by the system, so its text cannot be selected (Pages stores its body as protobuf).
  • Word parsing needs the browser's DecompressionStream (macOS 13.3+); older systems fall back to a Quick Look preview image.
  • Session memory keeps up to 8 MB per file and 64 MB per session; anything beyond that stays in memory only (it only affects "remember session" - opening and editing are unaffected). There is no limit on how many files you import or how large they are.
  • The macOS app is ad-hoc signed, so Gatekeeper warns on first launch. Right-click and choose Open, or run xattr -dr com.apple.quarantine.

License

MIT

About

Zero-dependency RTF / TXT / Markdown reader with a native macOS app (WKWebView). No build step, no node_modules.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages