third-party/termina/SOURCE.md - maka - Git at Google


            
            <!--

            
              Licensed to the Apache Software Foundation (ASF) under one

            
              or more contributor license agreements.  See the NOTICE file

            
              distributed with this work for additional information

            
              regarding copyright ownership.  The ASF licenses this file

            
              to you under the Apache License, Version 2.0 (the

            
              "License"); you may not use this file except in compliance

            
              with the License.  You may obtain a copy of the License at


                  http://www.apache.org/licenses/LICENSE-2.0


              Unless required by applicable law or agreed to in writing,

            
              software distributed under the License is distributed on an

            
              "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

            
              KIND, either express or implied.  See the License for the

            
              specific language governing permissions and limitations

            
              under the License.

            
            -->


            # Termina bounded terminal input


            Sources are copied from [Termina 0.4.0, revision 7be7389fd3509d508a66a7e887aa9935e037b801](https://github.com/helix-editor/termina/tree/7be7389fd3509d508a66a7e887aa9935e037b801), with the reviewed local patch `32a7a905ab1c72b51463a93e96852d957b1c8448`. `upstream.json` records the finite original inventory and SHA-256 hashes before that patch. The repository's existing LF normalization applies to the copied sources; original hashes refer to upstream bytes. All production sources, embedded tests, examples, benchmark, Windows documentation and the original manifest are retained; upstream CI, development-shell files and lockfile are omitted.


            The local `Cargo.lock` is generated by Cargo for Maka's standalone vendor tests and Windows compilation checks. It is generated build metadata outside the original source inventory.


            The original MIT and MPL texts are preserved. Maka uses the MIT alternative offered by the upstream README. Keep that README: it also contains the original Crossterm (Timon, 2019) and TermWiz (Wez Furlong, 2018) MIT notices.


            The bounded local changes are:


            - Preserve primary DA terminal type and numeric attributes in `Csi::PrimaryDeviceAttributes`, and decode strictly decimal, nonzero `CSI 6;height;width t` cell pixels using the existing window-response type.

            
            - Let the embedding reader set a pending-byte limit; the default remains unlimited. Checks happen before each byte is retained, including bracketed-paste framing. Completed events in the same OS read do not accumulate against this limit.

            
            - Bound incomplete `CSI ?` metadata to 256 bytes and 100 milliseconds, advancing deadlines through the existing Unix and Windows input sources even without more input. Numeric CSI key prefixes do not receive a fragment deadline. Input resource/timeout failures remain sticky and return through `Parser::parse` and the same reader; rejected tails are never replayed as keys. Existing malformed-sequence handling is otherwise retained.

            
            - Parse identified [Kitty graphics replies](https://sw.kovidgoyal.net/kitty/graphics-protocol/) through that same reader. `Event::KittyGraphicsResponse` preserves decimal `i`, optional `I`/`p`, and exact success or printable ASCII error text. APC (`ESC _`) is now a protocol prefix, like the existing OSC/DCS prefixes, rather than Alt+underscore. Complete unknown or malformed APC strings are discarded through ST; replies with duplicate, unknown, missing, or invalid identifier fields do not produce an event. APC strings share the existing 256-byte/100-millisecond sticky input-error bounds, so truncated or oversized strings cannot replay their tails as keys. These are local input resource limits, not protocol limits.

            
            - Decode the existing mode-1016 DECRPM type and text-area pixel-size reports (`CSI 4;height;width t`) without selecting a rendering backend. SGR mouse reports use `Event::SgrMouse` with original signed coordinates: the application owns whether it enabled one-based cells or pixels. Kitty and Ghostty send zero-based pixels, including negative positions outside the viewport. Legacy mouse events retain zero-based cells. Kitty's bit-8 leave extension produces a coordinate-free `Event::MouseLeave`; all other button bits and coordinate values have no semantic effect on that event. No parser-side mode mirror is added.

            
            - Decode the existing mode-80 DECRPM type, identified XTVERSION replies as `Dcs::TerminalNameAndVersion`, and iTerm2 capability replies as `Event::Iterm2Capabilities`. Names and feature strings retain their printable ASCII payloads; an empty capability string is valid. The parser does not infer terminal products or image support from them. Only the recognized `DCS >|` and `OSC 1337;Capabilities=` prefixes join the existing 256-byte/100-millisecond sticky reply bounds; unrelated OSC/DCS framing remains unchanged. iTerm2 replies accept BEL or ST. Feature-token interpretation remains with the consumer.

            
            - Enter Unix raw mode without flushing queued input. Allow Windows embedding owners to disable the existing discard-input-on-drop policy before starting their reader. Original mode/codepage restoration remains in the same terminal owner.

            
            - Expose non-consuming input readiness through the same reader and platform waker. Waiting observes the existing buffered events, input/resize handles, and parser reply deadline without reading, decoding, or removing input; the embedding owner can retain its presentation fence around actual polling and reads. Unix descriptor hangup/error paths terminate through the existing input error handling rather than repeatedly waking an idle reader.


            The local tests cover split replies mixed with Unicode/mouse/paste, strict parameters, Kitty query/placement responses, malformed APC isolation with following keys, a complete 64KiB paste, per-sequence limits, sticky rejection and deadline handling without delaying ordinary numeric key prefixes. Examples, documentation and the benchmark handle the fallible parser API.


            After patch `32a7a905ab1c72b51463a93e96852d957b1c8448`, Maka adds a Windows-only console-record regression for completed-key preservation, sticky budget errors and rejected-tail isolation.


            Maka's terminal shell owns the single OS reader and terminal mode guard; its existing Output worker owns terminal writes. This package does not add another reader, writer or capability-selection framework. Applications match Kitty response identifiers to their own outstanding requests; a response reports protocol acceptance, not that pixels have reached the screen. Image transmission, capability selection, and placement ownership remain in the embedding application. No general APC command framework or image transmitter is added by this patch.
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	# Termina bounded terminal input

	Sources are copied from [Termina 0.4.0, revision 7be7389fd3509d508a66a7e887aa9935e037b801](https://github.com/helix-editor/termina/tree/7be7389fd3509d508a66a7e887aa9935e037b801), with the reviewed local patch `32a7a905ab1c72b51463a93e96852d957b1c8448`. `upstream.json` records the finite original inventory and SHA-256 hashes before that patch. The repository's existing LF normalization applies to the copied sources; original hashes refer to upstream bytes. All production sources, embedded tests, examples, benchmark, Windows documentation and the original manifest are retained; upstream CI, development-shell files and lockfile are omitted.

	The local `Cargo.lock` is generated by Cargo for Maka's standalone vendor tests and Windows compilation checks. It is generated build metadata outside the original source inventory.

	The original MIT and MPL texts are preserved. Maka uses the MIT alternative offered by the upstream README. Keep that README: it also contains the original Crossterm (Timon, 2019) and TermWiz (Wez Furlong, 2018) MIT notices.

	The bounded local changes are:

	- Preserve primary DA terminal type and numeric attributes in `Csi::PrimaryDeviceAttributes`, and decode strictly decimal, nonzero `CSI 6;height;width t` cell pixels using the existing window-response type.
	- Let the embedding reader set a pending-byte limit; the default remains unlimited. Checks happen before each byte is retained, including bracketed-paste framing. Completed events in the same OS read do not accumulate against this limit.
	- Bound incomplete `CSI ?` metadata to 256 bytes and 100 milliseconds, advancing deadlines through the existing Unix and Windows input sources even without more input. Numeric CSI key prefixes do not receive a fragment deadline. Input resource/timeout failures remain sticky and return through `Parser::parse` and the same reader; rejected tails are never replayed as keys. Existing malformed-sequence handling is otherwise retained.
	- Parse identified [Kitty graphics replies](https://sw.kovidgoyal.net/kitty/graphics-protocol/) through that same reader. `Event::KittyGraphicsResponse` preserves decimal `i`, optional `I`/`p`, and exact success or printable ASCII error text. APC (`ESC _`) is now a protocol prefix, like the existing OSC/DCS prefixes, rather than Alt+underscore. Complete unknown or malformed APC strings are discarded through ST; replies with duplicate, unknown, missing, or invalid identifier fields do not produce an event. APC strings share the existing 256-byte/100-millisecond sticky input-error bounds, so truncated or oversized strings cannot replay their tails as keys. These are local input resource limits, not protocol limits.
	- Decode the existing mode-1016 DECRPM type and text-area pixel-size reports (`CSI 4;height;width t`) without selecting a rendering backend. SGR mouse reports use `Event::SgrMouse` with original signed coordinates: the application owns whether it enabled one-based cells or pixels. Kitty and Ghostty send zero-based pixels, including negative positions outside the viewport. Legacy mouse events retain zero-based cells. Kitty's bit-8 leave extension produces a coordinate-free `Event::MouseLeave`; all other button bits and coordinate values have no semantic effect on that event. No parser-side mode mirror is added.
	- Decode the existing mode-80 DECRPM type, identified XTVERSION replies as `Dcs::TerminalNameAndVersion`, and iTerm2 capability replies as `Event::Iterm2Capabilities`. Names and feature strings retain their printable ASCII payloads; an empty capability string is valid. The parser does not infer terminal products or image support from them. Only the recognized `DCS >\|` and `OSC 1337;Capabilities=` prefixes join the existing 256-byte/100-millisecond sticky reply bounds; unrelated OSC/DCS framing remains unchanged. iTerm2 replies accept BEL or ST. Feature-token interpretation remains with the consumer.
	- Enter Unix raw mode without flushing queued input. Allow Windows embedding owners to disable the existing discard-input-on-drop policy before starting their reader. Original mode/codepage restoration remains in the same terminal owner.
	- Expose non-consuming input readiness through the same reader and platform waker. Waiting observes the existing buffered events, input/resize handles, and parser reply deadline without reading, decoding, or removing input; the embedding owner can retain its presentation fence around actual polling and reads. Unix descriptor hangup/error paths terminate through the existing input error handling rather than repeatedly waking an idle reader.

	The local tests cover split replies mixed with Unicode/mouse/paste, strict parameters, Kitty query/placement responses, malformed APC isolation with following keys, a complete 64KiB paste, per-sequence limits, sticky rejection and deadline handling without delaying ordinary numeric key prefixes. Examples, documentation and the benchmark handle the fallible parser API.

	After patch `32a7a905ab1c72b51463a93e96852d957b1c8448`, Maka adds a Windows-only console-record regression for completed-key preservation, sticky budget errors and rejected-tail isolation.

	Maka's terminal shell owns the single OS reader and terminal mode guard; its existing Output worker owns terminal writes. This package does not add another reader, writer or capability-selection framework. Applications match Kitty response identifiers to their own outstanding requests; a response reports protocol acceptance, not that pixels have reached the screen. Image transmission, capability selection, and placement ownership remain in the embedding application. No general APC command framework or image transmitter is added by this patch.