Put your own program on the phone

// The smallest Remora application: one WebSocket, three messages, one dial.
//
//   node dial.mjs        (Node 22 or later, with a Remora server running)

const ws = new WebSocket('ws://127.0.0.1:7310/v1/app', 'remora.v1.json');
const send = (message) => ws.send(JSON.stringify(message));

const manifest = {
  specVersion: '1.0',
  id: 'com.example.timer',
  name: 'Focus timer',
  version: '0.1.0',
  components: { left: { type: 'dial', label: 'Minutes left', max: 25 } },
  scenarios: { main: { landscape: { root: 'left' } } },
  defaultScenario: 'main',
};

let left = 25;

ws.addEventListener('open', () => {
  send({ type: 'hello', role: 'app', versions: ['1.0'] });
});

ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  console.log('server:', JSON.stringify(message));

  if (message.type === 'welcome') send({ type: 'register', manifest });

  if (message.type === 'ready') {
    // The dial is called "left", so it shows the state key "left".
    send({ type: 'state', patch: { left } });
    // Count down once a second, so there is something to watch.
    setInterval(() => {
      left = left > 0 ? left - 1 : 25;
      send({ type: 'state', patch: { left } });
    }, 1000);
  }
});

ws.addEventListener('close', (event) => {
  console.log(`The connection closed (code ${event.code}). Is the server running?`);
  process.exit(1);
});

# The smallest Remora application: one WebSocket, three messages, one dial.
#
#   pip install websockets
#   python dial.py        (with a Remora server running)

import json
import time

from websockets.sync.client import connect

manifest = {
    "specVersion": "1.0",
    "id": "com.example.timer",
    "name": "Focus timer",
    "version": "0.1.0",
    "components": {"left": {"type": "dial", "label": "Minutes left", "max": 25}},
    "scenarios": {"main": {"landscape": {"root": "left"}}},
    "defaultScenario": "main",
}

with connect("ws://127.0.0.1:7310/v1/app", subprotocols=["remora.v1.json"]) as ws:

    def send(message):
        ws.send(json.dumps(message))

    def wait_for(wanted):
        while True:
            message = json.loads(ws.recv())
            print("server:", json.dumps(message))
            if message["type"] == "error":
                raise SystemExit(message["message"])
            if message["type"] == wanted:
                return message

    send({"type": "hello", "role": "app", "versions": ["1.0"]})
    wait_for("welcome")

    send({"type": "register", "manifest": manifest})
    wait_for("ready")

    # The dial is called "left", so it shows the state key "left".
    # Count down once a second, so there is something to watch.
    left = 25
    while True:
        send({"type": "state", "patch": {"left": left}})
        left = left - 1 if left > 0 else 25
        time.sleep(1)

// The smallest Remora application, with the Go SDK: connect, then patch.
//
//	go run ./website/samples/dial        (from the repository root, with a Remora server running)
package main

import (
	"context"
	"log"
	"time"

	"github.com/amnuts/remora/sdk/go/client"
)

const manifest = `{
  "specVersion": "1.0",
  "id": "com.example.timer",
  "name": "Focus timer",
  "version": "0.1.0",
  "components": { "left": { "type": "dial", "label": "Minutes left", "max": 25 } },
  "scenarios": { "main": { "landscape": { "root": "left" } } },
  "defaultScenario": "main"
}`

func main() {
	// Connect sends hello and register, and returns once the server has said ready.
	app, err := client.Connect(context.Background(), client.Manifest([]byte(manifest)), nil)
	if err != nil {
		log.Fatalf("could not register (is the server running?): %v", err)
	}
	defer app.Close()
	log.Printf("registered with %s as instance %s", app.ServerName(), app.Instance())

	// The dial is called "left", so it shows the state key "left".
	// Count down once a second, so there is something to watch.
	for left := 25; ; left-- {
		if left < 0 {
			left = 25
		}
		if err := app.Patch(map[string]any{"left": left}); err != nil {
			log.Fatalf("the connection ended: %v", err)
		}
		time.Sleep(time.Second)
	}
}

node website/samples/dial/dial.mjs

python website/samples/dial/dial.py

go run ./website/samples/dial

// A focus timer you can start, pause and reset from your phone.
//
//   node timer.mjs        (Node 22 or later, with a Remora server running)

import { readFileSync } from 'node:fs';

