# luma-home

Replaces the LG webOS Home screen with [Luma](https://github.com/ecklf/lg-luma) on webOS 5/6 TVs rooted via [Homebrew Channel](https://github.com/nicko88/LG-Homebrew).

## How it works

LG Home (`com.webos.app.home`) is a native QML app. This project bind-mounts a transparent web page over its directory so SAM sees a web-type Home. The web page immediately calls `WebOSServiceBridge` to launch Luma. A background watcher provides a fallback redirect via `luna-send` subscription.

### Components

| File | On TV at | Purpose |
|------|----------|---------|
| `overlay/appinfo.json` | `/media/developer/luma-home/overlay/` | Home manifest — web type, transparent, no splash |
| `overlay/index.html` | same | Minimal page that launches Luma via WebOSServiceBridge |
| `boot-hook.sh` | `/media/developer/luma-home/` | Homebrew Channel boot hook — mounts overlay, restarts SAM, launches Luma |
| `watcher.sh` | same | Background watcher — subscribes to foreground events, redirects Home→Luma |

### Boot flow

1. Homebrew Channel runs `boot-hook.sh` at cold boot
2. Bind-mount replaces `/usr/palm/applications/com.webos.app.home` (RAM only — reboot without the hook restores stock)
3. SAM restarts and reads the web manifest
4. Luma launches as the initial app
5. Watcher starts in the background

### Home button flow

1. User presses Home → system opens `com.webos.app.home` (our transparent web page)
2. `index.html` JS fires `WebOSServiceBridge` → launches Luma
3. Watcher catches the foreground change as backup → also launches Luma

## Requirements

- LG webOS TV rooted with Homebrew Channel (tested on webOS 6.5.3)
- Luma v2.1.0+ installed as `com.ecklf.luma`
- Telnet or SSH access to the TV

## Install

```sh
# Copy files to TV
scp -r overlay/ boot-hook.sh watcher.sh root@<TV_IP>:/media/developer/luma-home/

# SSH into TV and install the boot hook
chmod +x /media/developer/luma-home/boot-hook.sh /media/developer/luma-home/watcher.sh
ln -sf /media/developer/luma-home/boot-hook.sh /var/lib/webosbrew/init.d/10-luma-home

# Run it now (or reboot)
sh /media/developer/luma-home/boot-hook.sh
```

## Uninstall

```sh
# Remove boot hook
rm /var/lib/webosbrew/init.d/10-luma-home

# Kill watcher
kill $(cat /tmp/luma-watcher.pid 2>/dev/null)

# Unmount overlay (or just reboot)
umount /usr/palm/applications/com.webos.app.home
```

## Known limitations

- Brief visual transition when pressing Home (web page loads before Luma appears)
- `blockSystemApp` API (used by Luma's built-in Home integration for webOS 25/26) does not exist on webOS 5/6, so we use `systemctl restart sam` instead
- Native Home replacement (Luma binary as Home directly) does not work on webOS 6 — SAM handles native system apps differently

## Future

Fork Luma and patch `home.cjs` to support webOS 5/6 natively — replace the version check and `blockSystemApp` calls with the `systemctl restart sam` approach proven here.

## Tested on

- LG 65NANO813PA, webOS 6.5.3-47 (kisscurl-koli)
- Luma v2.1.0
- Homebrew Channel v0.7.3