Readout 3.3.0

3.3.0

Readout 3.3 fixes what got in the way of reading, makes opening agent documents more dependable, and refines the typography.

Fixed

Following and reading position

• When you are at the end of a document, Readout follows the agent again as it appends, even when it adds a long section.
• Your place is kept when the paragraph you were reading is deleted, when you change the text size or width or resize the window, when the appearance switches between light and dark in a document with diagrams, when the "rewritten" notice disappears, and after printing.
• N and ⇧N land on the change in long documents. Section links and the outline no longer place the heading under the toolbar, and the outline highlights the section you jumped to.
• Very tall blocks (long code, large diagrams) are marked read once you have seen enough of them.

Change marks

• A document that grows a lot, such as an outline the agent fills in, is no longer treated as rewritten: every addition is marked.
• A file briefly emptied and written again (as some scripts do) no longer shows everything as new.
• Task boxes ticked while Readout was closed are marked when you open the document again. A document rewritten while Readout was closed now says so.
• Large rewrites of long documents no longer freeze the window for seconds.
• An open "removed text" popup stays open while the agent keeps writing.

Live updates and opening

• Files under /tmp and other temporary folders now update live. Files on network volumes are checked reliably.
• A symbolic link such as latest.md follows its new target when the link is changed, and keeps its reading history.
• What you had read in the last seconds before quitting is no longer lost.
• A window whose first read failed loads the file once it becomes readable.
• readout -b and the Claude Code hook no longer switch the tab you are reading. When more than three new documents appear at once, Readout now opens the newest one instead of none.
• Paste, cut and undo work in the Find field. Find finds text anywhere in long documents.
• Settings says when another app already uses the global shortcut.
• The update check runs while Readout stays open, and turning it on takes effect immediately.

Rendering

• Inline math and footnote references work in nested list items. Display math $$…$$ works inside lists and quotes and right after a line of text.
• Dollar signs in links (such as ?$filter=) no longer turn into math, and \[WIP\] stays text.
• A </details> that is not on its own line no longer hides the rest of the document.
• Images with ?raw=true or #gh-dark-mode-only, and local images written as HTML, now show.
• Reference-style links follow their definition when it changes.
• Version strings such as react@18.3.1 are no longer email links. Section links match GitHub's for headings with code. Files saved as UTF-16 open correctly.
• Copying text no longer includes §, code language labels or button text.
• Printing in dark mode prints dark text on white, diagrams included.

Improved

• Diagrams keep their natural size: no longer blown up in wide windows or shrunk to unreadable in narrow ones; very wide diagrams scroll sideways.
• Brackets at the start of code blocks, table cells and paragraphs no longer stick out into the margin.
• More even spacing: headings in the middle of a document, code blocks and tables inside lists, rules and the footnotes section.
• Chinese and English mixed in one list keep a consistent line height. Japanese text uses Japanese glyph forms.
• Long URLs wrap instead of making the page scroll sideways. Inline code keeps its shape when it wraps. Wide tables show that they scroll.
• diff code blocks shade added and removed lines across their full width. The code block toolbar no longer covers code.
• The section link and change bar line up with the heading text. Highlighted text and keyboard keys have proper styles.
• Better contrast for tip and warning titles, front matter and code comments in light mode.

Readout 3.2.0

3.2.0

Readout now opens what your agents write without being asked, and without getting in your way.

New

