luma-home/agents.md

Luma agent context

Project

Luma is a native Rust/SDL2/OpenGL ES 2 launcher for rooted LG webOS TVs. Rust source is in src/, original assets/translations in assets/, shared vector geometry in vector-geometry/, the host SVG compiler in tools/vector-assets/, packaging/tooling in tools/, and desktop smoke scripts in tests/. There is no React/JSX/browser application. Read development.md for details.

Use pnpm, Oxlint and Oxfmt for build tools; Cargo/rustfmt/Clippy for Rust. nix develop supplies pinned Rust 1.93, ARMv7 std, Node 24, pnpm 10.34.5, SDL2, woff2 and Python/fontTools. The webOS SDK is separate: pnpm sdk, then set WEBOS_NDK to .build/toolchain/arm-webos-linux-gnueabi_sdk-buildroot.

pnpm install --frozen-lockfile
pnpm format:check
pnpm check
pnpm test
pnpm assets
pnpm test:smoke
pnpm run package

pnpm check does not execute tests. pnpm test is workspace unit tests; smoke scripts render desktop OpenGL and mock weather HTTP. Linux can use xvfb-run -a pnpm test:smoke. Tests must not contact real weather APIs or a TV. Respect any user instruction to use manual TV verification instead of running automated tests. Builds/lint may still be run. Do not claim hardware behavior from desktop checks. Add a pnpm changeset file for release-worthy changes and leave version bumps to the automated Version Packages PR. Its pnpm version:release command synchronizes package.json, appinfo.json, the root Cargo.toml, the luma entry in Cargo.lock and README IPK examples. Supporting Rust crates retain independent versions. pnpm version:check checks consistency without writing files. Code or behavior changes should use semantic versioning: patch for backward-compatible fixes, minor for backward-compatible features, and major for breaking changes. Documentation-only or maintenance changes that do not need a release can omit a changeset.

Build and identity

com.ecklf.luma is the native app's ID and luma its executable. Root appinfo.json is the package metadata source. It installs separately from the former web app com.luma.launcher and prototypes com.luma.launcher.native and com.luma.native, all excluded from app inventory. Preferences are local JSON per installation; browser local storage and preferences from other IDs are not migrated.

ARM builds must use the NDK's gnueabi soft-float calling convention and explicit sysroot, with isolated pkg-config. Preserve the Cortex-A9/VFP Rust flags and getauxval compatibility. The SDK's SDL has dummy video: use checksum-pinned SDL-webOS with standard SDL ABI and a real webOS/Wayland backend. Do not use rust-sdl2's generic bundled SDL or ship host libraries. Native packages use Architecture: arm, preserve executable mode and include licenses/checksums/feed.

Runtime constraints

Keep input/rendering on the SDL thread and TV/HTTP work off it. Luna requests originate from the native process, not luna-send-pub -a impersonation. Inventory failure must never substitute demo data on TV. Explicit --test-extra-apps is a labeled manual preview applied only after successful inventory reads, with separate preferences and no placeholder launch requests.

Pointer hover/down must not move a clicked control. Home favorites use one horizontal strip; remote focus/reordering reveals the whole selected card. Apps Up/Down follows six-column grid indices, including offscreen rows, so headers cannot steal mid-grid navigation. Back restores setting subpage parents and supports SDL-webOS Back. OK finishes move mode without launching.

Vector icon/logo assets are standalone SVGs compiled to .lvec at build time. Font outlines are tessellated only as needed; text runs use bounded GPU caches, lazy CJK and no glyph bitmap atlas. Text AA prefers MSAA of intact outlines, with a narrow fringe fallback; keep physical origin/baseline snapping and logical 1920×1080 layout. --resolution 4k is experimental, not a shipping-default claim. Profiles count presentations; ordinary --frames is event-loop iterations.

Weather uses ureq/rustls, fixed Open-Meteo origins, bounded replies/timeouts, no proxy/redirects, separate workers/cache and generation IDs. Cache Celsius and convert units without replacing it. Only configured/enabled/visible Home starts forecasts. Shared translations are bundled locally. Match the current native design without on-screen weather credits; attribution remains in docs.

Assets

SVG sources and fonts retain licenses in assets/. TV app artwork is resolved at runtime from inventory/installed manifests by src/app_artwork.rs, with an embedded Node 8-compatible elevated reader for jailed installations. Reads/decoding stay on its worker; GPU uploads stay on SDL. Refresh invalidates cached results. No collected icon map or card-colour JSON is used or shipped. Desktop previews use curated vectors and generic/category fallbacks. Do not add dumped TV images or per-TV icon maps to the repository. Do not replace vector logos with PNG exports. Curated vectors use the exact app-ID allowlist in src/branding.rs, never title/substring matching. Every logo in assets/logos/ must have a desktop demo app. pnpm test:brands renders the full gallery to .build/brands-gallery.png; source restoration via pnpm assets:brands is optional.

CI and releases

.github/workflows/ci.yml is native-only: format/lint/workspace tests, asset generation and mocked desktop rendering, SDK setup, ARM cross-build, actual IPK verification/checksum/feed, artifacts and guarded publication. Keep existing published-version/draft/tag-commit checks. .github/workflows/changeset-status.yml maintains an informational changeset status comment on PRs, including forks, with semantic-version guidance for code changes. It skips the generated version PR. Its pull_request_target jobs must not install dependencies or run code from the PR. .github/workflows/release-pr.yml maintains the Changesets version PR and dispatches its CI checks with the built-in token. Only a merged changeset-release/main PR with a version increase can publish after the main-branch CI build passes. Ordinary PRs, other merges and manual CI runs still build/check/package but do not publish. See development.md#releases for setup and retries. Only create commits or PRs when explicitly requested. For PR descriptions follow the global commands/pr.md format instructions.