SOFTrobots OS · App-API

# Reader: shows PDF documents.
name = reader
id = de.softrobots.reader
title = Reader
category = productivity
icon = icon.svg
capabilities = system.log, ui.surface
kind = system
opens = pdf
start = demand
memory = 768
# Programmordner daneben: uses-heap, uses-image, uses-svg, uses-ui

name = chooser
id = de.softrobots.chooser
title = File Dialog
category = system
capabilities = system.log, ui.surface, files.system, files.dialog
kind = system
start = demand
helper = display
# Never in the dock, not even while a dialog is open (2026-11-10).
dock = no

nonisolated(unsafe) var ui = UI()
nonisolated(unsafe) var clicks = 0

enum Buttons { static let count = 1 }

@c(app_main)
func appMain() {
    guard var surface = Surface.create() else { System.log("greeter: no window"); return }
    surface.requestSize(width: 360, height: 220)
    surface.addMenu(0, "Counter")
    surface.addItem(0, "Count", id: Buttons.count, key: 0x6E) // Cmd+N
    surface.publishMenus()
    var dirty = true
    while true {
        while let event = surface.nextEvent() {
            switch event {
            case .configure: dirty = true
            case .close: System.exit(0)
            case .menu(let id): if id == Buttons.count { clicks += 1; dirty = true }
            case .pointer(let x, let y, let buttons):
                let under = ui.button(at: x, y)
                surface.setPointer(under != 0 ? .hand : .arrow)
                if buttons & 2 != 0 {
                    if ui.pressed == 0 { ui.pressed = under; dirty = true }
                } else if ui.pressed != 0 {
                    if under == ui.pressed && under == Buttons.count { clicks += 1 }
                    ui.pressed = 0
                    dirty = true
                }
            default: break
            }
        }
        if dirty && surface.canvas.width > 0 {
            draw(surface.canvas)
            surface.present(Rect(x: 0, y: 0, width: surface.canvas.width, height: surface.canvas.height))
            dirty = false
        }
        surface.wait(timeout: 500_000_000)
    }
}

private func draw(_ canvas: Canvas) {
    var text = TextLine("Clicked ")
    text.append(decimal: UInt64(clicks))
    text.append(clicks == 1 ? " time" : " times")
    let view = Padded(20) {
        VStack(spacing: 14) {
            Text("greeter", face: .heading)
            Text(text, face: .body, color: UITheme.muted)
            Button("Count", id: Buttons.count)
            Spacer()
        }
    }
    canvas.render(view, in: Rect(x: 0, y: 0, width: canvas.width, height: canvas.height), &ui)
}

nonisolated(unsafe) var keyboard = Keyboard()
nonisolated(unsafe) var searchInput = InputField(maximumLength: 120)

// beim Start
searchInput.placeholder = TextLine("Search")

// bei case .key(let code, let down):
let press = keyboard.handle(code: code, down: down)
if searchFocused {
    switch searchInput.key(press, keyboard) {
    case .edited: search(); return true
    case .submit: return step(keyboard.shift ? -1 : 1, canvas)
    case .cancel: searchFocused = false; return true
    case .moved: return true
    case .none: break
    }
}

// beim Zeichnen
searchInput.draw(canvas, field, focused: searchFocused)

if dirty && surface.canvas.width > 0 {
    surface.beginDrawing()      // der Dienst kopiert jetzt nicht mitten ins Bild
    draw(surface.canvas)
    surface.presentChanges()    // nur die geänderten Kacheln
    dirty = false
}
surface.wait(timeout: 500_000_000)

surface.addFileMenu(open: true)
surface.addEditMenu(1)
surface.addMenu(2, "View")
surface.addItem(2, "Zoom In", id: Item.zoomIn, key: 0x2B, icon: .zoomIn)   // +
surface.addItem(2, "Zoom Out", id: Item.zoomOut, key: 0x2D, icon: .zoomOut) // -
surface.publishMenus()

while true {
    while let event = surface.nextEvent() {
        switch event {
        case .menu(let id):
            if id == FileMenu.open { _ = Dialog.open(types: "pdf") }
            else if menu(id, surface.canvas) { dirty = true }
        default: break
        }
    }
    if case .chosen(let grant)? = Dialog.answer() {
        load(grant.name, grant: grant)          // File.open(grant, mode: .read)
        dirty = true
    }
    // ... zeichnen, wait
}

surface.addFileMenu(export: true)

// Menüpunkt Export…:
if !Dialog.save(name: suggested, formats: "CSV=csv\nJSON=json", action: "Export") {
    status = TextLine("A file dialog is open already")
}

