@amritk/nish-aarch64-darwin 0.35.0 → 0.36.0

package/runtime/vite.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `nish/vite`: the Vite plugin that builds a Nish module imported by a page
+ * into wasm, inlined and loaded without a fetch (docs/guide/using-nish/interop.md).
+ */
+
+export interface NishViteOptions {
+  /** Modules to build to wasm, paths from the root. Default: none. */
+  entries?: string[];
+  /**
+   * Host modules, paths from the root, each passed to the compiler as
+   * `--host`; a root `package.json` `"nish": { "host": [...] }` also names
+   * them. The ones an entry imports are passed to its loader. Default: none.
+   */
+  host?: string[];
+  /** The `nish` command. Default: this package's `bin/nish`. */
+  compiler?: string;
+  /** `scripts/build.sh`. Default: this package's. */
+  buildScript?: string;
+}
+
+/** The hooks the plugin uses, which Vite and Rollup share. */
+export interface NishVitePlugin {
+  name: "nish";
+  enforce: "pre";
+  configResolved(config: { root?: string; command?: "build" | "serve"; cacheDir?: string }): void;
+  resolveId(source: string, importer?: string): Promise<string | null>;
+  load(id: string): Promise<string | null>;
+}
+
+export default function nish(options?: NishViteOptions): NishVitePlugin;

package/runtime/vite.mjs

