client

client-go is the Go library for writing looking-glass modules. Modules are compiled to WebAssembly (GOARCH=wasm GOOS=wasip1) and run inside the looking-glass host. This library provides everything a module needs: identity, configuration, asset access, rendering, HTTP, and logging.

Note: This is in active development, the API may change.

How a module works

A looking-glass module is a standard Go main package compiled to a WASI binary. The host launches one instance per module slot, injects configuration via environment variables, mounts an assets directory, and exposes a small set of host functions for rendering and HTTP. The module runs its own event loop and calls mod.Content(widget) whenever the display should update.

Writing a module

1. Initialise the module

client.NewModule() reads the MODULE_NAME environment variable set by the host. It must be called before any other client functions that require the module identity.

//go:build wasip1

package main

import "github.com/glasslabs/client-go"

func main() {
    log := client.NewLogger()

    mod, err := client.NewModule()
    if err != nil {
        log.Error("Could not create module", "error", err.Error())
        return
    }
    // ...
}

2. Parse configuration

The host encodes the module's configuration map as JSON and exposes it via MODULE_CONFIG. Call mod.ParseConfig with a pointer to your config struct; fields are populated from the JSON keys that match the struct tags. Set defaults before calling ParseConfig so that omitted keys retain sensible values.

type Config struct {
    Interval int    `json:"interval"`
    Label    string `json:"label"`
}

cfg := Config{Interval: 60} // set defaults first
if err := mod.ParseConfig(&cfg); err != nil {
    log.Error("Could not parse config", "error", err.Error())
    return
}

3. Load assets

Static files (templates, images, SVG) are placed alongside the module binary. The host mounts them at /assets inside the WASM sandbox. Use mod.Asset(path) to read them; path is relative to that directory.

data, err := mod.Asset("index.html")

4. Render content

Call mod.Content(widget) to push a new widget tree to the display. The host replaces the module's current content with the new tree on every call — there is no diffing. Call it once on startup and again whenever the display needs to change.

Widget trees are built from the composable types in this package:

Text can be styled with option functions: WithColor, WithFontSize, WithLight, WithBold, WithItalic, WithCondensed, and WithAlign.

func render(mod *client.Module, label string) {
    mod.Content(client.NewVStack(
        client.NewText(label,
            client.WithColor("#ffffff"),
            client.WithFontSize(48),
            client.WithLight(),
        ),
        client.NewSpacer(),
    ))
}

Canvas drawing

Canvas renders a list of DrawOp commands within a logical coordinate space. The viewport is scaled uniformly to fit the allocated slot.

Label is built from TextRun segments created with NewRun(content, ...opts). Options: WithRunFontSize, WithRunBaselineShift, WithRunColor.

5. Make HTTP requests

The host provides an HTTP transport that is automatically installed into http.DefaultClient when the module starts. Use the standard net/http package directly — no special client is required.

resp, err := http.Get("https://example.com/api/data")

The transport supports streaming response bodies, so Server-Sent Events and other long-lived streams work as expected.

6. Log messages

client.NewLogger() returns a logger that writes logfmt lines to stderr. The host captures these lines and forwards them to its structured logging pipeline.

log := client.NewLogger()
log.Info("Module ready", "module", mod.Name())
log.Error("Something failed", "error", err.Error())

Methods: Debug, Info, Warn, Error. Each accepts a message followed by alternating key/value string pairs.

Building a module

Modules must be compiled for the wasip1 target:

GOARCH=wasm GOOS=wasip1 go build -o my-module.wasm .

All source files that use client-go should carry the //go:build wasip1 build constraint, as the host functions are only available inside the WASM sandbox.

Minimal example

//go:build wasip1

package main

import (
    "time"

    "github.com/glasslabs/client-go"
)

type Config struct {
    Format string `json:"format"`
}

func main() {
    log := client.NewLogger()

    mod, err := client.NewModule()
    if err != nil {
        log.Error("Could not create module", "error", err.Error())
        return
    }

    cfg := Config{Format: "15:04:05"}
    if err = mod.ParseConfig(&cfg); err != nil {
        log.Error("Could not parse config", "error", err.Error())
        return
    }

    log.Info("Module ready", "module", mod.Name())

    for {
        mod.Content(client.NewText(
            time.Now().Format(cfg.Format),
            client.WithColor("#ffffff"),
            client.WithFontSize(48),
        ))
        time.Sleep(time.Second)
    }
}