// in der Schleife:
if case .chosen(let grant)? = Dialog.answer() {
    exportRows(json: grant.format == 1, to: grant)
}

func exportRows(json: Bool, to grant: FileGrant) {
    guard case .success(let file) = File.open(grant, mode: .replace) else {
        status = TextLine("The export file cannot be written")
        return
    }
    // ... file.write(...), file.close()
}

// Lange Antworten zeigen ihren Fortschritt (das System zeichnet ihn).
if task == nil {
    task = surface?.progress(TextLine("Download Big_Buck_Bunny.webm"),
                             total: UInt64(response.expectedLength ?? 0), unit: .bytes, cancellable: true)
}
if let running = task {
    surface?.progress(running, done: UInt64(response.body.count))
    if surface?.isCancelled(running) == true {
        cancelled = true
        break
    }
}

// am Ende (defer):
if let running = task {
    surface?.progress(running, finished: cancelled ? .cancelled : result.problem == nil ? .done : .failed)
    task = nil
}

// manifest: capabilities = system.log, ui.surface, files.own   (+ uses-heap)
guard case .success(let file) = File.open("notes.txt", mode: .read) else { return }
var bytes: [UInt8] = []
var chunk = InlineArray<1024, UInt8>(repeating: 0)
while true {
    var span = chunk.mutableSpan
    guard case .success(let count) = file.read(into: &span), count > 0 else { break }
    for index in 0..<count { bytes.append(chunk[index]) }
}
file.close()

guard case .success(let out) = File.open("notes.txt", mode: .replace) else { return }
bytes.withUnsafeBufferPointer { buffer in _ = out.write(Span(_unsafeElements: buffer)) }
out.close()

var index = 0
while case .success(let entry?) = folder.withUnsafeBufferPointer({ Files.entry(in: Span(_unsafeElements: $0), at: index) }) {
    // entry.name[0..<entry.nameLength], entry.isDirectory, entry.size, entry.modified
    index += 1
}

// manifest: opens = pdf   – kein files-Recht nötig
guard let document = Apps.document(), document.generation != generation else { return false }
generation = document.generation
switch File.openDocument(mode: .read) {
case .failure(let error): message = TextLine(error.text)
case .success(let file):  // ... lesen, file.close()
}

if var settings = Settings.load() {
    let starts = (settings.number("starts") ?? 0) + 1
    settings.set("starts", number: starts)
    settings.set("greeting", TextLine("hello robot"))
    _ = settings.save()
}

enum JointStatus { ok @0, warning @1, fault @2 }

shape Joint stored as joints {
    name: Text(32) unique
    angle: Int32 in -180000 ... 180000
    current: Float32?
    status: JointStatus = .ok
    index status, angle
    index angle
}

shape Move stored as moves {
    joint: Joint
    at: Time
    target: Int32
}

nonisolated(unsafe) var set = WriteSet<65536>()
nonisolated(unsafe) var query = Query<512>(Joints.table)
nonisolated(unsafe) var page = QueryPage<16384, 1024>()

guard case .success(let robot) = openDatabase("robot.db") else { return fail("cannot open robot.db") }

Joints.insert(&set, name: name.span.extracting(0..<length), angle: 45_000)
Joints.setStatus(&set, .warning)
guard case .success(1) = robot.write(&set) else { return fail("insert failed") }

// Regeln prüft der Kern:
guard case .failure(.rule(.duplicate, operation: 0, field: 1)) = robot.write(&set) else { ... }

// Die zehn größten Winkel über 90°, über den Index rückwärts
query = Query(Joints.table)
query.where(Joints.angle > 90_000)
query.sorted(by: Joints.angle.index, descending: true)
query.limit(10)
page.reset()
while robot.next(&query, into: &page) || page.rowCount > 0 {
    for row in 0..<page.rowCount { let joint = Joints.row(&page, row); _ = joint.angle }
    if page.rowCount == 0 { break }
}

// Join: Bewegungen, deren Gelenk den Status warning hat
query = Query(Moves.table)
query.where(Joints.status.via(Moves.joint) == 1)
query.count()

// manifest: capabilities = system.log, network.outgoing   (+ uses-tls)
guard let secure = SecureConnection.open("example.com") else {
    var line = TextLine("https: ")
    line.append(SecureConnection.lastError)
    System.log(line)
    return
}
let request: StaticString = "GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n"
let sent = request.withUTF8Buffer { bytes in secure.send(Span(_unsafeElements: bytes)) }
guard sent else { System.log("https: sending failed"); return }
var buffer = InlineArray<1024, UInt8>(repeating: 0)
while let count = secure.receive(into: &buffer) {
    if count == 0 { break }
    // ... buffer[0..<count]
}
secure.close()

