# Carnivore Browser Host

This page describes the thin browser wrapper around Carnivore.

Canonical host/session contract:

- [HOST-SESSION-API.md](/H:/source/repos/BASIC/HOST-SESSION-API.md)

The rule is:

- the web page is only a host
- Carnivore remains the system
- public behavior stays in Carnivore terms where possible

## What The Browser Host Does

The browser host currently provides:

- a `Scrn` canvas
- screen cursor state including `Scrn.CRSW%`
- real-time keyboard and mouse events
- `Break`
- warm reset
- upload/download handoff for `Dat@`
- durable browser-local `D8` disk image storage
- broad host-target handoff for `BOOT`
- host text channels:
  - `Host.In@`
  - `Host.Out@`
  - `Host.Report@`

It should not decide Carnivore policy unless the browser platform forces it.

## Devices And Channels

Current browser-side Carnivore surfaces are:

- `Dat@`
  - upload/download bridge
- `Dos`
  - RAM/K9-backed storage in the browser host
- `Host.In@`
  - host-fed text input
- `Host.Out@`
  - host-visible text output
- `Host.Report@`
  - host-visible report/diagnostic output

## Datasette Contract

Browser upload/download currently follows `Dat@` / device 1 rules:

- blank-name `LOAD` / `OPEN` on `Dat@`
  - accepts the next uploaded file
- named `LOAD` / `OPEN` on `Dat@`
  - accepts only an exactly matching uploaded file
- non-matching uploaded file
  - remains pending
  - open returns file-not-found
- `SAVE` or output `OPEN` on `Dat@`
  - offers the written bytes back to the browser as a download

The browser host does not force `.PRG` naming.

## Host Text Control

For control and embedding, use:

- `Host.In@`
- `Host.Out@`
- `Host.Report@`

These let a host page or harness:

- feed BASIC commands without fake keyboard typing
- collect normal output
- collect diagnostics separately

This is the browser equivalent of CLI pipe-style control.

## Screen Embedding

The browser page should primarily provide:

- one canvas for `Scrn`
- minimal controls
- optional upload/download buttons

Geometry should stay in Carnivore terms:

- `SCREEN POS`
- `RWINDOW()`
- `Scrn.CRSW%`

The host should react to Carnivore's requested geometry, not invent a second model.

Mouse ownership follows the Carnivore device state, not browser guesses:

- with no active Carnivore mouse driver, right-click stays an ordinary browser gesture
- after `MOUSE ON`, the browser host suppresses the context menu and delivers the right button to Carnivore
- this lets BASIC code decide whether to show or hide the mouse sprite while still keeping button ownership

Browser `BOOT` should also stay in Carnivore terms. The page host accepts the target requested by `BOOT` and attempts normal browser host opening:

- external URLs
- `mailto:` and other browser-owned schemes
- relative site paths when the target is relative

The browser host receives the raw target string unchanged. Use explicit forms such as:

- `BOOT "https://headsoft.org"`
- `BOOT "mailto:someone@example.com"`
- `BOOT "/docs/"`

Browser policy may still block popup-style opening. When that happens, the browser host falls back to same-tab navigation rather than doing nothing.

## Tool Surface

The current browser tool surface is built on:

- the browser session interface in [HOST-SESSION-API.md](/H:/source/repos/BASIC/HOST-SESSION-API.md)
- the local headless harness in [`tools/browser_headless_probe.js`](/H:/source/repos/BASIC/tools/browser_headless_probe.js)

That harness is intended to exercise the same browser-facing session surface that an external controller would use.

Preferred control order:

1. use `Host.In@`, `Host.Out@`, and `Host.Report@` for command-style control
2. use key and mouse injection when visible UI semantics matter
3. use screen readback instead of image guessing whenever possible

## Startup Content

For browser/desktop parity, shared startup content should live in Carnivore-owned storage and be staged the same way on every host.

Target direction:

- one shared `autoboot.c65`
- one shared standard library image under `Lib`
- browser `D8` as the user's persistent browser-local disk
- browser `D9` as volatile RAM/K9
- host-specific boot should only decide how that image gets seeded

That keeps:

- browser
- desktop
- future hosts

aligned on the same Carnivore-visible layout.

## Current Status

Current browser host work is still in active development.

Known focus areas:

- keyboard/direct-mode parity
- startup time
- visible/full feature parity with desktop