const manifest = JSON.parse(readFileSync(new URL('./manifest.json', import.meta.url), 'utf8'));

// --- the timer --------------------------------------------------------------

const timer = { minutes: 25, total: 25 * 60, left: 25 * 60, running: false, round: 1 };

function tick() {
  if (!timer.running) return;
  timer.left -= 1;
  if (timer.left === 0) {
    timer.running = false;
    timer.left = timer.total;
    timer.round += 1;
  }
}

function act(action, value) {
  if (action === 'startPause') timer.running = !timer.running;
  if (action === 'reset') {
    timer.running = false;
    timer.left = timer.total;
  }
  if (action === 'setLength' && !timer.running) {
    timer.minutes = value;
    timer.total = timer.left = value * 60;
  }
}

// The state the template draws. A template cannot calculate, so anything it
// needs worked out (the clock text, the button's label) is worked out here.
function view() {
  const started = timer.left < timer.total;
  return {
    left: `${Math.floor(timer.left / 60)}:${String(timer.left % 60).padStart(2, '0')}`,
    secondsLeft: timer.left,
    secondsTotal: timer.total,
    minutes: timer.minutes,
    round: timer.round,
    running: timer.running,
    startLabel: timer.running ? 'Pause' : started ? 'Resume' : 'Start',
    canReset: started,
  };
}

// --- talking to the server --------------------------------------------------

const ws = new WebSocket('ws://127.0.0.1:7310/v1/app', 'remora.v1.json');
const send = (message) => ws.send(JSON.stringify(message));

let registered = false;
let watchers = 0;
let sent = {}; // The state the server has from us.

// Sends only the keys that changed, and nothing at all while nobody is watching.
function publish() {
  if (!registered || watchers === 0) return;
  const now = view();
  const patch = {};
  for (const key of Object.keys(now)) {
    if (now[key] !== sent[key]) patch[key] = now[key];
  }
  if (Object.keys(patch).length === 0) return;
  send({ type: 'state', patch });
  sent = now;
}

ws.addEventListener('open', () => {
  send({ type: 'hello', role: 'app', versions: ['1.0'], client: { name: 'timer.mjs', version: '1.0.0' } });
});

ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  switch (message.type) {
    case 'welcome':
      send({ type: 'register', manifest });
      break;
    case 'ready':
      registered = true;
      console.log(`Registered as instance ${message.instance}.`);
      break;
    case 'watchers':
      // When the count rises from 0, this sends everything that changed while nobody was looking.
      watchers = message.count;
      console.log(`${watchers} viewer(s) watching.`);
      publish();
      break;
    case 'action':
      console.log(`Action: ${message.action}`, message.value ?? '');
      act(message.action, message.value);
      publish();
      break;
    case 'error':
      console.error(`The server reported ${message.code}: ${message.message}`);
      break;
  }
});

ws.addEventListener('close', (event) => {
  console.log(`The connection closed (code ${event.code}). Is the server running?`);
  process.exit(1);
});

setInterval(() => {
  tick();
  publish();
}, 1000);

# A focus timer you can start, pause and reset from your phone.
#
#   pip install websockets
#   python timer.py        (with a Remora server running)

import asyncio
import json
from pathlib import Path

import websockets

manifest = json.loads(Path(__file__).with_name("manifest.json").read_text(encoding="utf-8"))

# --- the timer ---------------------------------------------------------------

timer = {"minutes": 25, "total": 25 * 60, "left": 25 * 60, "running": False, "round": 1}


def tick():
    if not timer["running"]:
        return
    timer["left"] -= 1
    if timer["left"] == 0:
        timer["running"] = False
        timer["left"] = timer["total"]
        timer["round"] += 1


def act(action, value):
    if action == "startPause":
        timer["running"] = not timer["running"]
    if action == "reset":
        timer["running"] = False
        timer["left"] = timer["total"]
    if action == "setLength" and not timer["running"]:
        timer["minutes"] = value
        timer["total"] = timer["left"] = value * 60


def view():
    """The state the template draws. A template cannot calculate, so anything
    it needs worked out (the clock text, the button's label) is worked out here."""
    started = timer["left"] < timer["total"]
    return {
        "left": f"{timer['left'] // 60}:{timer['left'] % 60:02d}",
        "secondsLeft": timer["left"],
        "secondsTotal": timer["total"],
        "minutes": timer["minutes"],
        "round": timer["round"],
        "running": timer["running"],
        "startLabel": "Pause" if timer["running"] else "Resume" if started else "Start",
        "canReset": started,
    }


