OpenSpec Local Viewer

An offline-capable, single-page viewer for OpenSpec artifacts. It uses Plain Vanilla Web: no build step, no framework — plain HTML, CSS, and ES-module JavaScript served as-is.

Try it live: https://ypyl.github.io/openspec-viewer/

What it does

• Monitor one or more folders: add as many repository/openspec/ folders as you like from the rail (＋ button); each gets a colored avatar, its own file list, tabs, and unread state. A dot on an avatar marks a folder whose last read found unacknowledged changes. Re-picking the same folder is deduped; closing the active folder falls back to another one.
• Reload on demand + live refresh (Chrome/Edge): folders picked via the File System Access API are read when you open them and when you press the header's ⟳ Reload button. A reload re-reads only the groups you have expanded, plus the artifact you have open, so it stays fast even with a large archive. Expanding a collapsed group reads it, and that is where a change to an archived artifact surfaces. The artifact you have open is also watched on its own: edit its file and the view (or its diff) refreshes in place without a reload. Only that one file is read, so nothing else is walked.
• Change diffs: every read snapshots artifact content, so when the watcher or a reload detects a change you get a Diff button next to the breadcrumb with +/− line counts — click it to switch from the artifact to a line-by-line unified diff view (a NEW badge marks diffs you haven't seen yet). Snapshots live in IndexedDB, so diffs survive a page reload.
• Open a change to see its artifacts as tabs: Proposal, Spec(s), Design, Tasks, Metadata.
• Review mode: select text in an artifact and add a comment, or comment on the whole file from the artifact header; highlights are kept per file, then collected with the artifact content into a single LLM fix prompt (copy it or open it in a new tab). Each artifact kind shows a distilled Guide strip, and the review panel opens with the official two-minute checklist.
• Content search: the header search box is typo-tolerant full-text search (Fuse) over the active folder's artifacts, with a grouped results dropdown and in-file match highlighting. The sidebar's Filter files box narrows the current file list.
• Dark and light themes (follows the system unless you override), collapsible sidebar sections, and a per-folder unread/read marker.
• Everything reads locally — nothing is uploaded.

Using it

The app is served over HTTP(S) and loads as ES modules with a service worker, so it must be opened in a browser rather than from file://. Use the hosted version at https://ypyl.github.io/openspec-viewer/, or install it as an app (install icon in the address bar) so it runs fully offline.

1. Click the ＋ button in the left rail and choose a repository root or its openspec/ folder.
2. Open folders are remembered in IndexedDB and re-opened on your next visit (the last-active one becomes active), so a page reload picks up where you left off. The picker itself also reopens at your last-chosen folder.

In browsers without the File System Access API, the folder picker falls back to a one-shot read with no reload.

Local development

The app is a static multi-file site with no build step. Serve the folder over HTTP and open it in a browser:

python -m http.server 8743
# then open http://127.0.0.1:8743/

Architecture

• index.html — static skeleton (head meta, vendored UMD <script> tags, pre-paint theme bootstrap, component shells). Version lives in a comment at the top of the file.
• index.js — bootstrap: registers the web components and starts the app.
• index.css — root stylesheet; composes the styles/ sheets and each component's CSS.
• styles/ — reset.css, variables.css (theme tokens), global.css (layout).
• lib/ — vendored libraries: the Plain Vanilla Web libs (html-literal, tiny-signals) as ES modules, plus marked, js-yaml, DOMPurify, and Fuse as UMD builds loaded off window.
• app/ — logic modules: state.js (signals), store.js (folder registry + IndexedDB + File System + snapshots/scan), model.js (pure path/artifact classification), render.js, diff.js, annotations.js (review highlights/comments), review-guide.js (distilled review guidance), search.js (Fuse content search), prompt.js (LLM fix-prompt builder), testbridge.js (e2e test API exposed on window). store.js also watches the artifact on screen for external edits.
• components/ — web components (osv-*), each a folder with .js + .css: header, folder rail, file list, pane (tabs + artifact body), review drawer, search, loading overlay, toast, and the mobile navigation drawer.
• imports.js — centralizes module loads.
• sw.js — service worker (cache-name version tied to the app version).

Keep the version in sync across the comment at the top of index.html, the header badge (VERSION in components/osv-header/osv-header.js), and sw.js (CACHE_VERSION) when you ship a change.

Tests

• Node unit tests, zero deps — npm test (runs node --test tools/test-*.mjs): tools/test-model.mjs, tools/test-diff.mjs, tools/test-search.mjs.
• Playwright end-to-end tests against the served app (each stubs the File System Access API with an in-memory tree and drives the real pipeline): diff-test.js (scan → snapshot → diff → render), migration-test.js (IndexedDB v2→v3 upgrade keeps the saved folder), reload-test.js, scoped-read-test.js, auto-refresh-test.js, multi-folder-test.js, collapse-test.js, archive-read-test.js, mark-all-read-test.js, whole-file-comment-test.js, review-guidance-test.js, tab-nav-test.js, search-hotkey-test.js, mobile-drawer-test.js, panel-toggle-test.js.

Run a browser test with playwright-cli against python -m http.server 8743.