oasis7 docs

Viewer Manual

oasis7 Viewer User Manual

This repository now keeps viewer as the formal Viewer web surface, with software_safe only as a compatibility alias.

Local Real LLM Game Test

The repository Viewer manual provides daily preview and Viewer/debug guidance; a complete first-run procedure for a clean checkout has not been verified. This preset requires an existing build and working provider configuration, reuses the existing build by default, and is not a zero-configuration startup command. Run ./scripts/run-local-letai-game-test.sh --help-all for supported configuration-file and proxy options. Real model calls may incur provider charges.

./scripts/run-local-letai-game-test.sh --local-world-playtest

Use this preset for local real LetAI provider-backed gameplay. It handles token config, provider bridge, launcher/runtime/viewer/local-standalone-chain startup, and the daily playtest ports 48420/48421/48422; it does not connect to formal/public testnet. The emitted GAME_URL is the manual play and agent-browser evidence entry.

Do not treat bare run-viewer-web.sh as the local real provider-backed gameplay startup path; it belongs to the Viewer/debug loop below.

Lower-Level Viewer Debug Quick Start

1) Start the live server

env -u RUSTC_WRAPPER cargo run -p oasis7 --bin oasis7_viewer_live -- llm_bootstrap --allow-debug-scenario --llm --bind 127.0.0.1:5023 --web-bind 127.0.0.1:5011

This route is Viewer/debug only. If you switch to --no-llm, it remains observer/debug only.

2) Start the web viewer

env -u NO_COLOR ./scripts/run-viewer-web.sh --address 127.0.0.1 --port 4173

Open: http://127.0.0.1:4173/?ws=ws://127.0.0.1:5011

The repo now ships only the formal viewer web surface; software_safe remains a compatibility alias and no other Viewer entry is maintained.

Web Loop

Use the repo-owned regressions when possible:

The default capture uses the release/UI service above: test_api=1 does not install __AW_TEST__ in release builds. For semantic API capture, prepare the Viewer Node/Rust/WASM build dependencies, then build and serve the isolated test output in a separate terminal:

npm --prefix crates/oasis7_viewer run build:viewer:visual-test && \
python3 -m http.server 4174 --bind 127.0.0.1 --directory crates/oasis7_viewer/.viewer-test-dist

The script below defaults to release. Set export VIEWER_CAPTURE_MODE=visual-test in the capture terminal only after that test service is ready. Do not substitute run-viewer-web.sh for the test-output server or publish .viewer-test-dist as release. test_api=1 is an additional test-build opt-in; it cannot change a release build, grant player permissions, or provide a formal access credential. Record the selected profile, source/build identity, and URL.

Verify agent-browser 0.37.1 with --version and run doctor --offline --quick --json first. Create a worktree-scoped named session for each run, record diagnostics with session info/list --json when needed, and close only the session owned by that run.

set -euo pipefail
VIEWER_CAPTURE_MODE="${VIEWER_CAPTURE_MODE:-release}"
case "$VIEWER_CAPTURE_MODE" in
  release) VIEWER_CAPTURE_PORT=4173 ;;
  visual-test) VIEWER_CAPTURE_PORT=4174 ;;
  *) echo "unknown VIEWER_CAPTURE_MODE: $VIEWER_CAPTURE_MODE" >&2; exit 2 ;;
esac
command -v agent-browser >/dev/null || { echo "missing agent-browser" >&2; exit 1; }
agent-browser --version
agent-browser doctor --offline --quick --json
AB_SESSION="$(agent-browser session id --scope worktree --prefix viewer)"
export AB_SESSION
mkdir -p output/playwright/viewer
VIEWER_EVIDENCE_DIR="$(mktemp -d "output/playwright/viewer/${AB_SESSION}.XXXXXX")"
cleanup() {
  local main_status=$?
  local close_status=0
  trap - EXIT INT TERM
  if agent-browser --session "$AB_SESSION" close >"$VIEWER_EVIDENCE_DIR/close.log" 2>&1; then
    close_status=0
  else
    close_status=$?
  fi
  if (( close_status != 0 )); then
    printf 'cleanup blocker: close_status=%s; see %s/close.log\n' "$close_status" "$VIEWER_EVIDENCE_DIR" >&2
  fi
  if ! printf 'main_status=%s\nclose_status=%s\n' "$main_status" "$close_status" >"$VIEWER_EVIDENCE_DIR/cleanup.status"; then
    printf 'could not write cleanup status\n' >&2
  fi
  if (( main_status != 0 )); then
    exit "$main_status"
  fi
  exit "$close_status"
}
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
agent-browser --session "$AB_SESSION" --headed open "http://127.0.0.1:${VIEWER_CAPTURE_PORT}/viewer.html?ws=ws://127.0.0.1:5011&render_mode=viewer&test_api=1"
agent-browser --session "$AB_SESSION" wait --load domcontentloaded
if [[ "$VIEWER_CAPTURE_MODE" == "visual-test" ]]; then
  agent-browser --session "$AB_SESSION" wait --fn "typeof window.__AW_TEST__ === 'object'"
else
  agent-browser --session "$AB_SESSION" wait --fn "typeof window.__AW_TEST__ === 'undefined'"
fi
agent-browser --session "$AB_SESSION" session info --json | tee "$VIEWER_EVIDENCE_DIR/session-info.json"
agent-browser --session "$AB_SESSION" snapshot -i
if [[ "$VIEWER_CAPTURE_MODE" == "visual-test" ]]; then
  agent-browser --session "$AB_SESSION" eval "JSON.stringify(window.__AW_TEST__.getState())" | tee "$VIEWER_EVIDENCE_DIR/state.json"
fi
agent-browser --session "$AB_SESSION" console | tee "$VIEWER_EVIDENCE_DIR/console.log"
agent-browser --session "$AB_SESSION" screenshot "$VIEWER_EVIDENCE_DIR/viewer-web.png"

Preserve a failed sampling exit code; when sampling succeeds but close fails, return the close failure. The current artifact directory retains close.log and cleanup.status for the cleanup blocker. A nonzero close result does not prove the process is still alive; close only this run’s session.

Minimum capture criteria: the release/UI page loads, __AW_TEST__ is absent, and screenshot/console artifacts preserve the visible connection state or an explicit blocker. Visual-test additionally requires the explicit test build and opt-in, an available API, getState().renderMode=viewer (or the compatibility alias software_safe), and a state artifact. Page loading or API availability does not prove renderer readiness, real input behavior, or formal gameplay.

Current Scope

Troubleshooting