Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Foundation H: retire Read while preserving text and shared audio foundations

Open
  • Is something wrong?
#284 3 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Active
Tech stack
swift
Domain
desktop

Research direction

Read the canonical brief at docs/mac-foundation.md and the decision in PR #278 first. Then trace the named entry points, especially AppModel, Core.swift, VoicePreferences/main.swift, and scripts/release/preview.py; follow actual callers rather than filename matches. Run the affected tests and packaged-bundle checks. Done means Read is removed, dormant state and exact legacy text are preserved, and the listed shared audio, Dictate, and prompt-insertion behaviors still work.

Written by the indexing model from the issue text.

Description

Retire Read, Workbench's owned text-to-speech capability, from the focused Mac product. This is the decided result of the adversarial review in PR #278, not another Read refinement or an assertion that all its existing code is broken. The ordinary listening job has a capable native Mac route; a distinct recurring Workbench listening/export job has not been established. Package H remains under #7.

Removal boundary

  • Read is route speak, toolbar .read, shortcut id 6. Remove its page/sidebar, panel/toolbar/current-work entries, Window menu, shortcut catalogue and registration of previously enabled keys. Safely translate old toolbar modes/routes. Do not renumber other shortcuts.
  • Remove contextual Read aloud from History, Library and assistant results. Keep visual answer inspection, labeled Review result, Copy, export and original records.
  • Remove selected-text Services registration/admission in both edition bundles. Update scripts/release/preview.py and its tests, which currently require that service. Keep general Services, signing and identity checks.
  • Remove TTS provider/voice/model-download setup and public promises. Stop startup/activation voice enumeration, TTS Keychain status probing, catalogue requests, neural discovery/load/download, preview, render/export and production developer-command admission. Stale callbacks/Services/preferences cannot restart it.
  • No Advanced Read switch, contextual-only TTS, replacement Listen tool, permanent legacy page or automatic invocation of macOS speech. Brief help may point to Apple's native Read & Speak and explain its differing selection behavior.

Preserve narrowly

  • Core.SavedState stores reading text/voice/rate alongside Dictate draft/original text, History, corrections and unresolved delivery. Keep compatible decoding and round-trip dormant fields.
  • For a nonempty old speechText, preserve the exact Unicode text in one ordinary Library-linked UTF-8 file, with idempotent identity, atomic writes and file/reference readback. Keep the original field. Do not truncate, normalize, overwrite Dictate, fabricate a transcript or duplicate the item on relaunch. A failed migration preserves source with a contextual Library retry; empty/fresh profiles get no legacy UI.
  • Read permits one million characters; Library prompts only 50,000. Use a file resource, not a prompt or new reading archive.
  • Keep explicitly exported audio files untouched. Generated audio is transient in inspected source; do not scan arbitrary folders or preserve every temp file. Use existing update/shutdown admission for owned generation/export and reject late completions.
  • Inert TTS preferences/keys/caches may stay without a management panel. Do not read/send/delete credentials as incidental cleanup. Cache deletion is optional and only the verified inactive Pocket TTS subtree, never the shared FluidAudio parent or system voices.

Shared foundations that stay

ReadbackModel/ReadbackView, route readback and shortcut id 5 are Snap & Talk, not Read. Keep them, Dictate/Meetings recognition, Parakeet/FluidAudio, original meeting/narration playback, VoiceOver, clipboard/text delivery and prompt insertion. The existing update-busy projection groups prompt insertion with reading; preserve the surviving guard. No broad audio/plugin-framework rewrite.

Starting points: AppModel, Core.swift, ReadSelectionService, WorkbenchHome/Views, WorkbenchControlTool/toolbar projections, HistorySelectionControls, DemoLibraryView, VoicePreferences/main.swift, ReadingProviderView/NeuralVoiceViews, scripts/Info.plist, scripts/release/preview.py. Trace actual callers, not filename matches.

Acceptance X3

Fresh and upgraded signed bundles have no Read action, provider work, model download or Service admission. Upgrade a fixture with enabled id 6, old toolbar mode, selected online/neural provider and a large Unicode draft; the exact text is in one normal Library file through two relaunches. Inject file/Library save failure and verify no false completion or source loss. Unrelated original text/history/recovery and exported audio remain intact. Dictate, Meetings original playback, Snap & Talk id 5, VoiceOver and prompt-insertion update deferral still work. Check actual packaged Service metadata, negative dispatch and late callbacks as well as registry/gallery. Replace obsolete feature-success tests with removal/preservation tests in the same bounded change.

Hold Read-only #267 from the refinement batch; preserve its history and independently useful shared fixes. Reconcile #17/#161/#173 as superseded Read acceptance or preservation work, never as fixed by documentation. Coordinate AppModel, Library, main and toolbar edits with #279/#280/#281; one writer per shared file. This can release independently once its affected acceptance passes and does not wait for Present hardware.

Decision and evidence: spec PR #278, canonical brief, adversarial research.

Dominant language
Swift
Stars
0
Forks
1
Avg merge
8h 5m
Merged PRs (30d)
215

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Ship-Work/workbench

All issues in Ship-Work/workbench

Similar issues

More Swift issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.