# --- talking to the server ---------------------------------------------------


async def main():
    async with websockets.connect("ws://127.0.0.1:7310/v1/app", subprotocols=["remora.v1.json"]) as ws:
        link = {"registered": False, "watchers": 0, "sent": {}}  # "sent": the state the server has from us.

        async def send(message):
            await ws.send(json.dumps(message))

        async def publish():
            """Sends only the keys that changed, and nothing at all while nobody is watching."""
            if not link["registered"] or link["watchers"] == 0:
                return
            now = view()
            patch = {key: value for key, value in now.items() if link["sent"].get(key) != value}
            if patch:
                await send({"type": "state", "patch": patch})
                link["sent"] = now

        async def every_second():
            while True:
                await asyncio.sleep(1)
                tick()
                await publish()

        await send({"type": "hello", "role": "app", "versions": ["1.0"],
                    "client": {"name": "timer.py", "version": "1.0.0"}})
        ticking = asyncio.create_task(every_second())
        try:
            async for raw in ws:
                message = json.loads(raw)
                kind = message["type"]
                if kind == "welcome":
                    await send({"type": "register", "manifest": manifest})
                elif kind == "ready":
                    link["registered"] = True
                    print(f"Registered as instance {message['instance']}.")
                elif kind == "watchers":
                    # When the count rises from 0, this sends everything that changed while nobody was looking.
                    link["watchers"] = message["count"]
                    print(f"{message['count']} viewer(s) watching.")
                    await publish()
                elif kind == "action":
                    print("Action:", message["action"], message.get("value", ""))
                    act(message["action"], message.get("value"))
                    await publish()
                elif kind == "error":
                    print(f"The server reported {message['code']}: {message['message']}")
        finally:
            ticking.cancel()
    print("The connection closed.")


asyncio.run(main())

// A focus timer you can start, pause and reset from your phone, with the Go SDK.
//
//	go run ./website/samples/timer        (from the repository root, with a Remora server running)
package main

import (
	"context"
	_ "embed"
	"fmt"
	"log"
	"time"

	"github.com/amnuts/remora/sdk/go/client"
)

//go:embed manifest.json
var manifest []byte

// --- the timer ---------------------------------------------------------------

type timer struct {
	minutes, total, left, round int
	running                     bool
}

func (t *timer) tick() {
	if !t.running {
		return
	}
	t.left--
	if t.left == 0 {
		t.running = false
		t.left = t.total
		t.round++
	}
}

func (t *timer) act(a client.Action) {
	switch a.Name {
	case "startPause":
		t.running = !t.running
	case "reset":
		t.running = false
		t.left = t.total
	case "setLength":
		if minutes, ok := a.Number(); ok && !t.running {
			t.minutes = int(minutes)
			t.total = t.minutes * 60
			t.left = t.total
		}
	}
}

// view is the state the template draws. A template cannot calculate, so
// anything it needs worked out (the clock text, the button's label) is worked
// out here.
func (t *timer) view() map[string]any {
	started := t.left < t.total
	label := "Start"
	if t.running {
		label = "Pause"
	} else if started {
		label = "Resume"
	}
	return map[string]any{
		"left":         fmt.Sprintf("%d:%02d", t.left/60, t.left%60),
		"secondsLeft":  t.left,
		"secondsTotal": t.total,
		"minutes":      t.minutes,
		"round":        t.round,
		"running":      t.running,
		"startLabel":   label,
		"canReset":     started,
	}
}

// --- talking to the server ---------------------------------------------------

