Shared platform glue and device tooling for CheerChen's LG webOS TV apps.
Each app mounts this repo as a git submodule at tvkit/:
git submodule add https://github.com/CheerChen/webos-tv-kit.git tvkit
# when cloning an app:
git clone --recursive <app-repo>
# or after a plain clone:
git submodule update --initClassic script (ES5, no dependencies) that attaches window.WebOSPlatform:
send(uri, params, onResponse)— thinPalmServiceBridgewrapper; returnsnullwhen the bridge is absent (desktop browser).- Screensaver guard over
luna://com.webos.service.tvpower, in two styles:initScreenSaverGuard(isActiveFn)(the guard asks the app on every request) orinhibitScreenSaver()/allowScreenSaver()(the app flips the veto). Handles the errorCode -3 stale registration left behind by a CDPPage.reload. exitApp()—webOSSystem.platformBack→PalmSystem.platformBack→window.close().
Load it before the app scripts:
<script src="tvkit/js/webos-platform.js"></script>The screensaver guard only works once the app is registered on the Luna bus.
ares-install does that for you; sideloaded/rooted installs need the
role/permission/manifest files plus ls-control scan-services and a cold
restart.
All Python scripts are single-file uv run scripts (PEP 723 inline deps) and
share the same conventions: a CDP tunnel on localhost (default port 9977,
ssh -f -N -L 9977:localhost:9998 <tv-host>) and --target <substring> to
pick the app's page out of the CDP target list (first page when omitted).
| Script | Purpose |
|---|---|
cdp_eval.py |
Run JS (stdin) inside the live app's real origin |
cdp_reload.py |
Page.reload the file:// page in place — the hot-update loop is scp + this |
cdp_screenshot.py |
Page.captureScreenshot → PNG |
cdp_net.py |
Capture Network events: Set-Cookie and cookie-block reasons |
cdp_keys.py |
Dispatch trusted remote-control keys via Input.dispatchKeyEvent |
cdp_trace_keys.py |
Drive the app with key sequences and capture console/log output — the keyed variant of cdp_keys.py (keys via document.dispatchEvent, console via Runtime.enable / Log.enable) |
tv_luna.py |
Luna calls / app (re)launch over Telnet (SSH luna-send is ACL-dropped on rooted TVs) |
Examples:
echo 'location.href' | uv run tvkit/scripts/cdp_eval.py --target photofield
uv run tvkit/scripts/cdp_reload.py --target navidrome
uv run tvkit/scripts/cdp_keys.py --target decotv down down right ok
uv run tvkit/scripts/cdp_trace_keys.py --target photofield --keys "ok,ok" --delay 5
uv run tvkit/scripts/tv_luna.py --relaunch com.cheerchen.decotvShared IPK build: stages an explicit payload list, gates it against a recorded
contents file and a size ceiling, runs ares-package -n, and optionally syncs
a Homebrew Channel manifest (--release / --verify-release). Apps keep a
thin scripts/package.sh wrapper passing their own file list — see the header
comment for the full flag reference and the rationale for each gate.
Procedures and verified dead ends for rooted LG webOS TVs, in the Agent Skills
format (SKILL.md), readable by Claude Code, Codex and other agents:
| Skill | Covers |
|---|---|
webos-root-web-debug |
CDP live debugging, hot reload, webview cookie/CORS facts |
webos-root-app-install |
IPK sideloading, Luna bus registration, screensaver veto, reinstall |
webos-root-debloat |
Hiding/removing preinstalled apps, freeing RAM |
webos-root-media-tuning |
Decode pipeline, codec capabilities, HDR / frame-rate config |
AGENTS.md routes symptoms to the right skill. To install the skills in
Claude Code:
/plugin marketplace add CheerChen/webos-tv-kit
/plugin install webos-tv-kit@webos-tv-kitOther agents: point them at AGENTS.md, or copy skills/* into the agent's
skills directory.
npm run check # node --check + unit tests (node:assert, no deps)MIT