guard let address = NetConnection.resolve("example.com"),
      let connection = NetConnection(address: address, port: 80) else { return }
let request: StaticString = "GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n"
_ = request.withUTF8Buffer { connection.send(Span(_unsafeElements: $0)) }
var buffer = InlineArray<1024, UInt8>(repeating: 0)
while let count = connection.receive(into: &buffer, timeout: 2_000_000_000), count > 0 {
    // ...
}
connection.close()

// manifest: capabilities = …, network.outgoing, device.camera
//           connects = api.anthropic.com      (+ uses-ai, uses-tls, uses-heap)
let result = Claude.ask(String(decoding: question, as: UTF8.self), jpeg: jpeg)
if let problem = result.problem {
    // problem: warum es keine Antwort gibt (kein Schlüssel, kein Netz …)
} else {
    answer = Array(result.text.utf8)
}

// manifest: capabilities = …, sound.play, device.microphone   (+ uses-heap)
guard let info = Microphone.info(at: 0) else {
    problem = TextLine("There is no microphone.")
    return true
}
guard let opened = Microphone.open(info.id) else { return true }
ring = opened
ring?.skipToNow()
autoLevel = AutoLevel(channels: channels, gain: Double(choices.gain))
gate = NoiseGate(channels: channels)
voice = VoiceDetector(channels: channels)

// in der Schleife:
if ring!.state == .stoppedByOwner { problem = TextLine("You stopped the microphone (MIC in the menu bar).") }
while true {
    let got = raw.withUnsafeMutableBufferPointer { ring!.read(into: $0.baseAddress!, frames: 4800) }
    guard got.frames > 0 else { break }
    // ... in 10-ms-Perioden: autoLevel.process(&span), gate.process(&span),
    //     LevelMeter.measure(span), voice.detect(span)
}

// beim Ende:
Microphone.close()

if output == nil { output = SoundOutput.open() }
guard let output else { return }
while output.room >= 480 && position < total {
    let count = min(output.room, 4800, total - position)
    // chunk mit count Stereo-Frames füllen (links, rechts)
    _ = chunk.withUnsafeBufferPointer { output.write($0.baseAddress!, count: count) }
    position += count
}
// Stopp: output.flush()

// manifest: capabilities = …, device.camera   publish = detections
var list: [CameraInfo] = []
var index = 0
while let info = Camera.info(at: index) { list.append(info); index += 1 }
ring = Camera.open(list[0].id)

func takeFrame() -> Bool {
    guard let ring else { return false }
    let taken = jpeg.withUnsafeMutableBytes { ring.newest(after: frame.number, into: $0) }
    guard let taken else { return false }
    guard case .success(let picture) = Picture.decode(Array(jpeg[0..<taken.count])) else { return false }
    // ... erkennen, zeichnen
    return true
}

nonisolated(unsafe) var publisher = Publications.detections()

var batch = DetectionBatch()
batch.frame = shown.number
batch.captured = shown.captured
batch.done = done
batch.width = width; batch.height = height
batch.objects[batch.count] = Sighting(classIndex: 3, score: 0.82, x0: 0.1, y0: 0.2, x1: 0.4, y1: 0.6)
batch.count += 1
publisher!.publish(batch)

// manifest: realtime = 1000 200 log
//           subscribe = video.detections
guard let ring = Publications.subscription(0) else {
    System.log("rtvision: no subscription (subscribe line missing)")
    return
}
var last: UInt32 = 0
while true {
    let now = System.time
    if let batch = ring.newest(after: last, now: now, maximumAge: 5_000_000_000) {
        last = batch.number
        // batch.objects[0..<batch.count], ring.classByte(classIndex, at) für den Namen
    }
    System.waitForNextPeriod()
}

guard let bytes = jpeg ? JPEG.encode(picture, quality: 90) : PNG.encode(picture),
      case .success(let file) = jpeg ? File.open("window.jpg", mode: .replace) : File.open("window.png", mode: .replace) else {
    saved = TextLine("Could not save the picture")
    return
}
bytes.withUnsafeBufferPointer { buffer in _ = file.write(Span(_unsafeElements: buffer)) }
_ = file.close()