@@ -0,0 +1,150 @@
+/**
+ * `nish/vite` (WP50 stage 1): a Vite plugin that lets a page import a Nish
+ * module as the TypeScript it is and get, in a build, the wasm build of it.
+ *
+ * The entries are the modules compiled to wasm, `nish({ entries })`, paths
+ * from the root. (The root package.json's `nish` field cannot name them yet:
+ * the compiler refuses a key there other than `noPanic`, `capabilities` and
+ * `host`.) In
+ * `vite build` an import that resolves to one is answered with a generated
+ * module. The plugin compiles the entry with `nish --target wasm32 --emit-dts`,
+ * links the IR with `scripts/build.sh --profile wasm-host --inline`, and the
+ * generated module calls the loader's `loadSync` on the inlined bytes and
+ * re-exports each export by name. The page fetches nothing and awaits nothing.
+ * In `vite serve` the import is left to Vite, which serves the TypeScript.
+ *
+ * An entry that imports host modules (WP50 stage 2) is instantiated with
+ * them: the generated module imports each one the `.d.ts` names in `Imports`
+ * and passes them as `host`, so the page passes nothing. One seam is left for
+ * a later stage of docs/wp50-wasm-host.md: the `.nish` client specifier in
+ * `resolveId`.
+ *
+ * The plugin drives only the hooks Vite and Rollup share (`configResolved`,
+ * `resolveId`, `load`), so `tests/run.js` calls them directly, with no Vite.
+ */
+import { execFile } from "node:child_process";
+import { mkdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+const packageDir = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const PREFIX = "\0nish-entry:";
+
+/**
+ * The host modules an entry imports, as absolute paths: the
+ * `typeof import("...")` members of the `.d.ts`'s `Imports` type, each a
+ * specifier from the `.d.ts`'s directory written without its `.ts`, which is
+ * put back so the import names the file. None when there is no `Imports`.
+ */
+function hostModules(dts, dir) {
+  const line = dts.split("\n").find((l) => l.startsWith("export type Imports = "));
+  if (line === undefined) return [];
+  return [...line.matchAll(/typeof import\("([^"]+)"\)/g)].map((m) => `${path.resolve(dir, m[1])}.ts`);
+}
+
+/**
+ * The import lines and the import object an entry is instantiated with: each
+ * host module imported whole and passed under `host`, or `{}` with none.
+ */
+function importsFor(hosts) {
+  const lines = hosts.map((h, i) => `import * as __nishHost${i} from ${JSON.stringify(h)};`);
+  if (hosts.length === 0) return { lines, object: "{}" };
+  const host = hosts.length === 1 ? "__nishHost0" : `{ ${hosts.map((_, i) => `...__nishHost${i}`).join(", ")} }`;
+  return { lines, object: `{ host: ${host} }` };
+}
+
+/**
+ * The names the loader returns, read from the `Exports` interface of the
+ * `.d.ts` the same compile wrote: one member a line, `memory` included.
+ */
+function exportNames(dts) {
+  const body = dts.slice(dts.indexOf("export interface Exports {"));
+  const names = [];
+  for (const m of body.slice(0, body.indexOf("\n}")).matchAll(/^ {2}(?:readonly )?([A-Za-z_$][\w$]*)[(:]/gm)) {
+    names.push(m[1]);
+  }
+  return names;
+}
+
+/** The plugin. `compiler` and `buildScript` default to the ones in this package. */
+export default function nish(options = {}) {
+  const compiler = options.compiler ?? path.join(packageDir, "bin", "nish");
+  const buildScript = options.buildScript ?? path.join(packageDir, "scripts", "build.sh");
+  const runtimeWasm = path.join(packageDir, "runtime", "runtime-wasm.c");
+  let root = process.cwd();
+  let building = false;
+  let cacheDir = path.join(root, "node_modules", ".vite");
+  let entries = new Set();
+
+  const configure = (config) => {
+    root = config.root ?? root;
+    building = config.command === "build";
+    cacheDir = config.cacheDir ?? path.join(root, "node_modules", ".vite");
+    entries = new Set((options.entries ?? []).map((e) => path.resolve(root, e)));
+  };
+  configure({ root });
+
+  /** Compile and link one entry; resolves to the paths the generated module imports. */
+  const buildEntry = async (entry) => {
+    const stem = path.basename(entry, path.extname(entry));
+    const dir = path.join(cacheDir, "nish", path.relative(root, entry).replace(/[\\/]/g, "_"));
+    mkdirSync(dir, { recursive: true });
+    const ll = path.join(dir, `${stem}.ll`);
+    const dts = path.join(dir, `${stem}.d.ts`);
+    const host = (options.host ?? []).flatMap((h) => ["--host", path.resolve(root, h)]);
+    await run(compiler, [entry, "--target", "wasm32", ...host, "--emit-dts", dts, "-o", ll], { cwd: root });
+    const loader = path.join(dir, `${stem}.mjs`);
+    const ir = readFileSync(ll, "utf8");
+    // runtime-wasm.c is linked when the IR needs a runtime function (a weak
+    // `extern_weak` one, a panic stub wasm-ld writes itself, does not count)
+    // or the loader calls the arena.
+    const needsRuntime =
+      /^declare (?!extern_weak)[^"\n]*@nish_/m.test(ir) ||
+      readFileSync(loader, "utf8").includes("raw.nish_arena_mark(");
+    const inline = path.join(dir, `${stem}.bytes.mjs`);
+    const inputs = needsRuntime ? [ll, runtimeWasm] : [ll];
+    await run("bash", [buildScript, ...inputs, "-o", path.join(dir, `${stem}.wasm`), "--profile", "wasm-host", "--inline", inline], {
+      cwd: root,
+    });
+    const types = readFileSync(dts, "utf8");
+    return { loader, inline, names: exportNames(types), hosts: hostModules(types, dir) };
+  };
+
+  return {
+    name: "nish",
+    enforce: "pre",
+    configResolved: configure,
+    async resolveId(source, importer) {
+      if (!building) return null;
+      // The seam for a `./client.nish` specifier (the page's client module of a
+      // later stage) is here; stage 1 resolves only the entries.
+      const base = importer ? path.dirname(importer) : root;
+      const candidates = source.startsWith(".")
+        ? [path.resolve(base, source)]
+        : path.isAbsolute(source)
+          ? [source, path.join(root, source)]
+          : [];
+      const hit = candidates.find((c) => entries.has(c));
+      return hit === undefined ? null : PREFIX + hit;
+    },
+    async load(id) {
+      if (!id.startsWith(PREFIX)) return null;
+      const entry = id.slice(PREFIX.length);
+      const { loader, inline, names, hosts } = await buildEntry(entry);
+      const imports = importsFor(hosts);
+      // The module's own bindings are prefixed, so an export named `bytes`,
+      // `loadSync` or `exports` does not redeclare one of them.
+      const lines = [
+        `import { loadSync as __nishLoadSync } from ${JSON.stringify(loader)};`,
+        `import { bytes as __nishBytes } from ${JSON.stringify(inline)};`,
+        ...imports.lines,
+        `const __nishExports = __nishLoadSync(__nishBytes, ${imports.object});`,
+        "export default __nishExports;",
+      ];
+      if (names.length > 0) lines.push(`export const { ${names.join(", ")} } = __nishExports;`);
+      return `${lines.join("\n")}\n`;
+    },
+  };
+}

package/scripts/build.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Build an Nish .ll module (plus optional C sources) into a native binary.
 #
-#   scripts/build.sh <module.ll> [more .ll/.c files...] -o <out> [--profile debug|speed|size|wasm|wasi|napi]
+#   scripts/build.sh <module.ll> [more .ll/.c files...] -o <out> [--profile debug|speed|size|wasm|wasm-host|wasi|napi]
 #
 # The C runtime is sixteen translation units and is named as one: an input
 # <dir>/runtime.c also compiles <dir>/runtime-os.c, the half that wraps the
@@ -33,6 +33,28 @@
 #          load it from Node. Add runtime/runtime-wasm.c to the inputs when a
 #          function uses arrays (the arena and the array cold paths, no libc);
 #          strings and I/O still need a WASI runtime and are not available.
+#   wasm-host  the wasm profile's module for a page (WP50 stage 1): the same
+#          inputs, linked with an explicit export list instead of exporting
+#          everything -- the program's exported functions, `memory`, and,
+#          when runtime-wasm.c is linked, the arena entry points the
+#          `--emit-dts` loader calls (nish_arena_mark, nish_arena_release,
+#          nish_alloc_array, nish_reset_arena, nish_free_arena). The stack is
+#          a fixed 64 KiB (-z stack-size=65536). Runs `wasm-opt -Oz` on the
+#          module when wasm-opt (binaryen) is on PATH; the build line says
+#          whether it ran. Two flags take this profile alone, and any other
+#          refuses them with exit 2:
+#            --memory <MiB>       memory fixed at <MiB> MiB (1 to 4096), the
+#                                 initial size and the maximum both, so it
+#                                 never grows and `memory.buffer` is one
+#                                 ArrayBuffer for the module's life; an arena
+#                                 that runs out traps. Without it (the
+#                                 default) the memory starts at what the
+#                                 module needs and grows on demand, as under
+#                                 the wasm profile.
+#            --inline <file.mjs>  also write <file.mjs>, an ES module whose
+#                                 `export const bytes = new Uint8Array([...])`
+#                                 holds the .wasm's bytes, so a page loads the
+#                                 module with `loadSync(bytes)` and no fetch.
 #   wasi   wasm32-wasi command module: runtime.c linked against wasi-libc, so
 #          string programs run under any WASI host (`_start` runs `main`;
 #          `node examples/wasi-host.mjs app.wasm args...`). Needs a WASI
@@ -138,6 +160,9 @@ cpu=""                                 # --cpu x86-64-v3: the one CPU level abov
 sqlite_to=""                           # --sqlite-objects <dir>: compile runtime/sqlite/ alone, into <dir>
 sqlite_from=""                         # --sqlite-from <dir>: link runtime/sqlite/ compiled there
 modules_at=""                          # --module-objects <dir>: each X.ll's object is <dir>/X.o
+memory_mib=""                          # --memory <MiB>: wasm-host's fixed memory (WP50 stage 1)
+wasm_opt=""                            # what the build line says of wasm-opt; set only by wasm-host
+inline_to=""                           # --inline <file.mjs>: wasm-host's bytes as an ES module
 while [ $# -gt 0 ]; do
   case "$1" in
     -o) out="$2"; shift 2 ;;
@@ -152,6 +177,12 @@ while [ $# -gt 0 ]; do
     --sqlite-objects) sqlite_to="$2"; shift 2 ;;
     --sqlite-from) sqlite_from="$2"; shift 2 ;;
     --module-objects) modules_at="$2"; shift 2 ;;
+    --memory)
+      [ -n "${2-}" ] || { echo "error: --memory needs a size in MiB" >&2; exit 2; }
+      memory_mib="$2"; shift 2 ;;
+    --inline)
+      [ -n "${2-}" ] || { echo "error: --inline needs a file to write" >&2; exit 2; }
+      inline_to="$2"; shift 2 ;;
     --pgo-generate) pgo=(-fprofile-generate); shift ;;
     --pgo-use)
       [ -f "$2" ] || { echo "error: --pgo-use: profile '$2' not found (run the instrumented binary, then llvm-profdata merge)" >&2; exit 2; }
