From db7b472861c6bd05d7fdd548fafee0fface8510e Mon Sep 17 00:00:00 2001 From: Gerardo Betancourt Date: Wed, 28 Oct 2026 09:12:58 -0400 Subject: [PATCH] Prepare private.20261028.2 X11 text pilot --- docs/COMMAND-REFERENCE.md | 8 ++- docs/X11-TEXT-PRIVATE-CANDIDATE.md | 25 +++++++++ source/docs/COMMAND-GUIDE.json | 51 ++++++++++--------- source/docs/COMMAND-REFERENCE.md | 8 ++- source/docs/DEBIAN-TUTORIAL.md | 8 ++- source/docs/framebridge.1 | 6 ++- .../expanded/framebridge_expanded/__init__.py | 2 +- .../framebridge_expanded/guide_data.py | 3 ++ 8 files changed, 79 insertions(+), 32 deletions(-) create mode 100644 docs/X11-TEXT-PRIVATE-CANDIDATE.md diff --git a/docs/COMMAND-REFERENCE.md b/docs/COMMAND-REFERENCE.md index fce4677..f972d5a 100644 --- a/docs/COMMAND-REFERENCE.md +++ b/docs/COMMAND-REFERENCE.md @@ -1,6 +1,6 @@ # FrameBridge — command guide -Version: 0.3.2+private.20261028.1 | Guide schema: 1 +Version: 0.3.2+private.20261028.2 | Guide schema: 1 This reference is generated from the shared CLI/MCP guide. Use the matching installed version. @@ -36,7 +36,7 @@ fb --json status Install the .deb built for your exact Debian 13, Ubuntu 24.04/26.04, Linux Mint 22.x or LMDE 7 amd64 profile. These compatibility candidates still require installation and lifecycle validation on each target. Select the artifact from the matching profile folder and keep the distribution system Python. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings. ~~~sh -sudo apt install ./framebridge-expanded_0.3.2+private.20261028.1_amd64.deb +sudo apt install ./framebridge-expanded_0.3.2+private.20261028.2_amd64.deb fb connect ~~~ @@ -310,6 +310,10 @@ fb status fb doctor ~~~ +### Guarded X11 text compatibility + +Graphical TYPE in KEYS mode uses the guarded native X11 backend on x86-64 LP64 systems with libxdo 3.20160805.1. This private candidate accepts active keyboard group 0 only, with no held or latched modifiers and only conventional Caps Lock and Num Lock locked bits. The whole string and generated key actions are checked before any input. Unsupported groups, characters, actions or keyboard states fail closed. The backend does not change the keyboard group or map and does not use the clipboard. Display session, fixed target window, geometry and keyboard context are checked while sending. If input may have started and an error follows, inspect the target and do not automatically replay the text. + ### Frame-buffer read access screen-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication. diff --git a/docs/X11-TEXT-PRIVATE-CANDIDATE.md b/docs/X11-TEXT-PRIVATE-CANDIDATE.md new file mode 100644 index 0000000..44447ec --- /dev/null +++ b/docs/X11-TEXT-PRIVATE-CANDIDATE.md @@ -0,0 +1,25 @@ +# Private X11 text candidate 0.3.2+private.20261028.2 + +This candidate is private and uninstalled. It does not change the frozen 0.3.2 source or the six installed private.20261028.1 packages. No signing, publication or public activation is part of this preparation. + +The X11 KEYS backend chooses keycodes only from validated keyboard group 0 and sends direct XTEST events. It never invokes the libxdo group-switching sender, changes a keyboard map/group, or reads or writes the clipboard. The captured original source remains byte-for-byte unchanged. The existing action authorization, target-window and geometry checks still run before the project-owned primitive hook. Every permission batch repeats the display guard; the child rechecks the fixed context after permission and before events. A bounded isolated child prevents a stalled Xlib roundtrip from indefinitely blocking the native host. + +Supported native context is x86-64 LP64, libxdo version 3.20160805.1, active/locked keyboard group 0, no held/latched modifiers or group latch, and conventional Caps/Num locked bits only. All characters, action table indices and generated key behaviors are checked before the first input batch. Modifier actions must be exact SetMods for their physical modifier bit; ClearLocks is accepted only if that bit is not locked. Other groups, native ABIs, remapped actions and unrepresentable text are refused before events. No legacy text-sender fallback is permitted. + +An attempted input batch remains conservatively marked as possible input after a failure or timeout; automatic replay is forbidden. Cleanup attempts to release all attempted keys. A stalled or terminated X server can prevent confirmation of cleanup, so the result must remain uncertain. + +## Evidence and acceptance scope + +- Fix source commit: b283999f5aef615b2acee7754e438cdd01cc75bd. +- Approved helper SHA-256: d0c8a1f56a6a8e3d16a7d676bcc0a858318cbe590ea825f76bceb6a1d7045470. +- Approved native host SHA-256: 9a2f2af559793aa93c0623d307f6383494fb0b4863db2c425f73ed67ed7ae65f. +- The fix worktree passed all 800 tests; remote receipt gerameg-mcp-20261028-090452-f2ada16c, stdout SHA-256 b073bf80ad84bb1aeb6105fd8d8796106c231f20c0ce060ffc66d320d4e62e42. +- ASUS read-only preflight for a 169-character command-shaped ASCII probe passed with group 0, no held modifiers, Num Lock mask 16 and slash keycode 61; event emission was disabled. Receipt asus-mcp-20261028-085936-a8426ef7, stdout SHA-256 235d7cc42b8313fccdf49c604530c47e6b14c4505ba4f3d324d0b0e98fc1aca1. +- The root GUI controller then tested the reviewed standalone development helper in its own foreground cat receiver: 169 characters exactly matched, 169 permission batches, 5.704268 seconds, with keyboard map/group/held/Num Lock state unchanged. Production EXEC receipt 090055-db27c436d046 and receiver receipt 090127-6ceba9d8e540. +- That live result validates the development helper, not the installed MCP pipeline. This candidate still requires a private installed pilot and exact receiver comparison through the final package before any broader activation. + +## Primary implementation references + +- Public 2016 libxdo source and ABI: https://sources.debian.org/src/xdotool/1%3A3.20160805.1-5/ +- XKB public structures: https://gitlab.freedesktop.org/xorg/proto/xorgproto/-/blob/master/include/X11/extensions/XKBstr.h +- X.Org XKB library specification, action and behavior tables: https://www.x.org/archive/X11R7.7/doc/libX11/XKB/xkblib.html diff --git a/source/docs/COMMAND-GUIDE.json b/source/docs/COMMAND-GUIDE.json index f24c869..38be413 100644 --- a/source/docs/COMMAND-GUIDE.json +++ b/source/docs/COMMAND-GUIDE.json @@ -1,12 +1,12 @@ { "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topics": { "start": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "start", "title": "Start with FrameBridge", @@ -24,7 +24,7 @@ "heading": "Install and connect", "body": "Install the .deb built for your exact Debian 13, Ubuntu 24.04/26.04, Linux Mint 22.x or LMDE 7 amd64 profile. These compatibility candidates still require installation and lifecycle validation on each target. Select the artifact from the matching profile folder and keep the distribution system Python. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.", "commands": [ - "sudo apt install ./framebridge-expanded_0.3.2+private.20261028.1_amd64.deb", + "sudo apt install ./framebridge-expanded_0.3.2+private.20261028.2_amd64.deb", "fb connect" ] }, @@ -64,12 +64,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "633545a91cf4c434264832392e80fc50f04395dc3cd4f06465d8f115edeaa325" + "guide_sha256": "606e18e34e2b71a8a17ea3e05823a03b49b7a73d3b7a68dfaa725df9a754f16b" }, "commands": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "commands", "title": "Command reference", @@ -136,12 +136,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "3519625fe43305646fe3aa3d3c55abebeb6bb719343ded4e9f88d786046ac818" + "guide_sha256": "b765ac3fd5e90518f60f93969c86b4d5f04946cb8604b61a1e462833a7957172" }, "connection": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "connection", "title": "Connect and disconnect ChatGPT", @@ -190,12 +190,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "c50703d120533d821183a9907cfe7025d8d06fa86c6027f03d32776604865ec3" + "guide_sha256": "eb8ec2e6d26617b76ccd3d6972233b7fab74072275275c8981d09166bef0d12c" }, "lifecycle": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "lifecycle", "title": "Services, connection intent and boot policy", @@ -256,12 +256,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "14c12dfa8c9d70c59ea80bf4fe44028c8c4c9b45a98957d0b70c6d964d228e16" + "guide_sha256": "eb36c2d78bcda926b896a94385892ce3d479e56dce8a808ad55adfa601472f33" }, "nodes": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "nodes", "title": "Central and node operation", @@ -310,12 +310,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "179070ececdf8451b6e53785cbf453ecca96cad56e3d7c28898113a6bad8c356" + "guide_sha256": "fc9d260c0f0b4e4f84087297396044058d7ec2b8821391dae5187eb58683cad7" }, "terminals": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "terminals", "title": "Persistent Bash terminals", @@ -376,12 +376,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "2e2530cab757882cf1ce7feb1a360e1d76cbc84602f2fc76cf55922188b2f48a" + "guide_sha256": "162f069fbdb4584639be386163239530c1b9b883972ab212f5bccd47f6639e82" }, "screens": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "screens", "title": "Authentic screen observation and input", @@ -399,6 +399,11 @@ "fb doctor" ] }, + { + "heading": "Guarded X11 text compatibility", + "body": "Graphical TYPE in KEYS mode uses the guarded native X11 backend on x86-64 LP64 systems with libxdo 3.20160805.1. This private candidate accepts active keyboard group 0 only, with no held or latched modifiers and only conventional Caps Lock and Num Lock locked bits. The whole string and generated key actions are checked before any input. Unsupported groups, characters, actions or keyboard states fail closed. The backend does not change the keyboard group or map and does not use the clipboard. Display session, fixed target window, geometry and keyboard context are checked while sending. If input may have started and an error follows, inspect the target and do not automatically replay the text.", + "commands": [] + }, { "heading": "Frame-buffer read access", "body": "screen-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication.", @@ -426,12 +431,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "38e14c50a774b3d4b59d5a20e6afcc1dba568b1188083bf8f36593e4d88ca644" + "guide_sha256": "1734ee9890fe63d60fe008879c75804fa0c755c0396153a4be2e8228fd790316" }, "diagnostics": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "diagnostics", "title": "Status and diagnosis", @@ -476,12 +481,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "05e4e8a9ed3df91686434c00f2221ea8ac1c392b9a5ed002c8fde014fecad18a" + "guide_sha256": "2899db14de0686a2dc50a2b22edf35d97d7d53e162300194fe57c126dde395dc" }, "security": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "security", "title": "Authorization, distribution and safe operation", @@ -516,12 +521,12 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "2c1b1aa4f052c2d62fcc22a0c8a55dc75295465969d51d1171957c9654ad2a2a" + "guide_sha256": "addecd0420c18951683f32bdc05a9ab7d00a1b2150ecd6087bd99b784196696f" }, "compatibility": { "ok": true, "product": "FrameBridge", - "version": "0.3.2+private.20261028.1", + "version": "0.3.2+private.20261028.2", "guide_schema": 1, "topic": "compatibility", "title": "Compatibility with earlier commands", @@ -564,8 +569,8 @@ ], "read_only": true, "capabilities_verified": false, - "guide_sha256": "ea21425ad830c56bcb9328b2a7600e61cad86adaaf7e03531f9250b4e42c24e3" + "guide_sha256": "0dcbf347bfba8b0cff176d5c96bcf1a95f2c83fc6398559d54ac3b4c83d74b0a" } }, - "guide_sha256": "688782d53c19df9de8ba686abc90ff97ad7140a5bf0ca6897d4314147ab5c434" + "guide_sha256": "1f259d089526e7e38f1732afbc4ceae2af62ec36c8630452fd8f4ef4ccb90069" } diff --git a/source/docs/COMMAND-REFERENCE.md b/source/docs/COMMAND-REFERENCE.md index fce4677..f972d5a 100644 --- a/source/docs/COMMAND-REFERENCE.md +++ b/source/docs/COMMAND-REFERENCE.md @@ -1,6 +1,6 @@ # FrameBridge — command guide -Version: 0.3.2+private.20261028.1 | Guide schema: 1 +Version: 0.3.2+private.20261028.2 | Guide schema: 1 This reference is generated from the shared CLI/MCP guide. Use the matching installed version. @@ -36,7 +36,7 @@ fb --json status Install the .deb built for your exact Debian 13, Ubuntu 24.04/26.04, Linux Mint 22.x or LMDE 7 amd64 profile. These compatibility candidates still require installation and lifecycle validation on each target. Select the artifact from the matching profile folder and keep the distribution system Python. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings. ~~~sh -sudo apt install ./framebridge-expanded_0.3.2+private.20261028.1_amd64.deb +sudo apt install ./framebridge-expanded_0.3.2+private.20261028.2_amd64.deb fb connect ~~~ @@ -310,6 +310,10 @@ fb status fb doctor ~~~ +### Guarded X11 text compatibility + +Graphical TYPE in KEYS mode uses the guarded native X11 backend on x86-64 LP64 systems with libxdo 3.20160805.1. This private candidate accepts active keyboard group 0 only, with no held or latched modifiers and only conventional Caps Lock and Num Lock locked bits. The whole string and generated key actions are checked before any input. Unsupported groups, characters, actions or keyboard states fail closed. The backend does not change the keyboard group or map and does not use the clipboard. Display session, fixed target window, geometry and keyboard context are checked while sending. If input may have started and an error follows, inspect the target and do not automatically replay the text. + ### Frame-buffer read access screen-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication. diff --git a/source/docs/DEBIAN-TUTORIAL.md b/source/docs/DEBIAN-TUTORIAL.md index 748bdfd..dc0a004 100644 --- a/source/docs/DEBIAN-TUTORIAL.md +++ b/source/docs/DEBIAN-TUTORIAL.md @@ -1,6 +1,6 @@ # FrameBridge — Debian, Ubuntu and Linux Mint installation and first use -Version: 0.3.2+private.20261028.1 | Guide schema: 1 +Version: 0.3.2+private.20261028.2 | Guide schema: 1 This reference is generated from the shared CLI/MCP guide. Use the matching installed version. @@ -36,7 +36,7 @@ fb --json status Install the .deb built for your exact Debian 13, Ubuntu 24.04/26.04, Linux Mint 22.x or LMDE 7 amd64 profile. These compatibility candidates still require installation and lifecycle validation on each target. Select the artifact from the matching profile folder and keep the distribution system Python. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings. ~~~sh -sudo apt install ./framebridge-expanded_0.3.2+private.20261028.1_amd64.deb +sudo apt install ./framebridge-expanded_0.3.2+private.20261028.2_amd64.deb fb connect ~~~ @@ -310,6 +310,10 @@ fb status fb doctor ~~~ +### Guarded X11 text compatibility + +Graphical TYPE in KEYS mode uses the guarded native X11 backend on x86-64 LP64 systems with libxdo 3.20160805.1. This private candidate accepts active keyboard group 0 only, with no held or latched modifiers and only conventional Caps Lock and Num Lock locked bits. The whole string and generated key actions are checked before any input. Unsupported groups, characters, actions or keyboard states fail closed. The backend does not change the keyboard group or map and does not use the clipboard. Display session, fixed target window, geometry and keyboard context are checked while sending. If input may have started and an error follows, inspect the target and do not automatically replay the text. + ### Frame-buffer read access screen-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication. diff --git a/source/docs/framebridge.1 b/source/docs/framebridge.1 index 43022d5..5684490 100644 --- a/source/docs/framebridge.1 +++ b/source/docs/framebridge.1 @@ -1,4 +1,4 @@ -.TH FRAMEBRIDGE 1 "2026-10-27" "FrameBridge 0.3.2+private.20261028.1" "User Commands" +.TH FRAMEBRIDGE 1 "2026-10-27" "FrameBridge 0.3.2+private.20261028.2" "User Commands" .SH NAME framebridge, fb \- use local Linux tools and enrolled nodes with ChatGPT .SH SYNOPSIS @@ -21,7 +21,7 @@ fb \-\-json status Install the .deb built for your exact Debian 13, Ubuntu 24.04/26.04, Linux Mint 22.x or LMDE 7 amd64 profile. These compatibility candidates still require installation and lifecycle validation on each target. Select the artifact from the matching profile folder and keep the distribution system Python. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings. .PP .nf -sudo apt install ./framebridge\-expanded_0.3.2+private.20261028.1_amd64.deb +sudo apt install ./framebridge\-expanded_0.3.2+private.20261028.2_amd64.deb fb connect .fi .SS Updating and removal @@ -216,6 +216,8 @@ The installer and control console stay text interfaces in both TTY and a desktop fb status fb doctor .fi +.SS Guarded X11 text compatibility +Graphical TYPE in KEYS mode uses the guarded native X11 backend on x86\-64 LP64 systems with libxdo 3.20160805.1. This private candidate accepts active keyboard group 0 only, with no held or latched modifiers and only conventional Caps Lock and Num Lock locked bits. The whole string and generated key actions are checked before any input. Unsupported groups, characters, actions or keyboard states fail closed. The backend does not change the keyboard group or map and does not use the clipboard. Display session, fixed target window, geometry and keyboard context are checked while sending. If input may have started and an error follows, inspect the target and do not automatically replay the text. .SS Frame\-buffer read access screen\-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication. .PP diff --git a/source/expanded/framebridge_expanded/__init__.py b/source/expanded/framebridge_expanded/__init__.py index 53ce8bc..6fd3ae5 100644 --- a/source/expanded/framebridge_expanded/__init__.py +++ b/source/expanded/framebridge_expanded/__init__.py @@ -1 +1 @@ -__version__ = "0.3.2+private.20261028.1" +__version__ = "0.3.2+private.20261028.2" diff --git a/source/expanded/framebridge_expanded/guide_data.py b/source/expanded/framebridge_expanded/guide_data.py index b87fe88..0bf198e 100644 --- a/source/expanded/framebridge_expanded/guide_data.py +++ b/source/expanded/framebridge_expanded/guide_data.py @@ -304,6 +304,9 @@ GUIDE = {'start': {'title': 'Start with FrameBridge', {'heading': 'Automatic graphical discovery', 'body': 'The installer and control console stay text interfaces in both TTY and a desktop terminal. Compatible graphical CUA is discovered automatically; availability depends on the actual display/session and permissions. A loaded module is not proof that real pixel capture or input succeeded. New profiles use adaptive auto mode: without a verified active X11 session the runtime provides FBEXEC, FBTERM and CUA-TTY in text mode, without requiring a graphical login or automatically creating a private desktop. Explicit virtual-desktop settings remain advanced options and are labelled separately from physical-screen evidence. Xvfb and Openbox are optional package suggestions and are not installed for the normal connection. Only when you choose a private virtual desktop, install its tools explicitly with sudo apt install xvfb openbox xauth and rerun fb doctor. Installing Openbox can register it as the generic window-manager alternative; use your distribution settings to retain your preferred manager when needed. Physical-screen capture and input currently require the supported active X11 session. Native Wayland control is not validated; showing an XWayland window does not establish full-desktop capture or input.', 'commands': ['fb status', 'fb doctor']}, + {'heading': 'Guarded X11 text compatibility', + 'body': 'Graphical TYPE in KEYS mode uses the guarded native X11 backend on x86-64 LP64 systems with libxdo 3.20160805.1. This private candidate accepts active keyboard group 0 only, with no held or latched modifiers and only conventional Caps Lock and Num Lock locked bits. The whole string and generated key actions are checked before any input. Unsupported groups, characters, actions or keyboard states fail closed. The backend does not change the keyboard group or map and does not use the clipboard. Display session, fixed target window, geometry and keyboard context are checked while sending. If input may have started and an error follows, inspect the target and do not automatically replay the text.', + 'commands': []}, {'heading': 'Frame-buffer read access', 'body': 'screen-access is a narrow, explicit administrative permission ' 'for reading the real frame buffer. It does not by itself '