docs: make the comments and the README shorter

Keep each comment to no more than two lines and remove the comments that
say again what the code says. Write the README in Simplified Technical
English with short sentences.

Author: deadprogram

.github/workflows/pages.yml

@@ -1,7 +1,5 @@
 # Build the page with TinyGo and put it on GitHub Pages.
-#
-# Nothing binary lives in the repo. The WebAssembly builds of llama.cpp come
-# down here, and the Go program is compiled here.
+# Nothing binary lives in the repo, so llama.cpp comes down here.
 name: pages
 
 on:
@@ -29,8 +27,8 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v5
 
-      # TinyGo 0.41.1 works with Go 1.26 and not with Go 1.27. Go back to
-      # 'stable' after the release of TinyGo that adds Go 1.27.
+      # TinyGo 0.41.1 works with Go 1.26 and not with Go 1.27. Use 'stable'
+      # again after a release of TinyGo that adds Go 1.27.
       - name: Install Go
         uses: actions/setup-go@v6
         with:

Makefile

@@ -1,20 +1,18 @@
 # Build the page into build/, then serve it.
-#
-# The first build downloads about 20 MB of llama.cpp, which is cached by the
-# tag in the name, so only "make clean" makes it happen again.
+# The first build downloads about 20 MB of llama.cpp, and then caches it.
 
 BUILD_DIR ?= build
 PORT ?= 8080
 
 # The version of llama.cpp that the current release of yzma is built against.
 LLAMA_VERSION ?= $(shell curl -s https://hybridgroup.github.io/llama-cpp-builder/version.json | jq -r .tag_name)
 
-# yzma ships yzma-loader.js next to the Go package, so take it from the module
-# that go.mod pins rather than keeping a copy here that can drift.
+# Take yzma-loader.js from the module that go.mod pins, not from a copy
+# here that can drift.
 YZMA_DIR = $(shell go list -m -f "{{.Dir}}" github.com/hybridgroup/yzma)
 
-# The yzma command has to be the version that go.mod pins, not whatever is
-# already on the PATH: the two move together.
+# The yzma command has to be the version that go.mod pins, because the two
+# move together.
 YZMA_VERSION = $(shell go list -m -f "{{.Version}}" github.com/hybridgroup/yzma)
 # GOBIN when it is set, and GOPATH/bin when it is not.
 YZMA_BIN = $(firstword $(shell go env GOBIN) $(shell go env GOPATH)/bin)
@@ -26,8 +24,8 @@ all: build
 
 build: llama.cpp program assets
 
-# llama.cpp brings down all three WebAssembly builds: WebGPU, more than one
-# thread, and one thread. yzma-loader.js takes the best one at run time.
+# This brings down all three WebAssembly builds. yzma-loader.js takes the
+# best one at run time.
 llama.cpp:
 	go install github.com/hybridgroup/yzma@$(YZMA_VERSION)
 	mkdir -p $(BUILD_DIR)
@@ -43,19 +41,18 @@ assets:
 	cp -f $(YZMA_DIR)/wasm/yzma-loader.js $(BUILD_DIR)/
 	cp web/* $(BUILD_DIR)/
 
-# The service worker sets the headers this server also sets, so either one is
-# enough on localhost. On GitHub Pages only the service worker can.
+# This server sets the same headers as the service worker, so either one is
+# enough on localhost.
 serve:
 	go run github.com/hybridgroup/yzma/wasm/serve -dir $(BUILD_DIR) -port $(PORT)
 
-# check builds with the standard toolchain, which catches a mistake in the API
-# without waiting for TinyGo.
+# check builds with the standard toolchain, which is faster than TinyGo.
 check:
 	GOOS=js GOARCH=wasm go build -o /dev/null .
 	GOOS=js GOARCH=wasm go vet ./...
 
-# test holds a two turn conversation in Node, with no browser. It needs a
-# model with a chat template:
+# test holds a two turn conversation in Node. It needs a model with a chat
+# template.
 #
 #   make test MODEL=~/models/Qwen2.5-0.5B-Instruct-Q4_K_M.gguf
 MODEL ?=

README.md

@@ -2,15 +2,20 @@
 
 ![yzma in browser](./images/yzma-in-browser.png)
 
-A chat page where the whole language model runs in the tab. No server, no API key, nothing sent anywhere.
+A chat page that runs the language model in the browser tab. There is no server,
+no API key, and no data goes anywhere.
 
 **<https://hybridgroup.github.io/yzma-wasm-example/>**
 
 ## How it works
 
 [![yzma logo](https://raw.githubusercontent.com/hybridgroup/yzma/refs/heads/main/images/yzma-logo-full-color-small.png)](https://github.com/hybridgroup/yzma)
 
-The code is written in Go and compiled by TinyGo. Using the [yzma](https://github.com/hybridgroup/yzma) package, the web page runs [llama.cpp](https://github.com/ggml-org/llama.cpp), which has been compiled into a WebAssembly module. It all runs in a local Web Worker for best browser performance.
+The code is written in Go and compiled by TinyGo. The page uses the
+[yzma](https://github.com/hybridgroup/yzma) package to run
+[llama.cpp](https://github.com/ggml-org/llama.cpp), which is compiled into a
+WebAssembly module. All of it runs in a local Web Worker for the best browser
+performance.
 
 ```
    index.html
@@ -21,91 +26,92 @@ The code is written in Go and compiled by TinyGo. Using the [yzma](https://githu
    (Go, TinyGo) -> (llama.cpp, Emscripten)
 ```
 
-The page stores no record of the conversation. The conversation data is only in the TinyGo WASM module, and each turn puts the whole conversation back through the model.
+The page keeps no record of the conversation. The conversation stays in the
+TinyGo WASM module. Each turn sends the full conversation through the model
+again.
 
 ## Build and run
 
-Needs [TinyGo](https://tinygo.org/getting-started/install/) 0.41 or later, Go
+You need [TinyGo](https://tinygo.org/getting-started/install/) 0.41 or later, Go
 1.26, `jq`, and `node` for the test.
 
 ```
 make build
 make serve
 ```
 
-Then open <http://localhost:8080>, press **Load**, and wait for the model to come
-down. The default is
-[Qwen2.5-0.5B-Instruct Q4_K_M](https://huggingface.co/bartowski/Qwen2.5-0.5B-Instruct-GGUF),
-about 400 MB, which the browser caches. Any GGUF URL works as long as the host
-sends CORS headers, which Hugging Face does.
+Open <http://localhost:8080>, push **Load**, and wait for the download of the
+model. The default model is
+[Qwen2.5-0.5B-Instruct Q4_K_M](https://huggingface.co/bartowski/Qwen2.5-0.5B-Instruct-GGUF).
+It is approximately 400 MB, and the browser caches it. You can use any GGUF URL
+if the host sends CORS headers. Hugging Face sends them.
 
-`make build` downloads about 14 MB of llama.cpp into `build/`, compiles the Go
-program, and copies the page. Nothing binary lives in the repo.
+`make build` downloads approximately 14 MB of llama.cpp into `build/`, compiles
+the Go program, and copies the page. No binary files are in the repository.
 
 ## The test
 
-A two turn conversation, in Node, with no browser. The second question only
-makes sense if the first one is still in the prompt, so a sensible answer means
-the chat template came out right:
+The test holds a two turn conversation in Node, with no browser. The second
+question makes sense only if the first question is still in the prompt. Thus a
+sensible answer shows that the chat template is correct.
 
 ```
 make test MODEL=~/models/Qwen2.5-0.5B-Instruct-Q4_K_M.gguf
 ```
 
-## Threads, and why there is a service worker
+## Threads and the service worker
 
-llama.cpp comes in three WebAssembly builds, and `yzma-loader.js` takes the best
-one the browser can run:
+llama.cpp has three WebAssembly builds. `yzma-loader.js` selects the best build
+that the browser can run.
 
 | Build | What it needs |
 | --- | --- |
 | `yzma_wasm_webgpu` | WebGPU with f16 shaders, and JSPI. Chrome and Edge 137 and later. |
-| `yzma_wasm_mt` | `SharedArrayBuffer`, so a page with the COOP and COEP headers. |
-| `yzma_wasm` | Nothing. It works everywhere. |
+| `yzma_wasm_mt` | `SharedArrayBuffer`, thus a page with the COOP and COEP headers. |
+| `yzma_wasm` | Nothing. It runs everywhere. |
 
-GitHub Pages cannot send the COOP and COEP headers, so without help a browser
-gives the page no `SharedArrayBuffer` and llama.cpp runs on one thread. In Node
+GitHub Pages cannot send the COOP and COEP headers. Without help, the browser
+gives the page no `SharedArrayBuffer`, and llama.cpp runs on one thread. In Node
 that is the difference between 0.9 and 9.6 tokens a second on Qwen2.5 0.5B.
 
-So the page loads
-[`coi-serviceworker.js`](https://github.com/gzuidhof/coi-serviceworker) first.
-It registers a service worker that adds the two headers and reloads the page
-once, and from then on the page is cross-origin isolated and the loader takes
-the build with every thread. It works on localhost too, so a plain static server
-is enough for development. `make serve` sets the headers as well, which makes no
-difference but does no harm.
+Thus the page loads
+[`coi-serviceworker.js`](https://github.com/gzuidhof/coi-serviceworker) first. It
+registers a service worker that adds the two headers and reloads the page once.
+After that the page is cross origin isolated, and the loader selects the build
+with all of the threads. This also operates on localhost, thus a usual static
+server is sufficient for development. `make serve` sets the headers too, which
+makes no difference but does no damage.
 
-Cross-origin isolation does mean a model has to come from a host that sends CORS
-headers. Hugging Face does.
+Cross origin isolation makes it necessary for the model to come from a host that
+sends CORS headers. Hugging Face sends them.
 
-The line at the top right of the page says which build won. Force one with
-`?mode=cpu` or `?mode=webgpu` on the URL.
+The line at the top right of the page shows the selected build. To force a
+build, add `?mode=cpu` or `?mode=webgpu` to the URL.
 
 ## Notes
 
-- The system prompt box tells the model how to answer. The page sends it with
-  each question, so a change applies to the next answer. An empty box gives the
-  default prompt back.
-- The model has to be smaller than 2 GB. One JavaScript ArrayBuffer holds no
-  more, so anything larger has to be in GGUF splits.
-- Use a model with a chat template. A base model has none, and the page says so,
-  but the answers wander.
-- `ChatApplyTemplate` formats one message at a time, so `prompt` in `main.go`
-  puts the conversation together one message after another. That is exactly
-  right for a chatml model such as Qwen. A model whose template puts something
-  once at the top of a conversation, such as Gemma folding the system message
-  into the first user turn, comes out slightly off.
-- A discrete NVIDIA card does not give f16 shaders in Chrome, so such a machine
-  falls back to the CPU unless Chrome starts with
+- The system prompt box tells the model how to answer. The page sends the prompt
+  with each question, thus a change applies to the next answer. An empty box
+  gives the default prompt again.
+- The model must be smaller than 2 GB. One JavaScript ArrayBuffer holds no more,
+  thus a larger model must be in GGUF splits.
+- Use a model with a chat template. A base model has no template. The page shows
+  a message, but the answers are poor.
+- `ChatApplyTemplate` formats one message at a time. Thus `prompt` in `main.go`
+  puts the conversation together one message after the other. This is correct
+  for a chatml model such as Qwen. It is not fully correct for a model whose
+  template puts something one time at the top of a conversation, such as Gemma,
+  which folds the system message into the first user turn.
+- A discrete NVIDIA card does not give f16 shaders in Chrome. Such a machine
+  falls back to the CPU unless you start Chrome with
   `--enable-dawn-features=vulkan_enable_f16_on_nvidia`.
 
 ## Deploying
 
-`.github/workflows/pages.yml` builds and deploys on every push to `main`. Set
-**Settings → Pages → Source** to **GitHub Actions** once, and that is all.
+`.github/workflows/pages.yml` builds and deploys on each push to `main`. Set
+**Settings → Pages → Source** to **GitHub Actions** one time. That is all.
 
 ## License
 
-Apache 2.0, the same as yzma. `web/min.css`
-([min](https://mincss.com)) and `web/coi-serviceworker.js` are MIT, and keep
-their own notices.
+Apache 2.0, the same as yzma. `web/min.css` ([min](https://mincss.com)) and
+`web/coi-serviceworker.js` are MIT, and they keep their own notices.

main.go

@@ -1,16 +1,7 @@
 //go:build js && wasm
 
-// A chat that runs entirely in the browser.
-//
-// llama.cpp is a WebAssembly module. This program drives it through the
-// pkg/llamawasm package of yzma, keeps the turns of the conversation, and sends
-// each piece of the answer to the page as it arrives.
-//
-// Build it with TinyGo:
-//
-//	tinygo build -target wasm -o build/yzma.wasm .
-//
-// See README.md for the rest.
+// Package main is a chat that runs a language model in the browser.
+// It drives llama.cpp through yzma and sends each piece of the answer to the page.
 package main
 
 import (
@@ -23,8 +14,7 @@ import (
 )
 
 const (
-	// modelPath is where the model goes in the filesystem of the llama.cpp
-	// module, once the page has downloaded it.
+	// modelPath is where the model goes in the filesystem of llama.cpp.
 	modelPath = "/models/model.gguf"
 
 	// defaultSystem opens a conversation until the page sends another one.
@@ -37,7 +27,7 @@ const (
 	defaultMaxTokens = 512
 )
 
-// A turn is one message of the conversation.
+// turn is one message of the conversation.
 type turn struct {
 	Role    string
 	Content string
@@ -68,7 +58,6 @@ func main() {
 	js.Global().Set("yzmaReset", js.FuncOf(reset))
 	js.Global().Set("yzmaSetSystem", js.FuncOf(setSystem))
 
-	// The page shows this in its system prompt box.
 	post("system", defaultSystem)
 	post("ready", backendReport())
 
@@ -103,9 +92,8 @@ func loadModel(this js.Value, args []js.Value) any {
 	return nil
 }
 
-// openModel(path) loads a model that is already in the filesystem of the
-// llama.cpp module. The page downloads one instead; a test puts it there
-// itself.
+// openModel(path) loads a model that is already in the filesystem of llama.cpp.
+// The page downloads one instead, but the test puts it there itself.
 func openModel(this js.Value, args []js.Value) any {
 	path := modelPath
 	if len(args) > 0 && args[0].Truthy() {
@@ -123,8 +111,8 @@ func open(path string) {
 
 	params := llamawasm.ModelDefaultParams()
 
-	// A build with WebGPU has a device, so put every layer on it. A build on the
-	// CPU has none, and the value does nothing there.
+	// A build with WebGPU has a device, so put every layer on it.
+	// A build on the CPU has none, and the value does nothing.
 	if llamawasm.GPUDevice() != "" {
 		params.NGpuLayers = 999
 	}
@@ -146,8 +134,8 @@ func open(path string) {
 
 	vocab = llamawasm.ModelGetVocab(model)
 
-	// One sampler for the whole conversation. A chat wants some variety, which
-	// is what this chain gives and the greedy sampler does not.
+	// One sampler for the whole conversation. This chain gives the variety
+	// that a chat needs and the greedy sampler does not.
 	if sampler != 0 {
 		llamawasm.SamplerFree(sampler)
 	}
@@ -160,8 +148,7 @@ func open(path string) {
 
 	history = history[:1]
 
-	// A base model has no chat template, and the answers of one in a chat are
-	// poor. Say so rather than letting the reader wonder.
+	// A base model has no chat template, and its answers in a chat are poor.
 	if llamawasm.ModelChatTemplate(model, "") == "" {
 		post("status", "this model has no chat template, so the answers will wander")
 	}
@@ -227,8 +214,8 @@ func ask(this js.Value, args []js.Value) any {
 			return
 		}
 
-		// The whole conversation goes in again each turn, so the state of the
-		// last one has to go.
+		// The whole conversation goes in again each turn, so the state of
+		// the last turn has to go.
 		if err := llamawasm.MemoryClear(ctx, true); err != nil {
 			post("error", err.Error())
 			return
@@ -277,27 +264,23 @@ func ask(this js.Value, args []js.Value) any {
 	return nil
 }
 
-// prompt puts the conversation into the chat format of the model and tokenizes
-// it. It drops the oldest turns until what is left has room for an answer.
-//
-// ChatApplyTemplate takes one message at a time, so a conversation is the
-// messages one after another, with the opening of the turn of the assistant on
-// the last one. That is what makes the model answer instead of carrying on.
+// prompt puts the conversation into the chat format of the model and tokenizes it.
+// It drops the oldest turns until what is left has room for an answer.
 func prompt(maxTokens int32) []llamawasm.Token {
 	for {
 		var text strings.Builder
 		for i, message := range history {
 			formatted, err := llamawasm.ChatApplyTemplate(model, message.Role, message.Content, i == len(history)-1)
 			if err != nil {
-				// A model with no template, or a build of llama.cpp too old to
-				// have the call. The bare question is the best that is left.
+				// The model has no template, or llama.cpp is too old to have
+				// the call. The bare question is all that is left.
 				return llamawasm.Tokenize(vocab, history[len(history)-1].Content, true, false)
 			}
 			text.WriteString(formatted)
 		}
 
-		// parseSpecial has to be true, or the markers of the template tokenize
-		// as ordinary text and the model never sees the shape of a chat.
+		// parseSpecial has to be true, or the markers of the template
+		// tokenize as ordinary text and the model sees no chat.
 		tokens := llamawasm.Tokenize(vocab, text.String(), true, true)
 
 		if int32(len(tokens)) <= nCtx-maxTokens || len(history) <= 2 {
@@ -313,8 +296,7 @@ func prompt(maxTokens int32) []llamawasm.Token {
 	}
 }
 
-// post sends a message to whatever holds this module. In a Web Worker that is
-// the page, and in Node it is the harness.
+// post sends a message to the page in a Web Worker, or to the harness in Node.
 func post(kind, text string) {
 	message := map[string]any{"kind": kind, "text": text}