About

About these docs

How this documentation was produced and checked, what was tested, what could not be, and how to regenerate the screenshots.

These pages were written from the repository's source code, then checked by running the app. This page says how much each part can be trusted, and what is still unchecked.

How they were made#

1. Read the code. The routes, components, data model, templates, search parser and settings were read to build a feature list (see the feature inventory). A feature was only listed if its implementation exists, not because its button does.
2. Run the app. The web version was built (npm run build:standalone) and served locally, and the computer version was built and started with a temporary data folder. A script drove them in Chromium with Playwright: typing into the real note box, clicking real buttons, dragging on the real map canvas.
3. Capture. Every screenshot and recording on these pages comes from that run, not from mock-ups. Nothing in an image was edited except the annotations described below.
4. Write. Instructions were written from what happened, including surprises, which are documented as limits.

How the pictures are annotated#

The numbered orange boxes are drawn on the live page just before the screenshot is taken and removed straight afterwards, using the same colour and style everywhere. They mark the control a step refers to, and the caption lists what each number means. The two pictures that would show this computer's network address (the phone pairing code) cover it with a grey box saying so. Recordings show a small orange ring that follows the pointer. Their text equivalent is the numbered steps beside them. Each picture has alternative text, and each video has a label and a download link.

What was run#

• Writing and editing notes, all four pickers, flags, titles, dates, deleting and undoing, solving and reopening questions.
• Setting and moving the in-game date in both calendars; the calendar editor's refusal when dates would be stranded.
• Today, Day and Journal views and the filters; people (add, progress, notes, delete and restore); the Farm (add, harvest with count, plant again, entry page).
• Tags (create, rename into a merge, merge); search syntax (tag, person, phrase, exclusion, flags, in:, day, typo tolerance).
• Maps: creating, every drawing tool by keyboard, tidy-up, markers with details and linking, layers, view options, history, marker types, exploring mode, measuring, exporting PNG, SVG, PDF and the project file, re-importing it, duplicating, the Places list.
• Journals: creating, switching, the delete window. Settings: every section. Export and import (JSON and Markdown downloads read back), snapshot back-up and restore, Recently deleted restore.
• The computer version: the Phone section (switch, pairing panel), the data folder row.
• The web version: the storage-protection panel and the one-tab screen.
• Layouts at a wide, tablet and phone width.

The project's own automated tests (unit, component and end-to-end, including accessibility scans) are described in How it works. We read them to understand intended behaviour; we did not rerun the whole suite as part of writing the docs, except the build, type check, lint and format check listed in the repository's verification notes.

Where the app and its own text disagree#

Checking the app against its own words turned up these. They are documented here as limits rather than hidden.

• The changelog says questions can be "ignored"; the app has only open and solved (see Questions).
• Today focuses the note box at once, so the single-key shortcuts do nothing until you press Esc (see Shortcuts).

What could not be verified#

• A real phone. Pairing was checked from the computer's side only; scanning the code, using the app over the network and the Home Screen icon were not.
• Touch input. Pinch zoom, long-press names and touch menus in the map editor.
• Other browsers. Safari, Firefox and Edge; installing the web version; its offline use and update bar.
• Installing from the published package. Before it was published, the npm package was built, installed from its tarball into an empty project and run on macOS with Node 22.14 to 26. Windows and Linux were covered by the project's automated checks, not by hand, and the programs on the releases page are built by the release workflow. If a route here does not work for you, please tell us.
• GitHub Pages itself. The site is built with the project-site base path /mossnote/ and tested through a local server that answers like GitHub Pages (a missing address gets 404.html, a folder without a slash is redirected), in Chromium and in WebKit. That checks the base path, refreshing on a deep link, offline use and these pages' links. It is not the same as the live site: browsers other than Chromium and WebKit, and the live host's own behaviour, were not tested.
• Print output., very large journals and paging beyond 50 notes.
• The integrity-check failure path, upgrade snapshots, and the web version's backup reminder and update bar, which need a particular situation to appear.
• Restoring a map version, and the exact behaviour of changing a marker type after use.

Regenerating the pictures#

The pictures were captured from the running app with a script that is kept outside the repository. If the interface changes, they have to be retaken. After replacing the images in docs/assets, rebuild the site with npm run docs:build. See docs/README.md in the repository for how to add or edit a page.

Found a mistake?#

Please open an issue and say which page it is on. If the app behaves differently from these pages, one of the two is wrong, and either is worth knowing about.