@@ -164,9 +195,19 @@ done
 if [ -n "$cpu" ]; then
   [ "$cpu" = x86-64-v3 ] || { echo "error: --cpu takes x86-64-v3, not '$cpu'" >&2; exit 2; }
   case "$profile" in
-    wasm|wasi) echo "error: --cpu x86-64-v3 is an x86-64 level, so the $profile profile does not take it" >&2; exit 2 ;;
+    wasm|wasm-host|wasi) echo "error: --cpu x86-64-v3 is an x86-64 level, so the $profile profile does not take it" >&2; exit 2 ;;
   esac
 fi
+if [ -n "$memory_mib" ] || [ -n "$inline_to" ]; then
+  [ "$profile" = wasm-host ] || { echo "error: --memory and --inline take the wasm-host profile, not '$profile'" >&2; exit 2; }
+fi
+if [ -n "$memory_mib" ]; then
+  case "$memory_mib" in
+    *[!0-9]*|0*) memory_ok=0 ;;
+    *) if [ "${#memory_mib}" -le 4 ] && [ "$memory_mib" -le 4096 ]; then memory_ok=1; else memory_ok=0; fi ;;
+  esac
+  [ "$memory_ok" = 1 ] || { echo "error: --memory takes a whole number of MiB from 1 to 4096, not '$memory_mib'" >&2; exit 2; }
+fi
 # wasm-ld exports a wasm module's linear memory as `memory`, so under the wasm
 # profile's `--export-all` a function of that name makes a module Node refuses
 # to compile ("Duplicate export name 'memory'", #643). The wasi module exports
