tv-shell

Imported from itsgsimi/bear-den-tv (apps/tv-shell/AGENTS.md). Install upstream with npx skills add itsgsimi/bear-den-tv --skill tv-shell. Copyright stays with the author.

apps/tv-shell/: the TV shell (Qt 6.8, QML + C++)

bear-den-tv-shell is everything on the TV between apps: Home, Settings, pairing, dialogs, themes and bears. It owns presentation and the focus graph and nothing else. The coordinator starts and supervises it and talks to it over the private socket in contracts/ipc.md. It never launches apps, reads config files or listens on the network.

The whole shell is one static QML module BearDen (library beardenshell, CMakeLists.txt). The executable and the tests link the same module, so tests exercise the shipped QML.

C++ types exposed to QML

QML singletons: Apps.qml (per-adapter copy and brand colours), Badges.qml (Den badge names, hints and art by id), Help.qml (one plain sentence of help per settings row id: Settings, Themes, Apps, setup) and World.qml (the active theme as components see it), marked QT_QML_SINGLETON_TYPE in CMake.

main.cpp flags

src/main.cpp: --dev (honours BDTV_SHELL_SOCKET), --fixture PATH (offline: render a state snapshot, no coordinator), --screen home|apps|themes|settings|pairing|devices|diagnostics|remote-setup|playback|advanced-playback|weather|plex|badges|onboarding (any screen in ShellRoot's screens map; also onboarding-0 … onboarding-5 for one setup step, and the old names streaming and add-apps, which open the Apps page at that section), --windowed, --size WxH (default 1920x1080), --screenshot PATH, --screenshot-after MS (default 1500), --screenshot-every MS (--dev only), --exit-after MS. Environment variables:

QML files

Animation and performance gates

The floor is a 2-core Celeron at 120 Hz. Rules: docs/THEMES.md → Performance rules. The convention is one alive property that every timer and animation binds to:

readonly property bool alive: visible && !Theme.reducedMotion && !Theme.resting
                              && !Theme.screensaver && Session.target.kind === "shell"

(CampScene.qml, DenFamily.qml, HeroDecor.qml; FocusDecor.qml keeps its slow focused motion while resting.) Anything that loops moves on the shared heartbeat, not its own Timer or a looping animation:

Connections {
    target: World
    enabled: root.alive
    function onBeat(dt) { root.phase += dt }   // 20 beats/s awake, 4 resting
}

Separate timers each trigger their own frames and their rates add up; the heartbeat puts every change in one frame. Canvas repaints only when inputs change (each repaint costs one extra frame), no shaders. make perf fails when resting or the screensaver draws over budget. Durations go through Theme.ms()/Theme.duration so reduced motion collapses them to 0. Theme.resting is set by ShellRoot after 45 s without input.

CMake file lists

• QML: every QML/JS file is listed explicitly in BDTV_QML_FILES in CMakeLists.txt. A new file that is not listed is simply missing at runtime. QML is addressed as qrc:/qt/qml/BearDen/<File>.qml.
• Pixel art and ornaments: assets/pixel/*.png and assets/ornaments/*.{png,svg} are globbed (CONFIGURE_DEPENDS) into BDTV_ASSETS, addressed as qrc:/qt/qml/BearDen/assets/.... Regenerating art with tools/pixelart needs no list edit.
• Theme packages: themes/** is globbed into :/themes/<id>/.
• C++: new files go in SOURCES.

Add a screen

1. Write qml/<Name>Screen.qml: an Item with enter(), navigate(action) returning true when it consumed the action, and optionally report(), opened() (called only on a fresh visit, not when a page it opened pops back: start at the top there) and leave(); it reports focus with Nav.reportFocus(...).
2. List it in BDTV_QML_FILES in CMakeLists.txt.
3. In ShellRoot.qml: instantiate it in the safe item with the same opacity/y pattern as its siblings and register it in the screens map.
4. Open it with openScreen(name) from another screen (a Settings link row, see below).
5. If its name is not one of the contract's shell.screen values, map it in navScreenName() (remote-setup and onboarding report setup; playback and advanced-playback report diagnostics; apps, themes, weather, plex and badges report settings). A name that should land on a section of another screen goes in ShellRoot's aliases.
6. --screen <name> in main.cpp then works for it too.

Back pops the stack; at Home it is a reported no-op, never an exit.

Done when: make test-shell passes with a test that opens it, and scripts/sandbox.sh shot --screen <name> shows it (you looked).

Settings rows

SettingsScreen.qml has two levels: a list of categories (a card with a Bear Den icon each; section settings-categories, items phones, display, home, playback, power, about) and, after OK, that category's rows (section settings, items the row ids). Back from a row's page returns to its row, from a category to that category, and from the categories Home; opening Settings from Home shows the categories on the one last used. Rows are data: allRows holds every row by id as {id, kind, label, description, value} with kind one of link, choice, toggle, danger, info, rendered by SettingsRow.qml, and categories lists each category's row ids. Beside the list, HelpPanel shows the focused row's help from Help.qml (one table by row id; engine code only looks ids up).

Where the rows of the old single list went (every one reachable exactly once, everyFormerSettingIsReachableOnceWithHelp): background (Theme), style, art, app-icons and badges are on the Themes page (ThemesScreen; the theme is the card strip, the badges a card that opens BadgesScreen); add-apps, streaming and auto-update are on the Apps page (AppsScreen: the Add apps cards, the streaming site and browser rows, Keep apps up to date); every other row is in the category above.

1. Add the row to allRows and its id to a category's rows (the order there is the order on screen). Copy goes through qsTr.
2. choice: a case in change(row, delta) (◀ ▶). toggle or link: a case in activate(row) (OK). A link opens a screen with openScreen(name).
3. Its one-line help: an entry in Help.qml (and the same words in the phone's SETTING_HELP if the phone shows the setting).
4. Appearance settings are layout fields: edit through editUi(u => u.<field> = ...), which sends Shell.updateLayout; the coordinator validates and persists. A new ui field is a contract change (contracts/AGENTS.md).
5. Update tests/tst_shell.cpp. Tests reach a row with toSettingsRow(id): it asks the screen which category holds the row (categoryOf(id)), goes there with toSettingsCategory(category) (Back to the categories, down to it, OK), to the category's top, then down until that row, so a new row shifts nothing. openSettings() opens Settings from the top bar; openFromHeader(pill) any pill. everyFormerSettingIsReachableOnceWithHelp walks every category, the Themes page and the Apps page with the D-pad and fails when a former row is missing or twice, or an entry has no help. A snapshot rebuilds the rows; the list keeps the focused row in view (onModelChanged).

Done when: make test-shell passes and scripts/sandbox.sh shot --screen settings shows the row (you looked).

First-run setup

OnboardingScreen.qml opens over Home when the first snapshot that carries state.onboarding says completed: false (ShellRoot.checkOnboarding, once; an older coordinator sends none and a later snapshot never reopens it), and from Settings → About → Run setup again. Six steps with progress dots: Welcome, Your look (Pixel or Classic, then the ThemePicker cards), Your apps (one-press cards that open the install card; a "Streaming sites" card turns Netflix, Disney+ and Hulu on (Apps.isStreamingSite) and offers their browser's install card), Phone remote (plain-language consent, the network to allow it on through Shell.configureRemote, then Pair a phone opens PairingScreen), Extras (Plex, Weather, Start with this PC through Shell.setAutostart) and Done (Go Home sends Shell.completeOnboarding() → IPC onboarding.complete). Every step has Skip; Back returns to the step you came from, and on the welcome leaves the setup (it shows again at the next start). Nothing is installed, enabled or stored until OK on that thing. Sections report as onboarding-<step>. Tests: onboardingOnFirstRunSkipAndComplete. Screenshots: scripts/sandbox.sh shot --installs --screen onboarding-<step>.

Bear tips

Session.tips is state.tips (config tips, contracts/config.md): which tips were already shown, whether the bears stopped offering them (three "Not now" in a row) and the local day of the last one. The shell reports each tip with Shell.tipEvent(tip, "seen" | "ok" | "not_now"); Settings sends Shell.setTips(enabled) and Shell.resetTips() (IPC tips.*, contracts/ipc.md).

qml/TipBear.qml is the bear. Its table holds every tip's copy, pill, hat and prop in order (Themes, Add apps, Phone remote, Now playing, Sleep timer, Den badges, Guest passes); applies(id) skips a tip whose feature is already in use (e.g. a phone is paired). The rules, all tested in bearTipsFollowTheRules and bearTipsEachShowInBothStyles:

• allowed (ShellRoot): Home only, first-run setup done, no dialog, card, launch, lock, screensaver, badge card or app in front. Leaving Home only sends the bear off; it is not an answer.
• The tipQuiet timer (Shell.tipSeconds, 8 s, BDTV_TIP_SECONDS) runs only while allowed, on, and no tip was shown today (the tests set today); every key restarts it (poke()).
• The tip never takes focus. While it waits, ShellRoot's handle() gives OK to "Show me" (ok, then showMe opens the place) and Back to "Not now" (not_now); any other key sends the bear off and carries on.
• "seen" only stamps the day; ok and not_now make the tip done, and the coordinator stops the bears after three not_now in a row.
• It moves only on World.beat while walking or hopping (World.visiting); sitting it draws nothing new. Reduced motion: it appears sitting. scripts/perf-sandbox.sh --tips checks a waiting bear adds no frames.
• Never branch on a theme id: the bear's look comes from World and the ornaments.

App tiles and branding

Supported apps are a closed set keyed by adapter name (plex-htpc, vacuumtube, moonlight, the optional spotify, jellyfin, retroarch, and the web apps netflix, disney-plus, hulu, browser; tiles are skipped while hidden); engine code never branches on a display name. Apps.note(adapter) is a short line a tile shows while the app has not been opened since Bear Den started (the streaming sites' "Up to 720p"); the web apps reuse existing rooms (cinema, theatre, cabin, nook). For a new app, after internal/AGENTS.md → Add an app:

Artwork: Bear Den bundles its own original app icons, never third-party logos (docs/THEMES.md → App icons). Shell.appArt(adapter, classic, icons) returns {icon, logo, background, iconSource}; the icon comes, in order, from the owner's brand folder ~/.local/share/bear-den-tv/brand/<adapter>/ (icon|logo|background + .svg|.png|.jpg|.webp; logo and background come only from there); with icons "app" (Theme.appIcons, layout ui.app_icons, the default: Themes → App icons → App's own) the icon the installed Flatpak exports when that Flatpak is the app itself (ownIconFlatpakIdFor: never Chrome's for the streaming sites, the Browser tile may show its browser's; an app that is not installed has no export); Bear Den's own icon (assets/pixel/app-<adapter>.png, or with classic assets/classic/app-<adapter>.svg); AppIcon draws a monogram when there is none. Results are cached for a minute. Every place an app is shown goes through AppIcon (tiles, the featured panel and its room's screen, the launch overlay, the install card, Add apps). A new app needs its icon in tools/pixelart/appicons.py and tools/classicart/appicons.py (appArtResolutionOrder checks every adapter has both).

Change the look

Most look changes are not QML changes. Start in docs/THEMES.md → Make it yours:

Engine QML reads the active theme only through World (World.qml) and never checks a theme id.

Tests

tests/tst_shell.cpp loads the real BearDen module offscreen from tests/fixtures/state.demo.json (offline ShellController, animations forced off) and drives it through Nav.apply, exactly like coordinator input:

• act("nav.right") applies an action and processes events; goHome(), toHeader(), toFavorites(), toFavoriteTile(id), openFromHeader(pill), openSettings(), toSettingsCategory(id) and toSettingsRow(id) walk to a known start; shellScreen() is ShellRoot's own screen name (Nav.screen is the contract's).
• fixture() returns the demo snapshot; tests modify a copy and call SessionModel::instance()->applySnapshot(...), then restore it.
• shot(name) saves a PNG when BDTV_SCREENSHOT_DIR is set.

pairing.guest-demo.json is a DEMO guest invitation with a real QR for the Pair screen test. The fixture's apps, sections and device ids (plex-htpc, youtube, plex-continue, demo-1, dev_a1) are asserted by name. The shell does not run the contracts/fixtures files; its schema checks are in SessionModel.

Render offscreen and look

The quick way (scripts/sandbox.sh; run make shell first after a QML change, the script only builds a missing binary):

scripts/sandbox.sh shot --screen settings --theme forest   # prints the PNG path
make shots                                                 # every theme × main screens

The same by hand:

make shell
QT_QPA_PLATFORM=offscreen build/bin/bear-den-tv-shell \
  --fixture apps/tv-shell/tests/fixtures/state.demo.json --windowed --size 1920x1080 \
  --screen settings --screenshot /tmp/shell.png --screenshot-after 2600 --exit-after 3400

Then open the PNG. For a theme, see docs/THEMES.md → Preview and validate.

Checks

make test-shell     # configure build/tv-shell with tests, build, ctest offscreen
make lint           # includes qmllint (all_qmllint); configures build/tv-shell first if it is missing
make shell          # release binary into build/bin/
make perf           # frames and CPU per phase of Home, offscreen on two cores