# Helm Keyboard v5.6 - Technical Reference

This document is a complete implementation-oriented reference for Helm Keyboard in its current v5.6 state.

## 1. Scope and Objectives

Helm Keyboard is a local-first, single-page web app that provides:

- Radial text entry and variants.
- Suggestion-assisted writing from multiple data sources.
- Continuous learning from user behavior.
- Configurable accessibility and alternate input modes.
- Persistent local data and backup/restore portability.

Design goals:

- Fast writing with minimal pointer movement.
- Broad input compatibility (keyboard, mouse/air-mouse, gamepad).
- Stable behavior with no backend dependency.
- Full user control over behavior through settings.

## 2. Runtime Architecture

The app is implemented as one HTML file with inline CSS and JavaScript.

Runtime pattern:

1. Load persisted state from localStorage.
2. Normalize all stores and settings.
3. Cache DOM references.
4. Bind event listeners.
5. Render UI surfaces.
6. Mutate in-memory state on interaction.
7. Persist changed state and rerender targeted components.

Primary subsystems:

- UI and layout subsystem.
- Radial input subsystem.
- Suggestions and learning subsystem.
- Notes/history subsystem.
- Settings/presets/theme subsystem.
- Data portability subsystem (backup/restore/import/export).
- Gamepad subsystem.

## 3. Data Model and Storage

### 3.1 Core stores

Persisted stores include:

- `settings`
- `userDict`
- `history`
- `bigrams`
- `glossaries`
- `settingsPresets`
- `activeSettingsPresetId`
- `sailorPalettes`
- `editorDraft`
- backup reminder timestamps

### 3.2 Bigram schema

Bigrams are normalized to:

- `pair`: map of `"prev<TAB>next" -> count`
- `meta`: optional provenance counters and source hints

Meta includes:

- `suggestionCount`
- `textCount`
- `manualCount`
- `lastSource`

The app preserves backward compatibility by normalizing older payloads.

### 3.3 Normalization strategy

Normalization helpers enforce:

- Type safety for loaded values.
- Clamped numeric ranges.
- Valid enum values with defaults.
- Migration-safe behavior when keys are missing.

## 4. UI Structure

Top-level regions:

1. Navbar
2. Section 1: radial + suggestions + variants
3. Section 2: editor + write actions
4. Section 3: notes/entries/bigrams/glossary view
5. Overlays: settings, sailor mood, glossaries, how-it-works

The `How it works?` modal in v5.6 acts as a documentation hub and support entry.

## 5. Input Modalities

### 5.1 Keyboard input

- Direct typing in editor.
- Shortcut handling for navigation and actions.
- Optional directional and encapsulated key systems.

### 5.2 Pointer input

- Segment click to insert.
- Utility button click handlers.
- Optional dwell activation flow.

### 5.3 Gamepad input

The gamepad system supports:

- Enable/disable toggle.
- Deadzone configuration.
- D-pad and axis navigation modes.
- Left/right stick axis source.
- Circular or coordinate traversal.
- Configurable button mapping for action commands.
- Repeat settings with start/interval timings.

Controller testing reference:

- https://hardwaretester.com/gamepad

Use it to verify axes, dpad, and buttons before tuning in-app mappings.

## 6. Radial Subsystem

### 6.1 Modes

Radial mode set:

- LETTERS
- NUMBERS
- SYMBOLS
- EMOJIS

### 6.2 Segment generation

Each mode has dedicated item builders, with contextual behavior for:

- Inner ring.
- Outer ring.
- Crown/utility actions.

### 6.3 Variants

Variant generation includes:

- Extended letter variants.
- Accent vowel variants.
- Open-accent vowel variants.

### 6.4 Smart symbol insertion

Symbol insertion applies spacing logic:

- Symbols that should append trailing space.
- Symbols that force appended spacing.
- Symbols that preserve left-side spacing.

This reduces punctuation cleanup in normal writing flows.

## 7. Suggestions Engine