@@ -175,7 +216,7 @@ fi
 # when it knows the build is wasm, but IR compiled for the host with `-o` alone
 # reaches these profiles without telling it, so the IR is read here too.
 case "$profile" in
-  wasm|wasi)
+  wasm|wasm-host|wasi)
     for i in ${inputs[@]+"${inputs[@]}"}; do
       case "$i" in
         *.ll)
@@ -298,8 +339,8 @@ if [ "$sqlite_wanted" = 1 ] && [ -z "$sqlite_dir" ]; then
   echo "error: the module calls SQLite, and $(dirname "$0")/../runtime/sqlite/ is not there" >&2
   exit 2
 fi
-if [ "$sqlite_wanted" = 1 ] && [ "$profile" = wasm ]; then
-  echo "error: the module calls SQLite, which the wasm profile cannot link: it has no libc for runtime/sqlite/sqlite3.c to build on; use --profile wasi" >&2
+if [ "$sqlite_wanted" = 1 ] && { [ "$profile" = wasm ] || [ "$profile" = wasm-host ]; }; then
+  echo "error: the module calls SQLite, which the $profile profile cannot link: it has no libc for runtime/sqlite/sqlite3.c to build on; use --profile wasi" >&2
   exit 2
 fi
 
@@ -672,7 +713,7 @@ case "$profile" in
   speed|size)
     "$CC" "${common[@]}" "${optimise[@]}" ${lto_parts[@]+"${lto_parts[@]}"} \
       "${gc[@]}" ${strip_flag[@]+"${strip_flag[@]}"} "${inputs[@]}" -lm -o "$out" ;;
-  wasm)
+  wasm|wasm-host)
     # A region's chunks come from malloc, and the freestanding wasm runtime
     # (runtime-wasm.c) has none, so IR that makes or enters one is refused here
     # rather than failing at the link on an undefined `nish_region_*`. The wasi
@@ -680,7 +721,7 @@ case "$profile" in
     for i in ${inputs[@]+"${inputs[@]}"}; do
       case "$i" in
         *.ll) if grep -q "@nish_region_" "$i"; then
-          echo "error: $i uses regions, which the wasm profile cannot link (it has no malloc); build it with --profile wasi" >&2
+          echo "error: $i uses regions, which the $profile profile cannot link (it has no malloc); build it with --profile wasi" >&2
           exit 2
         fi ;;
       esac
@@ -689,7 +730,7 @@ case "$profile" in
     # rather than probing PATH so a Homebrew llvm without a PATH entry still works.
     wasm_ld=$("$CC" -print-prog-name=wasm-ld)
     if [ ! -x "$wasm_ld" ]; then
-      echo "error: the wasm profile needs wasm-ld (install lld; on macOS: brew install llvm@18)" >&2
+      echo "error: the $profile profile needs wasm-ld (install lld; on macOS: brew install llvm@18)" >&2
       exit 2
     fi
     # IR compiled for the host rather than with `--target wasm32` calls std/crypto/aes.ts's
@@ -749,10 +790,64 @@ case "$profile" in
     fi
     # -mbulk-memory lowers llvm.memset/memcpy (`new Array<T>(n)`, `push` growth) to the
     # memory.fill/memory.copy instructions instead of libc calls the freestanding link lacks.
