docs menuhandling app updates

handling app updates

discover sites, monitor changes, and understand what can relocate after a rebuild.

exact builds

recompiling a native app can move code, change instructions, and remove the bytes a patch expected. an adapter therefore identifies an exact build. themes and plugin modules express behavior, while the adapter records where that behavior can reach the app.

the loader’s whole-file launch gate remains strict. direct loading uses a different path: the agent refuses an unreadable executable, reports a non-exact build, then tries supported relocation and per-site checks. there is no --allow-drift switch.

monitoring a build

the monitor reads an adapter and executable without starting or changing the application. it reports build identity and which color, event, and byte-patch sites still match:

./target/debug/fpui-monitor adapter.json /path/to/app-binary --json --label test-build

--json selects machine-readable output and --label names the checked build. a broken reported site produces a nonzero exit status. the monitor is report-only; it does not install patches or update adapters.

checking a new app buildthe monitor reads the adapter and new executable without changing either. if the checked sites match, the report passes for those sites. if a site is broken, discovery suggests candidates, and you validate them and update the adapter.yesbrokenmonitorsites match?green reportdiscoveryyou validate
checking a new app buildthe monitor reads the adapter and new executable without changing either. if the checked sites match, the report passes for those sites. if a site is broken, discovery suggests candidates, and you validate them and update the adapter.yesbrokenmonitorsites match?green reportdiscoveryyou validate

return, argument, and replacement sites are not covered by the report, and it does not exercise the complete anchored live path. a green report is useful evidence for the sites it checked, not proof that every engine feature or application integration works.

the JSON report includes the build hash, identity match, timestamp, optional label, and per-site resolved offsets. save each output line to keep a history across builds. a passing site report does not override a whole-file identity mismatch.

discovery and anchors

the discovery tool can start from a symbol, a known offset, or a referenced string. it emits an adapter entry and a signature describing a unique byte window. these are usage examples; replace the binary path, symbol, offset, and string with values established for your target.

./target/debug/fpui-discover /path/to/app-binary --symbol function_name --token example
./target/debug/fpui-discover /path/to/app-binary --offset 0x1000 --token sidebar
./target/debug/fpui-discover /path/to/app-binary --anchor "unique source string" --token example
./target/debug/fpui-discover /path/to/app-binary --symbol function_name --force-return 0

--also can add other builds when extracting a signature, so the window is checked for uniqueness across them. --force-return generates an aarch64 byte patch containing a constant return sequence; it does not apply that patch.

a string anchor finds a unique string reference and resolves it to a containing function. this has been demonstrated on stripped aarch64 Mach-O release binaries across rebuilds. it is not arbitrary symbol recovery or universal target detection.

relocation limits

use a string-xref anchor to identify a function entry where supported. a byte signature is a secondary drift guard, not proof that matching code belongs to the same function. even a unique prologue can match another function after a rebuild.

when a supported site has a signature, the pinned offset only wins if the wider signature window agrees. otherwise the resolver scans for one unique signature match and rechecks the expected bytes at the recovered site. matching a few expected bytes at the old offset is not enough.

the live resolver handles anchors for event, return, argument, and replacement function entries. color and event sites also use byte signatures. unanchored return, argument, and replacement sites remain pinned to their offsets; adding a signature field alone does not give them a live signature backend.

live byte patches also remain pinned in the current backend. the offline helper and monitor can locate byte patches by signature. expected bytes are checked again before a live write, even after a location is found.

if a signature or anchor is missing or ambiguous, the affected site is skipped and reported. relocation can recover a moved site; it cannot make changed machine instructions mean the same thing.

application updates can also replace a wrapped bundle. check the new executable and adapter, then wrap it again if that development workflow is still appropriate.