README — SciMath Keyboard

A custom iOS and iPadOS keyboard extension providing a full QWERTY layout plus three additional symbol layers: numbers and punctuation, extended operators, and scientific/mathematical characters.

Targets

Target	Role
`ScientificK`	Keyboard extension (`UIInputViewController` subclass)
`Scientific`	Containing app (`ContentView.swift`, SwiftUI)

Layers

Layer	Access	Contents
ABC	Default	QWERTY letters; diacriticals on long-press
123	123 button	Numbers, common punctuation; superscripts/subscripts on long-press digits
#+=	#+= button	Brackets, operators, currency
sci	sci button	° ± × ÷ ≈ ≠ ≤ ≥ √ ∞ ∑ † ∫ ∂ ∇ Δ ℏ Å µ Ω π ⊙ ∴ ∀ · ∝ ∈ ′ ⊥

Layer cycle: 123 → #+= → sci → 123. ABC button returns from any layer.

Key Features

Scientific and mathematical Unicode symbols
Extended diacriticals: French, German, Scandinavian, Spanish, Eastern European, scholarly Latin
Long-press alternates on sci layer (∈ → ∉ ∋ ⊂ ⊃ ∪ ∩ ∅, etc.)
Superscript and subscript digits on long-press (123 layer)
Traditional footnote sequence: * † ‡ § ‖ ¶ ※
Trackpad cursor mode (hold spacebar)
Key flash (brightens key on tap; visible in direct sunlight)
iPad pull-down secondary characters
No Full Access required — complete privacy by design
No network access, no analytics, no telemetry
One-time purchase; no subscription; no advertising

Architecture Notes

rebuildAndSwap() pattern for all layout changes — tears down and rebuilds the key grid, swaps atomically. No incremental mutation.
PaddedButton subclass provides expanded hit targets beyond visual bounds.
UILongPressGestureRecognizer(minimumPressDuration: 0) used for per-key press tracking.
Popup direction: top-row keys drop below (no space above within keyboard bounds); all other rows rise above. Apple architectural constraint — extension views cannot render outside their bounds.
Key flash implemented as explicit UIColor brightening on touchesBegan, not a system animation. Fires on first contact with no gesture recognition delay.
Shift-up hint characters on iPad ABC/123 layers match stock iPadOS layout.
Globe key: iOS injects on iPhone (needsInputModeSwitchKey). iPad uses advanceToNextInputMode() / handleInputModeList(from:with:) via documented API.
Microphone button: non-functional on iPad, present for spatial layout preservation only.
App Groups shared defaults sync key flash preference between extension and containing app.
Keyboard background colours are explicit hardcoded RGB values tuned by hand. Apple does not publish the specs for stock keyboard chrome colours.

iOS 26 Gesture Regression

Apple introduced a regression in iOS 26.x (May 2026) affecting UIPanGestureRecognizer in keyboard extensions — .began no longer fires on stationary contact, breaking balloon detection. Filed as FB19394663 / FB19405284, acknowledged by Apple.

Workaround: ImmediatePanGestureRecognizer subclass overrides touchesBegan to force state = .began on first contact. Fork began at v0.400. The workaround uses supported API and remains valid after Apple fixes the underlying bug.

class ImmediatePanGestureRecognizer: UIPanGestureRecognizer {
    override func touchesBegan(_ touches: Set<UITouch>,
                                with event: UIEvent) {
        super.touchesBegan(touches, with: event)
        state = .began
    }
}

Known Limitations

Autocorrect / predictive text: requires Full Access — not available by design.
Dictation: requires Full Access — not available. Workaround: switch to stock keyboard, dictate, switch back.
Emoji: no emoji key. Workaround: switch to stock keyboard, select emoji, switch back.
Slide-to-type: gesture architecture conflicts with balloon gesture recognition — not currently supported.
Full Greek alphabet: π, µ, Ω, ω present as mathematical constants only.
Top-row balloons: cannot appear above the keyboard boundary — Apple architectural constraint, not fixable from an extension.

A Note on iOS Keyboard Geometry

Apple updated stock keyboard key appearance in iOS 18, rounding key shapes more aggressively and reducing effective tap target area. If users report missing keys more than expected, this is a known platform change — muscle memory calibrated to pre-iOS 18 geometry is a factor.

Privacy

SciMath does not request Full Access. It never logs keystrokes, never makes network requests, and contains no analytics or telemetry of any kind. Nothing typed ever leaves the device. The only local storage is the key flash preference. See privacy.html for the full policy.