From 938caa39cc181ed1c70104b88aa84326e277d9d3 Mon Sep 17 00:00:00 2001 From: baketnk Date: Thu, 24 Sep 2026 23:23:11 -0400 Subject: [PATCH] docs: describe paced typing and remaining acceptance gates --- README.md | 2 +- TODO.md | 14 +++++++++----- docs/build.md | 20 +++++++++++++------- docs/design.md | 13 +++++++++---- docs/overlay.md | 13 ++++++++++++- 5 files changed, 44 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index feae655..f1abc9a 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ sh install.sh --mode binary --archive /path/to/frameyap-VERSION-linux-aarch64.ta | Overlay Type / Type + Enter | The same deliberate text / Enter actions. | | Overlay Hold Quit | Hold for 0.9 seconds, then release to quit (prevents accidental exit). | -Controls are remappable in SteamVR. Grip gestures may be unavailable with the dashboard open; pointer controls are an alternative. At the 4096-byte transcript limit, Type preserves the full text without appending a space if none fits. No speech commands, automatic Enter or automatic submit. Review is the default; Settings → Auto insert is opt-in, normally text + space only under continuously observed Xwayland focus. Check the focused destination before Type or Type + Enter. Edit literal Quick phrases (`quick_inputs`) in `$XDG_CONFIG_HOME/frameyap/config.json`, then restart. See [overlay and settings](docs/overlay.md). +Controls are remappable in SteamVR. Grip gestures may be unavailable with the dashboard open; pointer controls are an alternative. At the 4096-byte transcript limit, Type preserves the full text without appending a space if none fits. No speech commands, automatic Enter or automatic submit. Review is the default; Settings → Auto insert is opt-in, normally text + space only under continuously observed Xwayland focus. Type and Type + Enter now require a verified Xwayland target and use paced direct typing; Cancel stops remaining batches, never undoing prior input. The clipboard stays untouched. Check the destination before typing. Edit literal Quick phrases (`quick_inputs`) in `$XDG_CONFIG_HOME/frameyap/config.json`, then restart. See [overlay and settings](docs/overlay.md). ## Status / not yet validated diff --git a/TODO.md b/TODO.md index 66b985c..526a3cc 100644 --- a/TODO.md +++ b/TODO.md @@ -12,9 +12,10 @@ implementation is present, **not** a shipped or headset-accepted release. ## Implemented locally; offline tested; installed/headset validation pending The current working tree includes the source changes for A3, A5–A7, B1–B4, -C1–C3, D1–D2, E2–E3 and F1–F2. Offline checks passed 23/23 default, -24/24 strict UI, and 28/28 on a private native ARM64 snapshot. Later review -fixes require a fresh final native build before deployment. +C1–C3, D1–D2, E2–E3 and F1–F2. Final offline checks passed 24/24 default, +25/25 strict UI, and the fake Wayland input regression suite. An earlier private +native ARM64 snapshot passed 28/28; the final source requires a fresh native +build before deployment. These checkboxes close the *source tasks*, not their empirical acceptance gates. C1's second backend is a fake executable fixture, **not** a second shipped ASR engine. C2's two-click model consent, SHA-bound installer handoff, and D1/D2's @@ -32,8 +33,11 @@ deployed to Frame; local code/tests cannot establish a fixed delivery regression literal transcript, and add repeated/long/Unicode delivery regression tests. Do not assume a larger buffer fixes it or retry uncertain delivery automatically. An old-code delivery fixture crashed the Gamescope session, **not** the OS; - this is not evidence of a fix. Real-target confirmation remains required after - a tested fix is deployed. + this is not evidence of a fix. Plain-ASCII prefix corruption was reproduced; + retained IME and immediate byte chunking did not fix it. A nonblocking, + focus-guarded 24-codepoint/150 ms delivery queue is implemented with offline + regressions, including full-length Unicode and all-space batches. Clipboard + remains untouched. Real-target confirmation is still required after deployment. ## A. First release (v0.1) blockers diff --git a/docs/build.md b/docs/build.md index f653e34..64f230d 100644 --- a/docs/build.md +++ b/docs/build.md @@ -44,13 +44,19 @@ initialize OpenVR, open a microphone, run ASR, download files or inject input. microphone device failure releases the stream for explicit retry. A cancelled in-flight request or broken worker protocol may require reloading. No cloud/desktop fallback. -- Gamescope IME v2 generated bindings, per-action short-lived lease, unavailable - handling, UTF-8/control validation and explicit Type + Enter action. - Type ensures a trailing space without doubling an existing one. Type + Enter - first types pending review, releases the text lease, then acquires a fresh - lease for Enter. Failed/uncertain text never proceeds to Enter; failed - Enter acquisition never replays text. If a validated transcript fills the - 4096-byte bound and lacks a trailing space, Type preserves all its bytes and +- Gamescope IME v2 generated bindings and a tick-driven paced delivery queue: + at most 24 Unicode codepoints per commit, at least 150 ms between commits, + including separate actions and explicit Enter. This is a proposed workaround + for the finite temporary keymap, not a target-consumption acknowledgment. Clipboard is + untouched. The full literal is retained while pending; Cancel/Quit, focus loss + or model/debug changes discard unsent input without retry or Enter. Manual + Type captures a verified Xwayland target; Auto insert keeps its original guard. + The IME is retained only through the task and cooldown (shutdown can wait the + remaining <=150 ms). Pacing does not sleep in the UI loop, but an individual + Wayland roundtrip can still reach its bounded one-second timeout. Type adds + a trailing space if it fits, without doubling an existing one. If a validated + transcript fills the 4096-byte bound and lacks a trailing space, Type preserves + all its bytes and queues it **without** the usual space; it does not signal a separate error. Destination consumption and repeated-delivery behavior remain unaccepted. - User-local installer with checked binary-archive or explicitly provisioned diff --git a/docs/design.md b/docs/design.md index ec53ac6..2f89893 100644 --- a/docs/design.md +++ b/docs/design.md @@ -194,11 +194,16 @@ Gamescope exposes focus-display/window root properties, but their encoding and relationship to seat focus need implementation-specific validation. Do not infer that X display `:0` is always the destination, or that an X focus observation identifies a native Wayland text field. For unobservable native Wayland focus, -require explicit review/Type; do not advertise safe auto-targeting. +keep the transcript in review; current paced manual Type also refuses an +unverifiable target. Do not advertise native Wayland target support. -If focus changes, keep the result in review. A fresh Type explicitly approves -the current destination and creates a new delivery authorization. Recheck again -at typing. This minimizes stale delivery but does **not** eliminate a race +Before the first send, focus failure keeps the result in review. A fresh Type +approves a currently verified Xwayland destination and creates a new delivery +authorization. The paced queue rechecks that same target before each <=24-codepoint +batch and explicit Enter, spacing commits by at least 150 ms. After a partial +send, focus failure drops the remainder and Enter without replay; it cannot +undo already queued input. The clipboard remains untouched. This minimizes stale +delivery but does **not** eliminate a race between the final check and global input processing; do not claim otherwise. A Wayland roundtrip means compositor processing, not application consumption. Report `input queued`, never `message sent`. diff --git a/docs/overlay.md b/docs/overlay.md index 47d1155..6d0a6c9 100644 --- a/docs/overlay.md +++ b/docs/overlay.md @@ -178,7 +178,9 @@ focus-out, root focus-property change (even if the same window returns), window destruction, held keyboard key, missing X display or any disagreement permanently disarms that clip. The transcript then remains for explicit review/Type. Native Wayland focus and child text-field focus cannot be safely inferred here; -those cases fall back to review. No automatic Enter, speech commands or retry. +those cases fall back to review. Manual Type now also requires a verifiable +Xwayland target; it does not bypass an unavailable guard. No automatic Enter, +speech commands or retry. The compositor can still change focus in the gap between the final check and global delivery, and IME commit is not an application receipt. This path has offline synthetic focus tests and a separate owned-target IME fixture; live @@ -186,6 +188,15 @@ speech-driven Auto insert, target coverage and headset acceptance remain unverified. The setting is preserved on upgrade and a failed preference write applies only to the current session. +Delivery uses a responsive, tick-driven queue of at most 24 Unicode codepoints +per commit, with at least 150 ms between commits and before explicit Enter. +The full 4096-byte literal is preserved, including all-space batches. The same +target is checked before every batch; input blocked before the first send keeps +review, whereas partial/uncertain input is consumed and never retried. Cancel +stops remaining text and Enter; it cannot undo bytes already queued. Record and +new Type actions are disabled while pacing. The clipboard is never touched. +This source-grounded Gamescope workaround still needs long-text live acceptance. + `quick_inputs` is an editable list of 1–6 nonempty, printable ASCII strings, each at most 64 characters. Edit the JSON file and restart; there is no headset text editor. Inputs are literal (not expanded or interpreted by FrameYap) and