4.8 KiB
Screenreader Common
Shared Go packages for the Cthulhu and Fenrir screen readers. The packages contain reader-independent data and behavior; each reader owns its input, presentation, localization, and operating-system integration.
Emoji catalog
emoji.Categories() returns the bundled emoji picker categories and entries.
It returns independent slices so callers can build and modify their own menus.
Emoji sequences and English labels are catalog data; readers decide how to
translate labels and what to do when an emoji is selected.
Import git.stormux.org/storm/screenreader-common/emoji and call
emoji.Categories() to build a reader-specific picker.
The module targets Go 1.24 or newer and has no external dependencies.
AI-assisted contributions
AI-assisted contributions are welcome. The person submitting a contribution must review the diff and test the changed behavior and plausible regressions before submission. Do not submit automatically generated changes without human review. Check the maintained branch and whether the change is still needed before editing. Describe what changed, the tests run, and remaining live reader checks. Leave submission to the contributor after their review and testing.
License
GPL-3.0-or-later. See LICENSE.
Internal UI toolkit
internalui is the single reader-independent toolkit. Form has either
FlatForm (one page without a tab strip) or TabForm layout. Both use the same
Session, controls, editor, validation and speech/braille presentation.
Controls include entries, protected entries, lists, grids, checkboxes, buttons, numeric fields and combo boxes. Forms support groups, hidden draft controls, disabled controls, required fields, entry length limits and dynamic choices. List and category-arrow navigation stops at boundaries; Tab/Shift+Tab cycles through enabled visible controls in the current dialog/page. Home/End selects list or category boundaries. Lists and grids support Page Up/Down.
Entries support Unicode caret movement, Control+Left/Right word movement, Shift selection, select-all, and host-mediated copy/cut/paste. The host must write the clipboard successfully before deleting a cut selection. Password fields mask speech and braille, refuse copy/cut, and drop their text references on Close. Values and Focused_control may contain plaintext secrets: use them only for submission, never generic logging or persistence. Go strings do not provide guaranteed memory erasure. Clipboard I/O remains a host operation. Fenrir uses its clipboard history; Cthulhu uses its existing desktop clipboard.
NewSession accepts a session-local Messages translator. Literal choices bypass translation. Result contains speech, braille and cursor information alongside activation and clipboard requests. Presentation styles affect wording, not control behavior. Hosts call Close on cancellation, replacement and shutdown; the toolkit closes itself on Escape. Sessions belong to one event-loop/worker and must not be accessed concurrently without external serialization.
interaction translates the existing Cthulhu form protocol into this toolkit,
retaining JSON kinds and external input limits. Its NewUnifiedSession exposes
rich forms to core reader features; Cthulhu's OpenUI returns typed Controls
keyed by page.control and preserves local-only authorization. The old
interaction/tabbed import is a compatibility alias. Neither adapter contains
an independent widget engine. Fenrir imports internalui through its local
localization adapter. New widgets belong in internalui, so either reader can
use them without another implementation. No date picker or general table
widget is included yet; external application table reading is separate.
Hosts retain keyboard capture, secure/local-only authorization, focus and session cancellation, clipboard I/O, action execution, settings persistence, and speech/braille delivery. The toolkit imports only the standard library and other packages within this module.
Run go test -race ./... here. Tests exercise both layouts, adapters, secrets,
editing, validation, independent sessions/catalogs and matching grid behavior.
Consumer repositories also retain application and input integration tests.
Local development and release
For sibling checkouts, create a local Go workspace in their parent directory:
go work init ./screenreader-common ./cthulhu ./fenrir
Do not commit machine-local workspace or replacement paths. A workspace makes
both local reader builds use these sources immediately. Published builds use
pinned module versions: after review and live acceptance, release/tag the
common module, then update go.mod and go.sum in both readers and test
with GOWORK=off. A shared source change does not update already installed
binaries; they must be rebuilt with the updated dependency.