func main() {
	watching := make(chan int, 8)
	app, err := client.Connect(context.Background(), client.Manifest(manifest), &client.Options{
		Name: "timer (Go)", Version: "1.0.0",
		OnWatchers: func(count int) { watching <- count },
	})
	if err != nil {
		log.Fatalf("could not register (is the server running?): %v", err)
	}
	defer app.Close()
	log.Printf("registered as instance %s", app.Instance())

	t := &timer{minutes: 25, total: 25 * 60, left: 25 * 60, round: 1}
	watchers := 0
	// The SDK sends what it is given; the server passes on only what changed.
	// So this publishes the whole view, and nothing at all while nobody is watching.
	publish := func() {
		if watchers == 0 {
			return
		}
		if err := app.Patch(t.view()); err != nil {
			log.Printf("patch failed: %v", err)
		}
	}

	second := time.NewTicker(time.Second)
	defer second.Stop()
	for {
		select {
		case <-app.Done():
			log.Fatalf("the connection ended: %v", app.Err())
		case watchers = <-watching:
			log.Printf("%d viewer(s) watching", watchers)
		case a := <-app.Actions():
			log.Printf("action: %s %v", a.Name, a.Value)
			t.act(a)
		case <-second.C:
			t.tick()
		}
		publish()
	}
}

node website/samples/timer/timer.mjs

python website/samples/timer/timer.py

go run ./website/samples/timer

// Registers a template that has asset files, as a .remora archive, and then
// supplies an image made while the program runs.
//
//   node package.mjs        (Node 22.2 or later, with a Remora server running)

import { createHash } from 'node:crypto';
import { fileURLToPath } from 'node:url';
import { pack } from './pack.mjs';

const archive = pack(fileURLToPath(new URL('./template', import.meta.url)));
const hash = createHash('sha256').update(archive).digest('hex');
console.log(`The archive is ${archive.length} bytes; its hash is ${hash}.`);

const ws = new WebSocket('ws://127.0.0.1:7310/v1/app', 'remora.v1.json');
const send = (message) => ws.send(JSON.stringify(message));

// A row of dots, one for each round finished. Any image the program can
// produce or fetch works the same way: a cover, a chart, a photo.
function tally(done) {
  const dots = Array.from({ length: done }, (_, i) => `<circle cx="${20 + i * 40}" cy="20" r="13" fill="#FFB84A"/>`);
  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${done * 40} 40">${dots.join('')}</svg>`;
}

let done = 0;

function finishRound() {
  done = done < 8 ? done + 1 : 1;
  const path = `tally/${done}.svg`;
  // A runtime asset is two frames: a JSON message saying what is coming, then the bytes.
  send({ type: 'asset', path, contentType: 'image/svg+xml' });
  ws.send(Buffer.from(tally(done)));
  // State then refers to it as "runtime:" plus the path.
  send({ type: 'state', patch: { done, tally: `runtime:${path}` } });
}

ws.addEventListener('open', () => {
  send({ type: 'hello', role: 'app', versions: ['1.0'] });
});

ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  switch (message.type) {
    case 'welcome':
      if (archive.length > message.limits.packageBytes) {
        console.error(`The archive is too large for this server (${message.limits.packageBytes} bytes at most).`);
        process.exit(1);
      }
      // Offer the package by its hash. The server asks for the bytes only if it does not have them.
      send({ type: 'register', package: hash });
      break;
    case 'packageRequired':
      console.log('The server does not have this package yet: uploading it.');
      ws.send(archive);
      break;
    case 'ready':
      console.log(`Ready. Instance ${message.instance} is showing package ${message.package}.`);
      finishRound();
      setInterval(finishRound, 5000);
      break;
    case 'error':
      console.error(`The server reported ${message.code}: ${message.message}`);
      break;
  }
});

ws.addEventListener('close', (event) => {
  console.log(`The connection closed (code ${event.code}). Is the server running?`);
  process.exit(1);
});

# Registers a template that has asset files, as a .remora archive, and then
# supplies an image made while the program runs.
#
#   pip install websockets
#   python package.py        (with a Remora server running)

import hashlib
import io
import json
import time
import zipfile
from pathlib import Path

from websockets.sync.client import connect


def pack(folder):
    """Builds a .remora archive: an ordinary ZIP with manifest.json at its root.
    Files go in sorted, with no timestamps, so the same folder always gives the
    same bytes, and therefore the same package hash."""
    buffer = io.BytesIO()
    with zipfile.ZipFile(buffer, "w") as archive:
        for path in sorted(p for p in folder.rglob("*") if p.is_file()):
            entry = zipfile.ZipInfo(path.relative_to(folder).as_posix())  # dated 1 January 1980
            entry.compress_type = zipfile.ZIP_DEFLATED
            archive.writestr(entry, path.read_bytes())
    return buffer.getvalue()


