@tantawowa/hosanna-tools 3.32.0 → 4.0.1

package/README.md

@@ -1,5 +1,9 @@
 # hosanna-tools
 
+This package lives in `packages/tools` in the Hosanna UI monorepo. It retains its
+own package name, version, and lockfile. Run its development commands from this
+directory; framework source remains at the repository root.
+
 ## Agent skills
 
 The repository instructions use TantaWowa's ClickUp workflow skills, Matt
@@ -7,7 +11,7 @@ Pocock's engineering skills, and pstack's `unslop` skill. Install them once on
 each developer machine:
 
 ```sh
-npx -y skills add TantaWowa/hosanna-tools --global --skill work-on-ticket hope-platform-planning hope-platform-architecture-ownership --agent '*' --full-depth --yes
+npx -y skills add TantaWowa/hosanna-tools --global --skill work-on-ticket --agent '*' --full-depth --yes
 npx -y skills add mattpocock/skills --global --all
 npx -y skills add cursor/plugins --global --skill unslop --agent '*' --full-depth --yes
 ```
@@ -21,10 +25,10 @@ Run `npx -y skills update --global --yes` to update the installed skills later.
 ## Documentation
 
 - **[MCP debugger](src/support-tools/mcp-server/README.md)** — `hst mcp:start`, debugger tools, commands by use case, examples, and RASP certification capture.
-- **[Video capture](docs/video-capture.md)** — standalone, agent-driven, and test-run recording for Apple simulators, physical-TV capture cards, and macOS windows.
-- **[Browser, Tizen, and webOS](docs/browser-tizen-webos.md)** — canonical commands, desktop previews, package/device workflows, vendor trust, and CSP/LAN policy.
+- **[Video capture](docs/video-capture.md)** — standalone, agent-driven, and test-run recording for Roku capture cards and browser emulator windows.
+- **[Roku and browser emulation](docs/roku-browser-emulation.md)** — supported launch commands, device selection, and emulator configuration.
 - **[docs/README.md](docs/README.md)** — index of docs in this repo (MCP + source-map note).
-- **hosanna-ui** (separate repo): `docs/README.md` for agentic debugging and links back to this README.
+- **[Hosanna UI framework](../../docs/README.md)** for agentic debugging and framework documentation.
 
 ## To use the tool
 
