xrsh-buildroot/buildroot-v86/board/v86/rootfs_overlay/root/manual.md

XRSH Manual

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ____ _____________ . .. .. . . . . . . . . . . \ / /_ / // | . . . . . . . . . . _ \ / | /_ / ~ \ . . . . . . . _ _ / \ | | / \ Y / _ _ _ _ _ _ _ . . //\ \ || /_ /___|_ /. . . . . . . . . . . . . ._/. . . . / . . . ./ . . _ / . . . . . . . . ▬▬▬▬ https://xrsh.isvery.ninja ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬

Open, local-first, polyglot, unix hackable & selfcontained XR apps. Using worlds first WebXR linux distro.

credits: NLnet | @nlnet@nlnet.nl https://nlnet.nl/project all FOSS devs | copy.sh (v86) aframe.io (AFRAME) Leon van Kammen | @lvk@mastodon.online Fabien Benetou | @utopiah@mastodon.pirateparty.be

Getting started

Please hook up your (bluetooth) keyboard to use xrsh.

tip use ctrl+a+0/1/2/3/.. to switch (GNU) screen terminals (and ctrl+a+c to create new ones)

usecase	command
require	adds javascript or CSS url to DOM
js run	js 'alert("hello")'
js console.log:	console document.baseURI
js inspect:	js "return document.baseURI"

Polyglot environment

Currently the following languages are supported:

• shellscript (busybox sh)
• awk (busybox awk v1.33.0)
• python (micropython)
• javascript (via your browser)
• lua (5.3.6)

TIP: type ls -la ~/hook.d/alert/* for examples

Editors

• vi (busybox vi)
• nano (busybox nano)
• mg (microemacs)

Boot sequence

The following files are loaded during boot (via /etc/profile)

file	info
/etc/profile.xrsh	sets up xrsh environment
/etc/profile.sh	global shellscript functions
/etc/profile.js	global javascript functions
/mnt/profile.browser	environment vars set by browser (echo $HOSTNAME)
/root/.profile	user shellscript functions/settings
/root/.profile.js	user javascript functions
/root/.screenrc	GNU screen initialisations
https://.../#ls	URI fragment is executed as command in own screen

TIP: to keep things portable with future versions of XRSH: modify files in /root/*

Calling terminal from javascript

const term = document.querySelector('[isoterminal]').components.isoterminal.term
term.exec("ls -la")

// interact directly with files 
await term.worker.create_file("hello.txt", term.convert.toUint8Array("hello") )
await term.worker.update_file("hello.txt", term.convert.toUint8Array("hi") )
await term.worker.append_file("hello.txt", term.convert.toUint8Array("world") )
const f = await term.worker.read_file("hello.txt")

Calling javascript from terminal

Various options:

1. Just add the #!/bin/js shebang to the top of a javascript file (+ chmod +x)
2. Run js "alert('hello')" in the shell
3. Run jsh alert hello in the shell
4. Run jsh to start an interactive shell

Hooks

Hooks are filebased events. Why filebased? Well first, because unixy is sexy. Second: it allows reacting to events in a hackable way via polyglot scripts.

TLDR: events are automatically triggering scripts found in /root/hook.d/{eventname}/*

OS related hooks

hook location	when is this hook called?
hook.d/wakeup/*	restoring xrsh session from cache
hook.d/save/*	saving xrsh session to cache
hook.d/alert/*	when 'alert'-function is used in shell
hook.d/prompt/*	when 'prompt'-function is used in shell
hook.d/confirm/*	when 'confirm'-function is used in shell

Clipboard related hooks

| hook.d/clipboard/* | user copy-pastes clipboard or (drops) file into scene | | hook.d/mimetype/* | clipboard activity (hook.d/clipboard/forwarder) | | hook.d/filetype/* | clipboard activity (hook.d/clipboard/forwarder) |

XR related hooks

hook location	when is this hook called?
hook.d/exit-vr/*	user exits immersive WebXR [VR] mode
hook.d/enter-vr/*	user enters immersive WebXR [VR] mode
hook.d/exit-ar/*	user exits immersive WebXR [AR] mode
hook.d/enter-ar/*	user enters immersive WebXR [AR] mode

How to trigger them?

Well the isoterminal-AFRAME component triggers them automatically for you. But you can do it manually too:

1. from shellscript: hook myevent (will trigger executable files in /root/hook.d/myevent)
2. from javascript: isoterminal.exec("hook myevent") (idem)
3. via jsh: jsh alert hello (will trigger executable files in /root/hook.d/alert)

These are various ways to enable hybrid eventing between browser and terminal (languages).

Multiple terminals [GNU screen]

From the cmdline

xrsh # screen –DR        # list of detached screen
xrsh # screen –r PID     # attach detached screen ses­sion
xrsh # screen –dmS Myses # start a detached screen ses­sion
xrsh # screen –r MySes   #attach screen ses­sion with name MySession

Basics

ctrl a c -> create new window
ctrl a A -> set win­dow name
ctrl a w -> show all win­dow
ctrl a 1|2|3|… -> switch to win­dow n
ctrl a " -> choose win­dow
ctrl a ctrl a -> switch between win­dow
ctrl a d -> detach win­dow
ctrl a ? -> help
ctrl a [ -> start copy, move cur­sor to the copy loca­tion, press ENTER, select the chars, press ENTER to copy the selected char­ac­ters to the buffer
ctrl a ] -> paste from buffer

Advanced

ctrl a S -> cre­ate split screen
ctrl a TAB -> switch between split screens
ctrl a Q -> Kill all regions but the cur­rent one.
ctrl a X -> remove active win­dow from split screen
ctrl a O -> logout active win­dow (dis­able out­put)
ctrl a I -> login active win­dow (enable output)

webrequests to the filesystem

Javascript webrequests can read from the filesystem via the 'file://host/path' protocol:

fetch("file://xrsh/mnt/profile.browser")

current [security] limitations:

• only /mnt directory is exposed
• file needs to be world-readable (chmod +r /mnt/<file>)