def tally(done):
    """A row of dots, one for each round finished. Any image the program can
    produce or fetch works the same way: a cover, a chart, a photo."""
    dots = "".join(f'<circle cx="{20 + i * 40}" cy="20" r="13" fill="#FFB84A"/>' for i in range(done))
    return f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {done * 40} 40">{dots}</svg>'


archive = pack(Path(__file__).with_name("template"))
package_hash = hashlib.sha256(archive).hexdigest()
print(f"The archive is {len(archive)} bytes; its hash is {package_hash}.")

with connect("ws://127.0.0.1:7310/v1/app", subprotocols=["remora.v1.json"]) as ws:

    def send(message):
        ws.send(json.dumps(message))

    def wait_for(*wanted):
        while True:
            message = json.loads(ws.recv())
            if message["type"] == "error":
                raise SystemExit(f"The server reported {message['code']}: {message['message']}")
            if message["type"] in wanted:
                return message

    send({"type": "hello", "role": "app", "versions": ["1.0"]})
    welcome = wait_for("welcome")
    if len(archive) > welcome["limits"]["packageBytes"]:
        raise SystemExit(f"The archive is too large for this server ({welcome['limits']['packageBytes']} bytes at most).")

    # Offer the package by its hash. The server asks for the bytes only if it does not have them.
    send({"type": "register", "package": package_hash})
    reply = wait_for("ready", "packageRequired")
    if reply["type"] == "packageRequired":
        print("The server does not have this package yet: uploading it.")
        ws.send(archive)
        reply = wait_for("ready")
    print(f"Ready. Instance {reply['instance']} is showing package {reply['package']}.")

    done = 0
    while True:
        done = done + 1 if done < 8 else 1
        path = f"tally/{done}.svg"
        # A runtime asset is two frames: a JSON message saying what is coming, then the bytes.
        send({"type": "asset", "path": path, "contentType": "image/svg+xml"})
        ws.send(tally(done).encode("utf-8"))
        # State then refers to it as "runtime:" plus the path.
        send({"type": "state", "patch": {"done": done, "tally": f"runtime:{path}"}})
        time.sleep(5)

// Registers a template that has asset files, as a .remora archive, and then
// supplies an image made while the program runs. With the Go SDK.
//
//	go run ./website/samples/package        (from the repository root, with a Remora server running)
package main

import (
	"context"
	"embed"
	"fmt"
	"io/fs"
	"log"
	"strings"
	"time"

	"github.com/amnuts/remora/sdk/go/client"
)

// The template folder travels inside the program.
//
//go:embed all:template
var files embed.FS

// tally is a row of dots, one for each round finished. Any image the program
// can produce or fetch works the same way: a cover, a chart, a photo.
func tally(done int) []byte {
	var dots strings.Builder
	for i := range done {
		fmt.Fprintf(&dots, `<circle cx="%d" cy="20" r="13" fill="#FFB84A"/>`, 20+i*40)
	}
	return fmt.Appendf(nil, `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 %d 40">%s</svg>`, done*40, dots.String())
}

func main() {
	template, err := fs.Sub(files, "template")
	if err != nil {
		log.Fatal(err)
	}
	// PackFS builds the .remora archive: the same folder always gives the same bytes.
	archive, err := client.PackFS(template)
	if err != nil {
		log.Fatal(err)
	}

	// Archive offers the package by its hash; the SDK uploads the bytes only if the server asks.
	app, err := client.Connect(context.Background(), client.Archive(archive), &client.Options{
		OnError: func(e *client.Error) { log.Printf("the server reported %s: %s", e.Code, e.Message) },
	})
	if err != nil {
		log.Fatalf("could not register (is the server running?): %v", err)
	}
	defer app.Close()
	log.Printf("ready: instance %s is showing package %s", app.Instance(), app.Package())

	for done := 1; ; done++ {
		if done > 8 {
			done = 1
		}
		path := fmt.Sprintf("tally/%d.svg", done)
		if err := app.UploadAsset(path, "image/svg+xml", tally(done)); err != nil {
			log.Fatalf("the connection ended: %v", err)
		}
		// State refers to a runtime asset as "runtime:" plus its path.
		if err := app.Patch(map[string]any{"done": done, "tally": "runtime:" + path}); err != nil {
			log.Fatalf("the connection ended: %v", err)
		}
		time.Sleep(5 * time.Second)
	}
}

node website/samples/package/package.mjs

python website/samples/package/package.py

go run ./website/samples/package