README.md — sigil-web-client

1# sigil-web-client

Client-side WASM UI framework for [Sigil](https://codeberg.org/sigil/sigil). A react-like rendering layer for browser applications compiled to WebAssembly: it renders Sigil SXML into the browser DOM and keeps application code independent of the underlying WASM DOM bridge.

`(sigil web client)` is the browser-side counterpart to the server-side [sigil-web](https://codeberg.org/sigil/sigil-web) framework. The two are orthogonal: this library imports only `sigil-wasm-dom` and shares no code with the server-side modules.

7## Usage

9```scheme

10(import (sigil web client))

12;; Look up a DOM root by selector

13(define root (web-client-root "#app"))

15;; Mount a view: SXML, or a nullary procedure returning SXML

16(web-client-mount root (lambda () `(div "Hello, world!")))

18;; Update the mounted view in place

19(web-client-update root (lambda () `(div "Updated!")))

21;; Clear a root

22(web-client-clear root)

23```

25### Memoized subtrees

27Use `web-client-memo` when a rendered subtree is immutable for a known

28revision:

30```scheme

31(web-client-memo

32 turn-id turn-revision

33 (lambda ()

34 `(section ,@(render-completed-turn turn))))

35```

37When a later `web-client-update` produces the same key and revision,

38reconciliation retains that element's complete DOM subtree without evaluating

39the producer or walking its attributes and descendants. A changed revision

40evaluates the producer and resumes normal reconciliation. The key and revision

41are renderer metadata and are not written to the DOM.

43Memoized content must be immutable for the lifetime of its revision, including

44event handlers and attributes on the boundary element. Use this for stable,

45expensive regions while leaving actively changing siblings unmemoized.

47### Exports

49- `web-client-root` — look up a DOM root node by selector

50- `web-client-root?` — validate a root node handle

51- `web-client-render` — render a view (an SXML value, or a nullary procedure returning one)

52- `web-client-mount` — mount a view into a root

53- `web-client-update` — update a mounted view in place; returns `#f` without

54 mutating when retained children no longer match the DOM (call

55 `web-client-clear` to recover from out-of-band changes)

56- `web-client-clear` — clear a root

57- `web-client-reset!` — reset retained client state

59## Building

61This is a browser/WASM library. Build it into a web application with the `web` config:

63```sh

64sigil deps install

65sigil build --config web

66```

68## License

70BSD-3-Clause