docs menuinternals

internals

how the loader, in-process agent, and plugin host divide the work.

the layers

the core operates on native machine code, independently of the app’s ui framework. injection, byte checks, string-anchor resolution, patches, and detours use adapter-defined addresses and operations with supported calling conventions. stable extension contracts connect those sites to app-specific behavior. manifests describe packages and app-defined capability strings; themes describe named colors; the plugin host carries hook names and opaque byte payloads. an adapter joins that contract to one app build.

the loader handles platform entry and verification. the injected agent runs inside the target process and installs supported native hooks or writes. an event probe copies its configured arguments and enqueues an observation; wasm runs on a dedicated plugin worker, outside that native call’s execution path.

identity and site checks

the loader launch path compares the executable against the adapter’s whole-file identity before starting it. a different build is refused. the agent then resolves and checks individual sites inside the running image, accounting for where the operating system loaded it.

string-xref anchors re-find supported function entries; byte signatures guard supported sites against drift. expected bytes are checked before each live change. a unique byte pattern alone does not prove that a candidate is the intended function, so adapter authors must establish that identity separately.

how the agent checks one sitethe agent locates each adapter site in the running image. an absent or ambiguous site is skipped and reported. a found site changes only if its expected bytes still match; otherwise it is skipped and reported.absent orambiguousfoundnoyeslocate siteskip and reportbytes match?live change
how the agent checks one sitethe agent locates each adapter site in the running image. an absent or ambiguous site is skipped and reported. a found site changes only if its expected bytes still match; otherwise it is skipped and reported.absent orambiguousfoundnoyeslocate siteskip and reportbytes match?live change

direct loading and the wrapper do not use the strict loader launch gate. the agent reads its own executable and refuses to continue if it cannot read it. it reports a non-exact build, then attempts supported relocation and per-site checks. that drift path does not make stale offsets or a coincidental prologue a reliable identity.

changes in memory

color sites identify a value, its location, and its encoding. the adapter can describe packed colors, floating-point channels, or HSLA values such as those used by gpui. the same backend writes the mapped representation; locating the right field or render call belongs to the target integration.

argument and return hooks act on opposite sides of the original call. an argument override changes an input before the body runs; a return override changes its result afterward. both preserve the body’s side effects. a fixed-length force-return byte patch instead prevents that body from running.

where each behavior change actsan argument override changes an input before the original body runs. a return override changes the result after the body, so the body's side effects still happen. a force-return byte patch returns without running the body.force-return patchcallargument overrideoriginal bodyreturn overrideresult
where each behavior change actsan argument override changes an input before the original body runs. a return override changes the result after the body, so the body's side effects still happen. a force-return byte patch returns without running the body.force-return patchcallargument overrideoriginal bodyreturn overrideresult

the constant-result replacement backend uses a native entry detour to skip the body. it currently supports integer, pointer, and boolean results in the primary return register. the backend is implemented and unit tested; end-to-end live target verification is still pending.

live byte patches write into the target’s existing memory after checking the expected bytes. they do not allocate arbitrary new native code or change the executable’s file hash. the macos backend’s ability to write executable text depends on the process’s signing policy; a required policy prevents that write.

the offline helper is separate: it writes an executable copy on disk, which then needs the appropriate signing treatment. the wrapper is separate again: it edits bundle metadata and re-signs. see the runtime matrix for the exact distinction.

native ui and overlays

the current native ui experiments use gpui-specific paint and settings seams on one pinned release build. calling the app’s own paint method appends a card drawn from quads to its live scene; text and image sprites remain pending. extending its returned settings-page list adds an entry that the app routes itself. both affect the app’s own window.

these proofs use custom agents and a cloned, ad-hoc re-signed app copy. another renderer needs its own paint, layout, and routing mappings, using the same native patch engine. the experiments are not reusable adapter operations or a general plugin ui api yet; arbitrary element synthesis and view-tree editing remain separate work.

the companion overlay is a separate prototype: its own window draws controls, handles clicks, and passes clicks through transparent areas. that window remains distinct from the native scene and settings-entry experiments.