• New documents open on their own. When an agent creates a new Markdown document in one of the folders listed in Settings (Claude Code's ~/.claude/plans is there by default), Readout opens it in the background, as a tab behind the one you are reading. Edits to files that were already there, such as a README, do not open anything. A burst of new files opens at most three, and a file you close does not reopen until Readout is relaunched. Nothing to install or turn on.
• A new icon.

Improved

• Readout no longer takes focus on its own. A document that opens by itself leaves your terminal in front and the document you were reading selected, and readout -b (or open -g) now really keeps Readout in the background.
• D now walks down the screen: each press opens the next closed comparison in view, and once all of them are open, the next press closes them.
• Korean text stored with separate jamo (as some tools write it) compares syllable by syllable in the word-level change view, like other Korean text.
• Install Command-Line Tool is gone from the menu: agents need no setup, since watched folders are enough. The readout script is still inside the app; the README shows how to link it if you want it.

Fixed

• In large documents, a link to a heading or footnote in the same document sometimes did nothing when clicked right after scrolling; clicking a tick on the change rail could do the same.

Readout 3.1.0

3.1.0

Readout gets simpler, renders more of GitHub-flavoured Markdown the way GitHub does, keeps up with large documents, and now shows exactly which words an agent changed.

New

• See what changed in a paragraph. Click the bar beside an edited block, or press D, to see the words that changed since you last read it: removed text struck through, added text highlighted. Chinese, Japanese and Korean compare character by character. Click again to hide it. Your reading position does not move.
• Removed text in full. The marker left where text was removed now opens to the whole removed passage as you last read it, not just its first lines. (Very long passages are cut at 200 KB; for long blocks you read before updating to 3.1.0, only their start was kept, and the marker says so.)
• Footnotes. [^1] references and their definitions render as on GitHub: numbered in order of first reference, with links to the note and back (one per reference), in a notes section at the end.
• Collapsible sections. <details> with Markdown inside renders as one block that folds and unfolds, code and lists included.
• More links. www. addresses and email addresses become links, as on GitHub.
• Code wrapping. A Wrap button on code blocks wraps long lines; the choice is remembered and applies to every window.

Improved

• Large documents update much faster: only the part of the file that changed is parsed again (a 1 MB file updates in a fraction of the time it took).
• Large documents (over a few hundred blocks) look the same as small ones: block spacing no longer widens, and change marks, section links and list numbers are no longer cut off at the left edge.
• Tables that fit keep their header row in view while you scroll through them, just below the toolbar; wide tables keep their first column in view while you scroll sideways.
• Mermaid diagrams use the page's colours in light and dark mode; a diagram that cannot be drawn says why and shows its source.
• Chinese text: stricter line breaking around punctuation, and doubled spacing between adjacent full-width punctuation is trimmed.
• Long file paths and identifiers in inline code wrap inside the text column instead of running past it.
• Printing: no interface elements, wrapped code, folded sections printed open, and tables, code and diagrams are not split across pages.
• A block that is edited and then changed back to what you read is no longer marked as changed; a checkbox you have not seen ticked stays marked.
• Simpler window: word count and reading time are gone from the subtitle and sidebar (the subtitle shows task progress when the document has tasks), and the welcome window no longer lists recent files — they remain in File ▸ Open Recent.

Fixed

• Code blocks were occasionally coloured entirely as a comment; highlighting is now the same every time a document opens.
• The update check no longer treats a pre-release as newer than its final release, and offers the final release to someone on a pre-release.

Privacy

• Remote images that you load by clicking are refused as soon as they exceed 20 MB, before they finish downloading, and images whose address is localhost or on your local network, or whose name looks up to such an address, are not fetched.

Readout 3.0.1

3.0.1

A correctness and privacy hardening release. No new features, no format
changes — everything below is a fix verified by the new release pipeline
(signed-product smoke tests, WebKit patch-engine tests, Core unit tests).

Fixed

• Document headings such as ## Notice no longer inherit the reader's own
  element styles or steal #fragment links; interface ids now live under
  ro-, and ro--prefixed slugs gain an h- prefix (#3).
• "Show Only Changes" keeps the reading position: hidden blocks no longer
  break anchor capture/restore, and the resize compensator no longer
  double-corrects filter reflow (#4).
• Writes that land during the first load are replayed right after the
  initial patch instead of being lost until the next write
  (#6).
• Resume prefers the excerpt match nearest the saved position when several
  blocks look alike (#6).
• Word count and reading time cover prose blocks only (code, math,
  diagrams, raw HTML and front matter excluded); don't counts as one
  word; timing is mixed-pace Latin 230 wpm + CJK 450 cpm
  (#6).
• Background update checks never pop up: they add a menu item that opens
  the release page; the manual-check dialog shows plain-text notes with a
  "View Full Release Notes" button (#6).
• The Welcome window height follows the recent-file count instead of
  jumping between two fixed sizes; change-rail buttons use localized
  labels (#6).
• Heading-id collision tests now also assert alignment-sensitive styles,
  and the fragment test starts scrolled at the bottom
  (#6).

Privacy

• The renderer Content-Security-Policy allows no http:/https: sources
  at all: background images, video posters, SVG images, image inputs,
  table backgrounds and srcset candidates can no longer phone home at
  render time. Remote images load only on click, downloaded by the app
  without cookies (15 s timeout, 20 MB cap, image/* only); video/audio
  open externally; Quick Look never loads remotely
  (#5).
• The in-app privacy wording is now exact: nothing is fetched at render
  time; the only automatic networking is the weekly update check, which
  can be turned off in Settings (#5).
• HTML sanitizing neutralizes navigation-capable tags (meta refresh,
  base, form, link) so they cannot survive parsing
  (#7).

Process

• Releases now ship only the verified signed artifact: Release build +
  ad-hoc sign + boot from /Applications + smoke assertions + Quick Look
  check, published as draft, re-download-verified, then undrafted
  (#1).
• Preflight gates every release on tag format, strict semver growth,
  release notes, MARKETING_VERSION, tag-on-main, and green CI on the
  tagged commit; manual dispatches only re-run existing tags
  (#1, #2).
• v1.0.0 (which crashed at launch inside dyld) carries a do-not-use
  warning and no longer offers downloads.

Readout 3.0.0

3.0.0

Focus on what's new: filter the document to unread changes, see reading
cost at a glance, link straight to a section, and resume where you left off
even after heavy agent rewrites.

Show Only Changes (⇧⌘K). A View menu toggle (and toolbar-adjacent
keyboard shortcut) hides every block already read; headings stay visible as
context. The rail, N/⇧N jumps, and the "All caught up" empty state all
respect the filter, and silent re-renders (checkbox toggles, CJK class
changes) no longer disturb it. Covered by patch-engine tests (filter, link
button, silent re-render, restore).

Word count and reading time. The window subtitle shows
"1,234 words · 3 min read" when a document has no task list (CJK characters
count individually, Latin text counts words), mirrored in the sidebar
footer. New ReadingStats core unit with tests.

Section links. Hovering a heading reveals a § button that copies a
filename#anchor link to the clipboard (native copyLink message path,
localized tooltip).

Recent files on welcome. The welcome window lists the five most recent
Markdown files with icons and parent-folder hints for one-click reopening
(existing files only).

Excerpt-anchored resume. The saved reading position now stores the top
block's first 120 characters alongside the baseline; on reopen the excerpt
is matched first (prefix, then containment, then half-excerpt fallbacks via
new ExcerptAnchor core unit), with the legacy block index as fallback for
older records. Scroll-only saves still skip unchanged baselines.

Docs. docs/design.md documents the focus-and-resume behavior; README
(EN + zh-CN) gains the new capabilities and shortcut. Chinese localization
at 100% for the new strings.

Ad-hoc signature (no Developer ID): first launch needs
System Settings → Privacy & Security → Open Anyway, as before.

Readout 2.0.0

2.0.0

Link navigation that lands where you meant, follow semantics that respect
where you are, and a full review pass over code, docs, and signing.

Cross-file links with fragments. other.md#section now opens the file
and scrolls to the section; #section in the same document scrolls in
place. Fragment matching is GitHub-style (percent-decoding, case-insensitive
slug fallback), and a link-opened file's fragment wins over the restored
reading position.

Follow semantics. Sitting at the end of a document still follows the
agent like a terminal — but only when the change is at or below the
viewport. An insertion at the top no longer yanks a bottom-dwelling reader;
the reading anchor is restored instead. Covered by patch-engine tests
(insert order, anchor stability, top-insert vs append, fragment scroll).

Stability under rapid writes. Overlapping parses from fast successive
writes are coalesced: one in-flight parse, queued completions share a
generation, stale results are dropped, and a write that lands mid-parse
triggers exactly one follow-up read from disk.

Review batch.

• Failed background update checks no longer push the weekly timer forward —
  one offline launch used to silence updates for another week
• Change-rail ticks are exposed to assistive tech (labeled buttons in a
  navigation landmark, not aria-hidden)
• Settings, Welcome, and sidebar strings all localized; Chinese coverage 100%
• Drag-and-drop and file opening accept Markdown files only
• tools/sign.sh drops dead Sparkle special-casing; the inside-out
  same-identity signing that fixed the 1.0.0 launch crash is unchanged

Docs. Release notes for every version live under docs/releases/.
Ad-hoc signature (no Developer ID): first launch needs
System Settings → Privacy & Security → Open Anyway, as before.

Readout 1.0.1

1.0.1

Fixes the launch crash from 1.0.0 and a batch of correctness issues.

Launch crash (1.0.0 regression). 1.0.0 shipped Sparkle signed ad-hoc while
its embedded XPC services carried mismatched identities — dyld refused to load
the framework and macOS reported the app as incompatible. Sparkle is removed;
updates are checked against the GitHub Releases API (menu item and Settings
toggle kept, no bundled updater code, nothing to sign).

• Update check: manual (Readout → Check for Updates…) plus a weekly
  background check, both with English and Chinese UI
• Release workflow no longer pretends to sign/notarize without a certificate

Correctness.

• Heading anchors are now unique even when a literal Notes-1 heading
  collides with a repeated Notes (TOC jumps land on the right section)
• Raw-HTML remote media (<img>, <video>, <audio>) goes through the same
  click-to-load gate as Markdown images — documents can't phone home on open
• Autolinked URLs keep balanced trailing parens
  (…/wiki/X_(film) links fully)
• \[…\] display math renders; ```math vs ```latex intent clarified
• Editor links escape ?/# in file names; readout CLI handles --named files
• File watcher no longer aliases files that differ only by case
• Change rail ticks are real buttons with VoiceOver labels
• Baselines store a 500-char similarity excerpt (was 2000); scrolling no
  longer rewrites an unchanged baseline file

Docs. Keyboard table lists ⌘]/⌘[; design notes describe the 1:1 edit
rule, the real baseline format, and the media privacy gate. The app no longer
claims the default Markdown handler role (Alternate).

Readout 1.0.0

This build crashes at launch. Do not use it; install 3.0.1 or later.

First release.

• Live reading of Markdown files that agents are writing, with the reading position kept in place
• Change marks relative to what you have read, with N / ⇧N navigation and ⌘K to mark all read
• GitHub-flavoured Markdown, Shiki code highlighting, KaTeX math, Mermaid diagrams, GitHub alerts
• Outline sidebar with per-section task progress
• Global shortcut (⌥⌘R) to open the newest Markdown file in your agent folders
• Quick Look extension
• readout command line tool, including readout --hook for Claude Code hooks
• English and Simplified Chinese