@@ -101,7 +105,7 @@ await buildConfig.resolve({
 await compiler.install({ version: '0.33.7' });
 await roku.package({ env: 'prod', prebuild: 'npm run roku:build:prod' });
 
-const recording = await capture.start({ platform: 'ios', device: 'iPhone 17 Pro' });
+const recording = await capture.start({ platform: 'roku', videoDevice: 'USB Video' });
 // Drive the app manually, through MCP, or through another automation API.
 await recording.stop();
 ```
@@ -115,7 +119,7 @@ Common build-script replacements:
 | `npx hst build-config:resolve --env dev --platform roku --out assets/meta/build-config.json` | `await buildConfig.resolve({ env: 'dev', platform: 'roku', out: 'assets/meta/build-config.json' })` |
 | `npx hst compiler:install 0.33.7` | `await compiler.install({ version: '0.33.7' })` |
 | `npx hst roku:package --env prod --prebuild 'npm run roku:build:prod'` | `await roku.package({ env: 'prod', prebuild: 'npm run roku:build:prod' })` |
-| `npx hst capture ios --device 'iPhone 17 Pro'` | `await capture.start({ platform: 'ios', device: 'iPhone 17 Pro' })` |
+| `npx hst capture roku --video-device 'USB Video'` | `await capture.start({ platform: 'roku', videoDevice: 'USB Video' })` |
 | `npx hst secrets:check` | `await secrets.check({ cwd: process.cwd() })` |
 | `npx hst env check` | `await env.check({ cwd: process.cwd() })` |
 | `npx hst doctor` | `await env.check({ cwd: process.cwd() })` |
@@ -123,9 +127,9 @@ Common build-script replacements:
 
 Long-running APIs such as `dev.run`, `debugger.start`, `mcp.start`, and RASP-owned certification capture workflows keep the same operational behavior as the corresponding CLI commands: they start services, attach to debuggers, or wait for user/session activity. `mcp.start` and `dev.run` are wired for programmatic no-exit behavior through the top-level API.
 
-### Installable Browser builds
+### Installable Roku browser emulator
 
-`hosannaPwaPlugin` is a build-only Vite plugin for the generic install shell. The
+`hosannaPwaPlugin` is a build-only Vite plugin for the browser emulator shell. The
 host application supplies its identity, artwork, launch selection, offline page,
 and network-only routes; Hosanna Tools emits the manifest, registration module,
 versioned service worker, and validated icon copies.
@@ -138,7 +142,7 @@ hosannaPwaPlugin({
     id: '/',
     name: 'Example',
     shortName: 'Example',
-    startUrl: '/?app=example&expression=phone',
+    startUrl: '/?app=example&expression=tv',
     scope: '/',
     backgroundColor: '#ffffff',
     themeColor: '#123456',
@@ -295,14 +299,15 @@ See [RELEASE.md](RELEASE.md) for the full release process.
 
 Quick reference:
 ```bash
-npm run release -- patch   # 2.14.0 → 2.14.1
-npm run release -- minor   # 2.14.0 → 2.15.0
-npm run release -- major   # 2.14.0 → 3.0.0
+npm run release -- patch --dry-run
+npm run release -- minor --dry-run
+npm run release -- major --dry-run
 ```
 
-For tokenless agent releases, dispatch **Release Patch** or **Release Minor**
-in GitHub Actions. Both wrappers invoke the OIDC-trusted `release.yml`
-workflow on `main`; agents do not need npm credentials.
+The wrapper delegates to the root monorepo release command. Publication uses the
+central `monorepo-release.yml` workflow after this package's npm trusted publisher
+has been migrated. See [RELEASE.md](RELEASE.md) for the configuration and validation
+requirements.
 
 ## CLI: configure-hosanna-url
 
@@ -324,52 +329,28 @@ Hosanna Tools is a comprehensive CLI toolset for the Hosanna framework that prov
 The CLI commands are organized into logical groups using colon-separated namespacing:
 
 ### Development Commands
-- `run` - Canonical cross-platform app launcher. Bare interactive runs show one destination picker; explicit platform options include Browser, Samsung Tizen, LG webOS, Roku, Apple, and Android hosts.
-- `launch` - Restart an already-installed Roku, iOS, Apple TV, Android, or Android TV app with launch arguments. No build, install, generated config, or development server is involved. See [launching installed apps](docs/launch-installed.md).
-- `build` - Build/package without device discovery, deployment, launch, browser opening, or log streaming. Successful Tizen/webOS builds print their absolute `.wgt`/`.ipk` path.
-- `device:setup <tizen|webos>` - Guided, dry-runnable vendor setup: connect/authorize Samsung with SDB and verify an external signing profile, or register an LG ares alias and optionally run the official interactive key flow. HST never stores keys, certificates, or passphrases.
-- `capture` - Record an Apple simulator, a physical-TV capture-card input, or a macOS screen/window. The default timeout is 180 seconds; use `--timeout` to override it.
-- `target:list` - List launch targets for humans or agents, including web emulators, sims, and physical devices.
-- `dev:start` - Run dev processes: vite, generator watch, and optional debugger
-- `debugger:start` - Start the command debugger WebSocket proxy (only one debugger is needed for multiple apps; if the port is already in use, a friendly message is shown instead of crashing)
 
-Examples:
+Hosanna launches native Roku or Roku emulated in the browser. Other platform launchers have been removed. Physical Roku device sessions must be reserved through Device Deck before deployment.
+
+- `run` — Start Roku or its browser emulator. Bare interactive runs show the supported destinations.
+- `launch roku` — Restart an installed Roku channel through ECP without building or installing.
+- `build` — Prepare Roku or browser output without starting it.
+- `target:list` — List the Roku emulator and physical Roku devices.
+- `dev:start` — Start the Roku browser emulator development server and generator.
+- `debugger:start` — Start the shared command debugger.
 
 ```bash
 hst run
 hst run --last
+hst run roku dev device --device 192.0.2.50
+hst run roku dev emulator
 hst run browser dev emulator
-hst run tizen dev emulator
-hst run webos dev emulator
-hst build tizen dev device --signing-profile samsung-tv-dev
-hst build webos dev device
-hst run tizen dev device "Samsung living room" --signing-profile samsung-tv-dev
-hst run webos dev device "LG living room"
-hst run --platform roku --target emulator
-hst run --platform ios --target emulator
-hst run --platform android --target emulator
-hst run --platform apple-tv --target emulator
-hst run --platform android-tv --target emulator
-hst run --platform ios --target sim --device "iPhone 17 Pro"
-hst run --platform ios --target device --device "George iPhone" --no-logs
-hst run --platform android --target sim --device "Pixel_8" --no-logs
-hst run --platform android --target device --device "RF8M62694QT" --no-logs
-hst run --platform android-tv --target sim --device "Television_1080p" --no-logs
-hst run --platform apple-tv --target sim --device "Apple TV 4K"
-hst run --platform roku --target device --device "Living Room"
-hst run --platform roku --target device --device "Living Room" --replace
-hst target:list --platform ios --target device --json
-hst target:list --platform android --target sim --json
-hst target:list --platform android-tv --target sim --json
-hst target:list --platform apple-tv --target sim --json
-hst target:list --form-factor tv --json
-```
-
-Bare `hst run` in an interactive terminal discovers runnable web previews, vendor simulators, and online physical devices, then presents one flat destination picker. The last selection is placed first, so pressing Enter repeats it; `hst run --last` skips discovery and immediately uses that remembered destination. The selection is stored in the user-level `~/.hosanna-tools/run.json`, preserving existing defaults. Explicit commands remain deterministic, and non-interactive runs never open the picker.
-
-`browser` is the canonical public platform; legacy platform input `web` is normalized to `browser`. `emulator` is the public desktop-preview target and HST retains internal target kind `web`. For Tizen and webOS, emulator mode launches the target-specific Vite config so compile-time initializers are selected; it is not a vendor simulator. `--target sim` launches a real vendor virtual device only for supported Apple/Android platforms. `--target device` launches or deploys to physical local hardware. Device/sim runs record the target and refuse to overwrite a recorded session or safe-to-kill occupied resource in non-interactive mode unless `--replace` is passed. Tizen/webOS previews cannot reuse a Browser session because their compiled alias graphs differ. Preferred run defaults live in `.hosanna-tools/run.json`, and friendly device aliases live in `.hosanna-tools/devices.json` or `~/.hosanna-tools/devices.json`; signing keys and device passphrases remain in vendor stores.
-
-HST starts new Android virtual devices with the Android Emulator's recommended `auto` graphics mode. Set `HS_ANDROID_EMULATOR_GPU` to an emulator-supported mode such as `host` or `software` when a machine needs an explicit performance or compatibility override. HST reads this setting only when it starts the AVD; stop and restart an already-running emulator through HST after changing it. The value is passed directly to the installed emulator, so its available modes remain authoritative.
+hst build roku dev device
+hst target:list --json
+hst launch roku --app-id dev --device 192.0.2.50
+```
+
+`web` aliases `browser`. Browser launches default to the `rokufhd` device preset. Existing development sessions are reused only when the requested app and port match. Configured run defaults live in `.hosanna-tools/run.json`.
 
 ### Roku Commands (`roku:*`) - Roku Deployment & Packaging
 - `roku:run` - Deploy a Roku app to a device (supports .zip file or folder)
@@ -438,31 +419,17 @@ Supported inputs include `file/line: pkg:/components/source_0.brs(7475)`, `at ..
 ### Build Config Commands (`build-config`) - Runtime Configuration
 - `build-config:resolve` - Resolve `build-config/base.json`, env/platform overlays, secrets, and optional developer profiles into the canonical runtime `build-config.json`
 
-Production JavaScript bundles strip `console.*` calls by default. Configure this through the normal overlay chain with `build.stripLogs`: set it to `false` in `build-config/prod.json` to retain production logs, or in `build-config/prod.apple.json` / `build-config/prod.web.json` for a platform-only exception. Non-production environments keep logs unless their overlay explicitly enables stripping. Apple `prod` builds use Xcode `Release`; other environments continue to use `Debug`.
+Production JavaScript bundles strip `console.*` calls by default. Configure this through the normal overlay chain with `build.stripLogs`: set it to `false` in `build-config/prod.json` to retain production logs, or in `build-config/prod.web.json` for a platform-only exception. Non-production environments keep logs unless their overlay explicitly enables stripping.
 
-Native Apple and Android phone/TV builds also emit a descriptor for the final packaged code bytes. See [Packaged code bundle descriptors](docs/code-bundle-descriptors.md) for version precedence, deterministic artifact paths, and the integrity-versus-authenticity security boundary.
 
 Roku builds also populate `assetServer.baseUrl` when an overlay does not define it. `hst run` uses the resolved project Vite port and a reachable LAN IPv4 address. Override either the complete URL with `HS_ASSET_SERVER_BASE_URL`, or its parts with `HS_ASSET_SERVER_HOST` and `HS_ASSET_SERVER_PORT`; the equivalent `HOSANNA_ASSET_SERVER_*` names are also accepted. Explicit build-config overlays remain authoritative. The legacy `game.assetBaseUrl` setting is generated independently for backward compatibility.
 
-Tizen/webOS builds prefer exact target overlays and fall back to the matching
-Web overlay only when the exact file is absent. Physical development builds
-resolve remote-debug loopback hosts to a reachable LAN address; override with
-`HS_REMOTE_DEBUG_HOST`. Production TV builds force remote debugging off. Exact
-non-secret service origins can be supplied with `--connect-origin` or
-`HS_TV_CONNECT_ORIGINS`; unresolved package tokens and wildcard origins fail
-staging. See [Browser, Tizen, and webOS](docs/browser-tizen-webos.md).
-
-Native builds can resolve config immediately before the platform build:
+Roku builds can resolve config immediately before the platform build:
 
 ```bash
 npx hst build-config:resolve --env dev --platform roku --out assets/meta/build-config.json
 npm run roku:build
 
-HS_ENV=dev HS_PLATFORM=android npx hst build-config:resolve --out assets/meta/build-config.json
-npm run android:build-code
-
-HS_ENV=dev HS_PLATFORM=apple HS_BUILD_PROFILE=george npx hst build-config:resolve --out assets/meta/build-config.json
-npm run apple:build-code
 ```
 
 ### CI Commands (`ci:*`) - Continuous Integration
@@ -631,7 +598,7 @@ silently break an install.
 - `mcp:start` - Start the Hosanna MCP server for AI agent debugging
 - `mcp:stop` - Stop the Hosanna MCP server
 
-**Cursor and MCP:** Cursor does not magically attach to a terminal `hst mcp:start`. Add Hosanna as a Command MCP server (project **`.cursor/mcp.json`** or **Cursor Settings → MCP → Add Custom MCP**) so Cursor spawns **`hosanna-mcp`** over stdio. Start the command debugger/app explicitly with `hst run browser dev emulator`, `hst run tizen dev emulator`, `hst run webos dev emulator`, or `hst run roku dev device`.
+**Cursor and MCP:** Cursor does not magically attach to a terminal `hst mcp:start`. Add Hosanna as a Command MCP server (project **`.cursor/mcp.json`** or **Cursor Settings → MCP → Add Custom MCP**) so Cursor spawns **`hosanna-mcp`** over stdio. Start the command debugger/app explicitly with `hst run browser dev emulator` or `hst run roku dev device`.
 
 ### Deterministic UI testing
 
@@ -639,24 +606,20 @@ Applications own regular Vitest suites. Global setup comes from `@tantawowa/hosa
 
 Add `createHosannaReporter(config)` from `@tantawowa/hosanna-tools/testing/vitest/reporter` to the application's Vitest reporters. Every run then writes a self-contained JSON and HTML report under `test-results/<testRunId>/`, updates `test-results/latest.json` and `test-results/latest.html`, and includes every Vitest result plus any named visual proofs captured by the tests.
 
-Tests can record the complete owned browser, supported Apple simulator, or
-Roku device run:
+Tests can record a complete browser emulator or Roku device run:
 
 ```ts
 defineHosannaTestConfig({
   // ...
   video: true,
   // Browser: video: { size: { width: 1280, height: 720 } },
-  // Native/device: video: { timeoutSeconds: 300, videoDevice: 'USB Video' },
+  // Roku device: video: { timeoutSeconds: 300, videoDevice: 'USB Video' },
 });
 ```
 
 The finalized recording is written below
 `test-results/<testRunId>/<platform>-<target>/` and embedded in the HTML report.
-Browser targets use Playwright WebM. iOS/Apple TV simulators use `simctl` MP4.
-Physical Roku, Tizen, and webOS targets use AVFoundation or a configured macOS
-screen/window source; HST does not claim vendor-native TV recording.
-Native/device capture defaults to 180 seconds; override it with
+Browser emulation uses Playwright WebM. Roku devices use their assigned capture card or a host window showing that feed. Roku capture defaults to 180 seconds; override it with
 `timeoutSeconds`. This is a review artifact, not a replay format or executable
 test source.
 
@@ -691,7 +654,7 @@ await hs.proof.capture('programme-focused', {
 });
 ```
 
-Image readiness requires a non-empty URI, `loadStatus: "ready"`, positive rendered dimensions, and positive decoded bitmap dimensions by default. Explicit `loadWidth`/`loadHeight` assertions remain available for controls that request a fixed decode size; zero is valid when the runtime decodes at the source size. `hs.image.byId(...)`, `hs.image.within(...)`, and semantic `hs.image.inCollectionCell(...)` locators work across browser, Roku, and later native drivers.
+Image readiness requires a non-empty URI, `loadStatus: "ready"`, positive rendered dimensions, and positive decoded bitmap dimensions by default. Explicit `loadWidth`/`loadHeight` assertions remain available for controls that request a fixed decode size; zero is valid when the runtime decodes at the source size. `hs.image.byId(...)`, `hs.image.within(...)`, and semantic `hs.image.inCollectionCell(...)` locators work across Roku and its browser emulator.
 
 Screenshots and proofs wait for the command-plane hierarchy and focus to remain stable for 300ms by default, then allow a short platform render-settle window. Consecutive screenshots are also spaced automatically. Override this only for known platform behaviour through the test config's `screenshot` settings or per-capture options; failure diagnostics bypass the stable-frame wait so they can still capture broken states.
 
@@ -714,14 +677,13 @@ defineHosannaTestConfig({
 });
 ```
 
-Use `createHosannaTestTarget(config)` with Vitest's standard conditional APIs. Selectors accept one platform or a set, and distinguish browser, simulator, and physical-device targets:
+Use `createHosannaTestTarget(config)` with Vitest's standard conditional APIs. Selectors distinguish Roku browser emulation and physical Roku targets:
 
 ```ts
 const target = createHosannaTestTarget(config);
 
 test.runIf(target.matches({ platform: 'roku', target: 'device' }))('Roku only', async ({ hs }) => {});
-test.runIf(target.matches({ platform: ['ios', 'android'], target: 'sim' }))('mobile simulators', async ({ hs }) => {});
-test.runIf(target.matches({ target: 'web' }))('all browser flavours', async ({ hs }) => {});
+test.runIf(target.matches({ target: 'web' }))('Roku browser emulation', async ({ hs }) => {});
 ```
 
 Browser Channel Store emulation supports per-test `success`, `cancelled`, and `failed` outcomes when `channelStore.testMode.enabled` is present in the test overlay. Set it from a named precondition with `hs.mocks.channelStore.setPurchaseOutcome(...)`. This API refuses physical-device targets. Roku purchase tests use Roku Pay [billing testing](https://developer.roku.com/dev/docs/billing-testing), a linked [Roku test user](https://developer.roku.com/dev/docs/test-users), and real Channel Store/OS purchase screens; keep them opt-in and serial.
@@ -732,31 +694,12 @@ For Roku device suites, the launcher builds and deploys before the test launch,
 
 ```bash
 # Development workflow
-hst run browser dev emulator      # Canonical Browser host
-hst run tizen dev emulator        # Desktop Tizen composition preview
-hst run webos dev emulator        # Desktop webOS composition preview
-hst build tizen dev device --signing-profile samsung-tv-dev
-hst build webos dev device
-hst run tizen dev device "Samsung living room" --signing-profile samsung-tv-dev
-hst run webos dev device "LG living room"
-hst run --platform roku --target emulator
-hst run --platform ios --target emulator
-hst run --platform android --target emulator
-hst run --platform apple-tv --target emulator
-hst run --platform android-tv --target emulator
-hst run --platform ios --target sim --device "iPhone 17 Pro"
-hst run --platform ios --target device --device "George iPhone" --no-logs
-hst run --platform android --target sim --device "Pixel_8" --no-logs
-hst run --platform android --target device --device "RF8M62694QT" --no-logs
-hst run --platform android-tv --target sim --device "Television_1080p" --no-logs
-hst run --platform apple-tv --target sim --device "Apple TV 4K"
-hst run --platform roku --target device --device "Living Room"
-hst run --platform roku --target device --device "Living Room" --replace
-hst target:list --platform ios --target device --json
-hst target:list --platform android --target sim --json
-hst target:list --platform android-tv --target sim --json
-hst target:list --platform apple-tv --target sim --json
-hst target:list --form-factor tv --json
+hst run browser dev emulator      # Roku browser emulator, FHD by default
+hst run roku dev emulator --device rokuhd
+hst run roku dev device --device "Living Room"
+hst run roku dev device --device "Living Room" --replace
+hst target:list --platform roku --target device --json
+hst target:list --target emulator --json
 hst generate:all --watch          # Generate code with file watching
 hst dev:start                    # Lower-level dev server task used by hst run
 

package/dist/artwork/app-artwork.d.ts

@@ -1,44 +1,9 @@
 import type { HosannaPwaIcon } from '../vite-pwa.js';
-export type AppArtworkPlatform = 'browser' | 'roku' | 'ios' | 'apple-tv' | 'android' | 'android-tv';
+export type AppArtworkPlatform = 'browser' | 'roku';
 /** Build-time sources. Paths are relative to this manifest, never runtime URLs. */
 export interface AppArtworkManifest {
     schemaVersion: 1;
     icon?: string;
-    ios?: {
-        icon?: string;
-        launchScreen?: {
-            image: string;
-            backgroundColor: string;
-        };
-    };
-    android?: {
-        icon?: string;
-        adaptive?: {
-            foreground: string;
-            background: string;
-            monochrome?: string;
-        };
-        launchScreen?: {
-            backgroundColor: string;
-            icon?: string;
-        };
-    };
-    androidTv?: {
-        icon?: string;
-        banner: string;
-        launchScreen?: {
-            backgroundColor: string;
-            icon?: string;
-        };
-    };
-    appleTv?: {
-        assetCatalog: string;
-        appIconName?: string;
-        launchScreen?: {
-            image: string;
-            backgroundColor: string;
-        };
-    };
     roku?: {
         channel: {
             hd: string;
@@ -53,7 +18,6 @@ export interface AppArtworkManifest {
     web?: {
         icon?: string;
         maskableIcon?: string;
-        appleTouchIcon?: string;
         favicon?: string;
         loadingScreen?: {
             image: string;
@@ -75,26 +39,6 @@ export interface PreparedAppArtwork {
     inputHash: string;
     outputDir: string;
     receiptPath: string;
-    apple?: {
-        assetCatalogPath: string;
-        appIconName: string;
-        watchAppIconName?: string;
-        launchScreen?: {
-            storyboardPath: string;
-            storyboardName: string;
-            imageName: string;
-            backgroundColor: string;
-        };
-    };
-    android?: {
-        resourceDirectory: string;
-        iconResource: string;
-        bannerResource?: string;
-        launchScreen?: {
-            iconResource: string;
-            backgroundColor: string;
-        };
-    };
     roku?: {
         files: Array<{
             source: string;
@@ -104,7 +48,6 @@ export interface PreparedAppArtwork {
     };
     web?: {
         icons: HosannaPwaIcon[];
-        appleTouchIcon?: string;
         favicon?: {
             source: string;
             src: string;
@@ -116,7 +59,7 @@ export interface PreparedAppArtwork {
         };
     };
 }
-/** Prepare one selected target without modifying any supplied source or native project. */
+/** Prepare one selected target without modifying supplied sources. */
 export declare function prepareAppArtwork(options: PrepareAppArtworkOptions): Promise<PreparedAppArtwork>;
 /** Validate the generic local manifest shape before an app-owned downloader activates it. */
 export declare function validateAppArtworkManifest(value: unknown): AppArtworkManifest;