var pdf = PDFDocument()
let margin = 40.0
pdf.text(name.isEmpty ? "Picture" : name, x: margin, y: margin + 14, size: 16, font: .bold)
pdf.text(String(shown.width) + " x " + String(shown.height) + " pixels · SOFTrobots OS Image",
         x: margin, y: margin + 32, size: 10, colour: (110, 110, 110))
_ = pdf.picture(shown, x: margin, y: margin + 50, width: 400, height: 300)
let bytes = pdf.data()

do {
    var opened = try PDFReader(fileBytes, password: password)
    for index in 0..<opened.pageCount {
        if let page = opened.page(index) {
            let turned = page.rotate == 90 || page.rotate == 270
            pageSizes.append(turned ? (page.height, page.width) : (page.width, page.height))
        }
    }
    let runs = opened.text(page: 0)     // [PDFTextRun]: text, x, y, size, width
} catch {
    // falsches Passwort, beschädigt …
}

invitationQR = QRCode.encode(bytes.span.extracting(0..<text.count), correction: .medium)
guard let code = invitationQR else { return }
let modules = code.size + 8
for y in 0..<code.size { for x in 0..<code.size where code.isDark(x: x, y: y) { /* Modul füllen */ } }

guard case .success(let file) = File.open(path, mode: .replace) else { return false }
var writer = MatroskaWriter(width: picture.width * picture.scale, height: picture.height * picture.scale, detections: true,
                            soundRate: recordSoundFormat.rate, soundChannels: recordSoundFormat.channels)
let header = writer.header()
_ = header.withUnsafeBufferPointer { file.write(Span(_unsafeElements: $0)) }

// je Kamerabild:
let milliseconds = Int((System.time &- recordStarted) / 1_000_000)
let piece = writer.frame(Array(jpeg[0..<jpegCount]), milliseconds: milliseconds)
_ = piece.withUnsafeBufferPointer { file.write(Span(_unsafeElements: $0)) }

var encoder = FLACEncoder(rate: rate, channels: channels, bits: 16)
pending = encoder.header()
// je 10-ms-Periode:
pending += encoder.encode(samples)          // Span<Int16>
// am Ende:
let (tail, finalHeader) = encoder.finish()

// manifest: capabilities = system.log, ipc, ui.surface, safety.stop
guard var actuator = Channel("actuator") else { System.log("arm: no actuator channel"); return }

private func move(_ to: Int32, _ actuator: inout Channel) {
    var bytes = InlineArray<9, UInt8>(repeating: 0)
    bytes[0] = 1                                   // 1 = move
    let values: InlineArray<2, Int32> = [to, 3_000] // Ziel und Geschwindigkeit in 0,01°
    for index in 0..<2 {
        let bits = UInt32(bitPattern: values[index])
        for byte in 0..<4 { bytes[1 + 4 * index + byte] = UInt8(truncatingIfNeeded: bits >> UInt32(8 * byte)) }
    }
    _ = actuator.send(bytes.span)
    actuator.notify()
}

// Antworten: 2 = Bewegung angenommen/begrenzt/abgelehnt, 3 = Status eines Gelenks
while let count = actuator.receive(into: &message), count >= 13 { /* ... */ }

// Not-Halt-Knopf:
System.emergencyStop(reason: 1)
// Freigeben:
System.releaseEmergencyStop()

var safety = System.safetyGeneration
if safety & 1 == 1 { motors.emergencyStop(true) }
while true {
    let now = System.safetyGeneration
    if now != safety { motors.emergencyStop(now & 1 == 1); safety = now }
    // ...
}

// manifest: subscribe = actuators.arm
guard let ring = Publications.subscriptionRing(0), let state = ArmRing.read(ring) else { return }
let model = ArmModel.chosen(state.id, count: state.idLength)
var q = ArmAngles()
for joint in 0..<model.count {
    q[joint] = Double(state.positions[joint]) / 100 * Double.pi / 180   // 0,01° → Radiant
}
let pose = model.forward(q)                       // pose.tip, pose.points
if let reach = model.inverse(x: 300, y: 0, z: 120, pitch: -Maths.pi / 2, near: q) { _ = reach }