-    "$CC" -Wno-override-module --target=wasm32-unknown-unknown -Oz -nostdlib -mbulk-memory \
-      ${tls[@]+"${tls[@]}"} \
-      -Wl,--no-entry -Wl,--export-all -Wl,--strip-all -Wl,--gc-sections \
-      "${inputs[@]}" -o "$out" ;;
+    wasm_compile=(-Wno-override-module --target=wasm32-unknown-unknown -Oz -nostdlib -mbulk-memory)
+    if [ "$profile" = wasm ]; then
+      "$CC" "${wasm_compile[@]}" \
+        ${tls[@]+"${tls[@]}"} \
+        -Wl,--no-entry -Wl,--export-all -Wl,--strip-all -Wl,--gc-sections \
+        "${inputs[@]}" -o "$out"
+    else
+      # The export list. A module's exported functions are its `define` lines
+      # with external linkage and default visibility: the compiler gives
+      # everything else `internal` or `private`, and the other linkages are
+      # listed for IR it did not write. wasm-ld exports `memory` itself.
+      exports=()
+      runtime_linked=0
+      for i in "${inputs[@]}"; do
+        case "$i" in
+          */runtime-wasm.c|runtime-wasm.c) runtime_linked=1 ;;
+          *.ll)
+            while IFS= read -r name; do
+              exports+=("-Wl,--export=$name")
+            done < <(grep -E '^define ' "$i" \
+              | grep -Ev '^define (internal|private|linkonce|linkonce_odr|weak|weak_odr|available_externally|extern_weak|common|hidden|protected) ' \
+              | sed -nE 's/^[^@]*@"?([^"(]+)"?\(.*/\1/p') ;;
+        esac
+      done
+      if [ "$runtime_linked" = 1 ]; then
+        for name in nish_arena_mark nish_arena_release nish_alloc_array nish_reset_arena nish_free_arena; do
+          exports+=("-Wl,--export=$name")
+        done
+      fi
+      # shellcheck disable=SC2054 # -Wl,<flag> is one argument: the comma is the linker's
+      memory=(-Wl,-z,stack-size=65536)
+      if [ -n "$memory_mib" ]; then
+        bytes=$((memory_mib * 1048576))
+        memory+=("-Wl,--initial-memory=$bytes" "-Wl,--max-memory=$bytes")
+      fi
+      "$CC" "${wasm_compile[@]}" \
+        ${tls[@]+"${tls[@]}"} \
+        -Wl,--no-entry ${exports[@]+"${exports[@]}"} "${memory[@]}" -Wl,--strip-all -Wl,--gc-sections \
+        "${inputs[@]}" -o "$out"
+      # binaryen's size pass is optional: the module is complete without it.
+      if command -v wasm-opt >/dev/null 2>&1; then
+        wasm-opt -Oz --enable-bulk-memory "$out" -o "$out"
+        wasm_opt="wasm-opt -Oz"
+      else
+        wasm_opt="no wasm-opt"
+      fi
+      if [ -n "$inline_to" ]; then
+        # Decimal, one array literal: of the inline forms the smallest after
+        # compression (docs/wp50-wasm-host.md, Q10). od prints each byte as an
+        # unsigned decimal, and tr and sed join them with commas.
+        {
+          printf '// The bytes of %s, from scripts/build.sh --profile wasm-host --inline.\n' "${out##*/}"
+          printf 'export const bytes = new Uint8Array(['
+          od -An -v -tu1 "$out" | tr -s ' \n' '  ' | sed -E 's/^ //; s/ $//; s/ /,/g' | tr -d '\n'
+          printf ']);\n'
+        } > "$inline_to"
+      fi
+    fi ;;
   wasi)
     sysroot=${WASI_SYSROOT:-}
     for d in /usr/lib/wasi-sysroot /opt/wasi-sdk/share/wasi-sysroot /usr/share/wasi-sysroot; do
@@ -830,4 +925,4 @@ esac
 if [ "${dsym:-0}" = 1 ]; then "$("$CC" -print-prog-name=dsymutil)" "$out"; fi
 
 # `wc -c` pads with spaces on macOS; strip them so the number is clean.
-printf '%s: %s bytes (%s)\n' "$out" "$(wc -c < "$out" | tr -d ' ')" "$profile"
+printf '%s: %s bytes (%s%s)\n' "$out" "$(wc -c < "$out" | tr -d ' ')" "$profile" "${wasm_opt:+, $wasm_opt}"