### 7.1 Sources

Suggestions are composed from:

1. User dictionary frequencies.
2. Active glossary index lookups.
3. Bigram next-word candidates.

### 7.2 Modes

- `PREFIX`: current-token completions.
- `PREFIX_NEXT`: token completions plus next-word prediction from bigrams.

### 7.3 Ranking

Ranking factors include:

- Source confidence.
- Usage counts.
- Configured boosts.
- Prefix compatibility.

### 7.4 Key normalization controls

- Optional diacritics folding.
- Optional case sensitivity.
- Optional letter-class projection behaviors.

## 8. Learning Pipeline

### 8.1 Word learning

Word learning can be triggered by:

- Delimiter events while typing.
- Copy/save note actions.
- Manual explicit actions.

### 8.2 Bigram learning

Bigram learning can be triggered by:

- Text token sequences.
- Suggestion-click events (configurable toggle).
- Manual bigram edits.

### 8.3 Provenance metadata

For each learned pair, metadata can identify whether learning came from:

- text
- suggestion
- manual
- mixed history of sources

This is used for transparency in suggestion tooltips and diagnostics.

## 9. Section 3 Data Views

Section 3 is a multipanel data manager with views for:

- Notes history
- Entries list
- Bigrams table
- Selected glossary details

Capabilities include:

- Sorting modes.
- Inline edits.
- Item deletion.
- Quick loading back into editor.

## 10. Settings and Presets

### 10.1 Settings domains

The settings model controls:

- Suggestions behavior and counts.
- Bigram display limits.
- Learning mode and learning triggers.
- Radial behavior.
- Directional/encapsulated controls.
- Gamepad behavior.
- Layout and typography.
- Theme and palette.
- Backup reminders.

### 10.2 Presets

Preset system supports:

- Built-in presets.
- Custom presets.
- Export/import preset payloads.
- Active preset synchronization with current settings snapshot.

## 11. Theming and Sailor Mood

Theme system includes:

- Built-in palettes.
- Custom palette creation/editing.
- Color normalization and fallback.
- Palette export/import.

The app applies CSS custom properties at runtime for live theme updates.

## 12. Import, Export, and Backup

### 12.1 Backup export

Backup exports serialize app state into JSON with timestamped naming.

### 12.2 Backup restore

Restore imports validate payload shape and normalize affected stores.

### 12.3 Glossary import

Glossary imports parse and normalize entries for suggestion indexing.

### 12.4 Offline export

The app can export itself as an offline file artifact for local usage.

## 13. Docs in Modal (v5.6)

The `How it works?` modal now includes:

1. Non-technical quick usage guidance.
2. Technical reference summary.
3. Direct links to GitHub-ready docs:
   - `README.md`
   - `README-TECHNICAL.md`
4. Support section with Buy Me a Coffee button.

## 14. AI Rebuild Blueprint

For an AI-assisted recreation of the app from scratch, implement in this order:

1. Base SPA scaffold (HTML/CSS/JS IIFE).
2. Core localStorage contracts and normalization helpers.
3. Editor + suggestions bar + variants panel.
4. Radial rendering and insertion actions by mode.
5. Learning and ranking engine.
6. Section 3 data management panels.
7. Settings modal with persistence and presets.
8. Theme/palette subsystem.
9. Import/export and backup flows.
10. Gamepad subsystem with configurable mappings.
11. Documentation modal and support links.

## 15. Verification Checklist

Use this checklist after feature changes:

1. App version label updates correctly.
2. Suggestions update on typing and on source changes.
3. Learning writes to user dictionary.
4. Bigrams learn and display immediately.
5. Case-sensitive bigram behavior works as expected.
6. Backup and restore roundtrip succeeds.
7. Gamepad mapping and repeat logic behave correctly.
8. Modal links open local docs.
9. Buy Me a Coffee link opens expected profile URL.

## 16. Support

Support URL template:

- https://buymeacoffee.com/devdch

Support link is configured to the current profile above.