// manifest: realtime = 1000 100      (Periode 1000 µs, Budget 100 µs; keine uses-heap-Datei)
@c(app_main)
func appMain() {
    var position: Int64 = 0, target: Int64 = 10_000, integral: Int64 = 0, previousError: Int64 = 0
    var nextReport = System.time + 5_000_000_000
    while true {
        let error = target - position
        integral += error
        let derivative = error - previousError
        previousError = error
        position += (error * 8 + integral / 64 + derivative * 2) / 256
        if System.time >= nextReport, let stats = System.realtimeStats(restartWorst: true) {
            nextReport += 5_000_000_000
            var line = TextLine("control: ")
            line.append(decimal: stats.missed)
            line.append(" missed, worst ")
            line.append(decimal: UInt64(stats.worstLatency * 1e9))
            line.append(" ns")
            System.log(line)
        }
        System.waitForNextPeriod()
    }
}

// manifest: record = samples 64 5 3600     (Name, Satzgröße, Sekunden im Ring, Sekunden auf Platte)
guard let recorder = Recorder.attach() else { return }
var record = InlineArray<56, UInt8>(repeating: 0)
// ... record füllen
_ = recorder.push(time: System.time, record.span)

guard let info = System.info() else { fail("no system information"); return }
guard info.apiVersion == 1, info.version.count > 0, info.cpus >= 1 else { fail("system information looks wrong"); return }

let callcost: StaticString = "callcost"
_ = callcost.withUTF8Buffer { Apps.launch(Span(_unsafeElements: $0)) }

var index = 0
while let crash = Apps.crash(at: index) {
    var line = TextLine()
    for i in 0..<crash.nameLength { line.append(byte: crash.name[i]) }
    line.append(": ")
    line.append(crash.reportPath)
    System.log(line)
    index += 1
}

switch id {
case EditMenu.copy, EditMenu.cut:
    guard Editor.hasSelection else { return }
    let bytes = Editor.selectedBytes
    _ = bytes.withUnsafeBufferPointer { Clipboard.copy(Span(_unsafeElements: $0)) }
    if id == EditMenu.cut { Editor.insert([]) }
case EditMenu.paste:
    var buffer = [UInt8](repeating: 0, count: 64 * 1024)
    var span = buffer.mutableSpan
    let length = Clipboard.paste(into: &span)
    _ = span
    guard length > 0 else { return }
    Editor.insert(Array(buffer[0..<length]))
default: break
}

// manifest: capabilities = system.log, ipc
guard var channel = Channel("bench") else {
    System.log("ipcping: channel refused")
    return
}
var reply = InlineArray<256, UInt8>(repeating: 0)
var message = InlineArray<64, UInt8>(repeating: 0x42)
for round in 0..<2_000 {
    message[0] = UInt8(truncatingIfNeeded: round)
    while !channel.send(message.span) { System.yield() }
    channel.notify()
    let count = channel.receiveWaiting(into: &reply)
    guard count == 64, reply[0] == message[0] else { System.log("ipcping: wrong reply"); return }
}

var line = TextLine("Stand ")
let time = WallClock.civil(unixMilliseconds: Int64(System.wallClock))
WallClock.appendDate(time, to: &line)
line.append(" ")
WallClock.appendTime(time, to: &line)
line.append(", Winkel ")
line.append(decimal: UInt64(Maths.degrees(Maths.atan2(1, 1))))
System.log(line)

state Listener {
    bangs: Int32 = 0
    lastBang: Time = 0
    talking: Bool = false
}

/// A bang: hold the arm (every joint stays where it is) and beep.
on microphone.loud(heard: Loudness) -> Listener {
    if isBang(level: heard.peak) and heard.taken - lastBang > 1 s {
        emit robot.move(joint: 1, to: 0°, in: 2 s)
        emit sound.tone(pitch: 660 Hz, length: 150 ms)
        return self with { bangs: bangs + 1, lastBang: heard.taken }
    }
    return self
}

on microphone.voice(change: VoiceChange) -> Listener {
    if change.speaking and not talking {
        emit robot.move(joint: 5, to: 20°, in: 0.3 s)
    }
    return self with { talking: change.speaking }
}

func isBang(BangLevel { level: Float32 }) -> Bool { return level > -6 }

test "a clap is a bang" { expect isBang(level: -3) }

state Hold {
    target: Angle = 30°
    periods: Int32 = 0
}

realtime every 1 ms -> Hold {
    let joint = robot.state(joint: 1)
    if periods % 20 == 0 {
        emit robot.move(joint: 1, to: joint.angle + step(gap: target - joint.angle).value, in: 20 ms)
    }
    return self with { periods: periods + 1 }
}

func step(Gap { gap: Angle }) -> Turn {
    if gap > 1° { return Turn(value: 1°) }
    if gap < -1° { return Turn(value: -1°) }
    return Turn(value: gap)
}

shape Turn { value: Angle }