feat: utf8to16 / utf16to8 helper wrappers (LE-default iconv filters)

Rather than baking UTF-16 into all five implementations, add two thin stdin/stdout
iconv wrappers in bin/: utf8to16 (UTF-8 -> UTF-16) and utf16to8 (UTF-16 -> UTF-8).
Both default to LITTLE-ENDIAN (ARM/x86_64; iconv's UTF-16 default is BE per RFC 2781,
which surprised us). utf8to16 emits a BOM by default (--no-bom to skip); utf16to8
auto-detects and strips a BOM, falling back to LE. Every glyph is BMP, so UTF-8<->UTF-16
is a lossless bijection — verified round-trips (default LE, --be, --no-bom).

Un-ignore them in .gitignore (bin/* is ignored), annotate via dirtree, and document
the recipe + the iconv escape hatch in the README.

Author: pmarreck

.dirtree-state

@@ -26,6 +26,8 @@ annotate=[
 	bin/printable-binary = LuaJIT CLI (the original reference implementation)
 	bin/printable-binary-node.js = Node.js CLI (ESM)
 	bin/printable_binary_ape.com = Prebuilt Actually-Portable-Executable (Cosmopolitan) C binary
+	bin/utf16to8 = Helper: transcode UTF-16 stdin -> UTF-8 (iconv wrapper; auto-detects BOM, else LE)
+	bin/utf8to16 = Helper: transcode UTF-8 stdin -> UTF-16 (iconv wrapper; default LE + BOM)
 	bm = Ad-hoc benchmark scripts (C vs Lua vs Zig)
 	bm/benchmark-zig-opt = Zig optimization benchmark
 	bm/benchmark_c_vs_lua.sh = C vs Lua benchmark script

.gitignore

@@ -35,3 +35,5 @@ bm/results
 
 # anything else
 ZIG_0.15_TO_0.16_MIGRATION.md
+!bin/utf8to16
+!bin/utf16to8

README.md

@@ -294,6 +294,24 @@ Because `--passthrough` sends the original binary to stdout, you can insert Prin
   # Should show 89PNG⏎␣␣ if the PNG signature is intact.
   ```
 
+### Piping to UTF-16 (or other text encodings)
+
+The encoded output is UTF-8 text. Because every glyph is in the BMP, it transcodes **losslessly** to UTF-16 — handy for Windows/PowerShell/JavaScript/.NET consumers. Two thin `iconv` wrappers default to **little-endian** (ARM and x86_64) and handle the BOM:
+
+```bash
+# Encode -> UTF-16LE (with BOM)
+printable-binary file | bin/utf8to16 > out.utf16
+
+# Decode a UTF-16 stream (BOM auto-detected; little-endian if absent)
+bin/utf16to8 < out.utf16 | printable-binary -d
+
+# Explicit endianness / no BOM
+printable-binary file | bin/utf8to16 --be        # UTF-16BE + BOM
+printable-binary file | bin/utf8to16 --no-bom    # UTF-16LE, no BOM
+```
+
+They are just `iconv` wrappers, so any encoding iconv supports works directly too (e.g. `... | iconv -f UTF-8 -t UTF-16LE`).
+
 ## Format Compatibility
 
 The PrintableBinary character set is specifically designed to be highly compatible with common text formats:

bin/utf16to8

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# utf16to8 — transcode UTF-16 on stdin to UTF-8 on stdout (a thin iconv wrapper).
+#
+# A leading BOM is auto-detected, used to pick endianness, and stripped. If there
+# is no BOM, little-endian is assumed (ARM/x86_64 default); override with --le/--be.
+#
+#   utf16to8 < file.utf16 | printable-binary -d     # auto-detect BOM, else LE
+#   utf16to8 --be < file.utf16be | printable-binary -d
+set -euo pipefail
+
+endian=LE
+forced=0
+for arg in "$@"; do
+  case "$arg" in
+    --le) endian=LE; forced=1 ;;
+    --be) endian=BE; forced=1 ;;
+    -h|--help)
+      echo "usage: utf16to8 [--le|--be]   (UTF-16 stdin -> UTF-8 stdout; BOM auto-detected, else LE)"
+      exit 0 ;;
+    *) echo "utf16to8: unknown option: $arg" >&2; exit 2 ;;
+  esac
+done
+
+tmp="$(mktemp)"
+trap 'rm -f "$tmp"' EXIT
+cat > "$tmp"
+
+skip=0
+bom="$(head -c 2 "$tmp" | xxd -p 2>/dev/null || true)"
+case "$bom" in
+  fffe) skip=2; [ "$forced" -eq 1 ] || endian=LE ;;
+  feff) skip=2; [ "$forced" -eq 1 ] || endian=BE ;;
+esac
+
+tail -c "+$((skip + 1))" "$tmp" | iconv -f "UTF-16$endian" -t UTF-8

bin/utf8to16

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# utf8to16 — transcode UTF-8 on stdin to UTF-16 on stdout (a thin iconv wrapper).
+#
+# Defaults to LITTLE-ENDIAN with a BOM. ARM and x86_64 are little-endian, and
+# `iconv -t UTF-16` historically emits big-endian (per RFC 2781), so this wrapper
+# makes LE the explicit, predictable default.
+#
+#   printable-binary file | utf8to16            # UTF-16LE + BOM
+#   printable-binary file | utf8to16 --be       # UTF-16BE + BOM
+#   printable-binary file | utf8to16 --no-bom   # UTF-16LE, no BOM
+#
+# Useful because every printable-binary glyph is in the BMP, so UTF-8<->UTF-16 is
+# a lossless bijection — pair with utf16to8 to round-trip through UTF-16.
+set -euo pipefail
+
+endian=LE
+bom=1
+for arg in "$@"; do
+  case "$arg" in
+    --le) endian=LE ;;
+    --be) endian=BE ;;
+    --no-bom) bom=0 ;;
+    -h|--help)
+      echo "usage: utf8to16 [--le|--be] [--no-bom]   (UTF-8 stdin -> UTF-16 stdout; default: LE + BOM)"
+      exit 0 ;;
+    *) echo "utf8to16: unknown option: $arg" >&2; exit 2 ;;
+  esac
+done
+
+# Emit the BOM ourselves so endianness is guaranteed regardless of iconv's default.
+if [ "$bom" -eq 1 ]; then
+  if [ "$endian" = LE ]; then printf '\xff\xfe'; else printf '\xfe\xff'; fi
+fi
+
+exec iconv -f UTF-8 -t "UTF-16$endian"