package/std/base64.ts

@@ -2,7 +2,17 @@
  * `nish/base64` — standard base64 (RFC 4648 §4) with `=` padding, the encoding
  * kitty graphics frames are sent in.
  *
- * The alphabet is `A-Z a-z 0-9 + /`. Every three bytes become four characters,
+ *     import { base64Encode, base64EncodeInto, base64EncodedLength } from "nish/base64";
+ *
+ *     export const main = (): i32 => {
+ *       const hi: u8[] = [72, 105];                    // "Hi"
+ *       const text: string = base64Encode(hi);         // "SGk="
+ *       const out: u8[] = new Array<u8>(base64EncodedLength(2) + 1);
+ *       const end: i32 = base64EncodeInto(hi, 0, 2, out, 1); // out[1..5) is "SGk=", end is 5
+ *       return end;
+ *     };
+ *
+ * **The alphabet is `A-Z a-z 0-9 + /`.** Every three bytes become four characters,
  * and a final group of one or two bytes becomes two or three characters filled
  * out to four with `=` (RFC 4648 §4, the padding rules of §3.2), so the text is
  * always a multiple of four long.
@@ -13,15 +23,15 @@
  *   can be encoded chunk by chunk straight into its output buffer.
  * - `base64Encode(bytes)` is the whole array as a string.
  *
- * This module only encodes: what it is for writes base64 and never reads it
+ * **This module only encodes**: what it is for writes base64 and never reads it
  * back. It is not the strict decoder of `nish/crypto/base64url`, which is a
  * different alphabet without padding and is written not to branch on the data;
  * what goes through here is pixels, not secrets, so a sextet becomes its
  * character by indexing the alphabet. The output is ASCII, so the string is
  * the same bytes natively and under Node.
  *
- * Private helpers share the importing program's flat symbol namespace
- * (`docs/wp26-stdlib.md` §3e), which is why each one carries the module's name.
+ * **Private helpers carry the module's name** because they share the
+ * importing program's flat symbol namespace (`docs/wp26-stdlib.md` §3e).
  */
 
 /** The 64 characters of RFC 4648 §4's Table 1, in value order. */
@@ -34,6 +44,10 @@ const BASE64_PAD: i32 = 61
  * The characters `n` bytes encode to: four for every three, a short final
  * group counted as a whole one. Panics when `n` is negative or the length
  * would pass 2^31 - 1, which `n` above 1,610,612,733 does.
+ *
+ * @param n How many bytes are to be encoded; zero answers zero.
+ * @returns The number of base64 characters, padding included, that `n` bytes
+ *   encode to: always a multiple of four.
  */
 export const base64EncodedLength = (n: i32): i32 => {
   if (n < 0) {
@@ -55,6 +69,15 @@ const base64CharOf = (v: i32): u8 => toU8(BASE64_ALPHABET.charCodeAt(v))
  * `at + base64EncodedLength(len)`. Nothing is allocated. Panics when the source
  * range is not inside `src` or the encoding does not fit in `dst` from `at`;
  * both are checked before anything is written.
+ *
+ * @param src The bytes to encode from; only `src[off..off+len)` is read.
+ * @param off Where in `src` the bytes to encode start.
+ * @param len How many bytes of `src` to encode; zero writes nothing and
+ *   answers `at`.
+ * @param dst The buffer the characters are written into, one ASCII byte per
+ *   character; bytes outside the written range are left as they were.
+ * @param at Where in `dst` the first character goes.
+ * @returns The index in `dst` just past the last character written.
  */
 export const base64EncodeInto = (src: u8[], off: i32, len: i32, dst: u8[], at: i32): i32 => {
   // Refused before `toI32`, which saturates a longer length under
@@ -104,7 +127,13 @@ export const base64EncodeInto = (src: u8[], off: i32, len: i32, dst: u8[], at: i
   return o
 }
 
-/** `bytes` as padded base64. Panics past 1,610,612,733 bytes, whose encoding would not fit a string. */
+/**
+ * `bytes` as padded base64. Panics past 1,610,612,733 bytes, whose encoding
+ * would not fit a string.
+ *
+ * @param bytes The bytes to encode, all of them; an empty array answers `""`.
+ * @returns A fresh string holding the padded encoding.
+ */
 export const base64Encode = (bytes: u8[]): string => {
   if (bytes.length > 2147483647) {
     panic("base64Encode: more than 2^31 - 1 bytes")