Expose standard Base64 encoding as a platform module

[lukewilliamboswell]

Summary

Expose standard padded Base64 encoding as a small pure pf.Base64 module:

import pf.Base64

encoded = Base64.encode(bytes)

with an initial API of:

encode : List(U8) -> Str

Motivation

While adding a multimodal outbound HTTP request to a basic-webserver
application, I needed to embed JPEG bytes in a JSON data URL:

image_url = "data:image/jpeg;base64,${Base64.encode(image)}"

The application currently has to carry its own Base64 implementation.

This need already exists inside basic-webserver itself. The
form-file-upload.roc example
contains a private encoder so it can render an uploaded PNG as a data URL.
Extracting that implementation into the platform would remove the duplication
and make a common web protocol primitive available to applications.

Other common uses include Basic authentication, MIME/content-transfer
encoding, webhooks, and binary values in JSON APIs.

Proposed scope

• Add a pure platform/Base64.roc module.
• Expose it from platform/main.roc.
• Implement the RFC 4648 standard alphabet with = padding.
• Document that the output is ASCII and accepts arbitrary bytes, not only
  UTF-8 input.
• Replace the private implementation in examples/form-file-upload.roc with
  the exposed module.
• Test the RFC 4648 vectors, empty input, one- and two-byte tails, and
  non-UTF-8 binary input.

This should require no hosted operation or ABI change.

Decoding, unpadded output, and the URL-safe alphabet can be separate follow-up
features when there is a concrete use case for their API and error contract.

Acceptance criteria

• Applications can import pf.Base64 and encode List(U8) as standard
  padded Base64.
• The implementation matches RFC 4648 test vectors and handles arbitrary
  binary input.
• The file-upload example uses the shared module instead of maintaining a
  private encoder.
• The generated platform API documentation includes the module and its
  encoding contract.

[lukewilliamboswell]

I did a design and dependency pass over the broader framework-feature proposal. I think this issue should proceed with the scope currently described.

Standard padded Base64 encoding is a small, deterministic and bounded transformation. It requires no host state or ABI change, already has two concrete platform use cases, and avoids every application carrying subtly different encoding code.

A few contract details worth making explicit during implementation:

• The result uses the RFC 4648 standard alphabet, includes = padding, and never inserts line breaks.
• The output length is exactly 4 * ceil(input_bytes / 3), so allocation is derived directly from the finite input.
• Tests should include the RFC 4648 vectors ("", f, fo, foo, foob, fooba, foobar), arbitrary non-UTF-8 bytes, and one- and two-byte tails.
• The documentation should distinguish this encoding from URL-safe Base64 and from unpadded token encodings.

I would keep decoding, URL-safe encoding and unpadded encoding out of this increment. A future decoder should have a typed strictness/error contract, especially around invalid characters, padding and non-canonical encodings.

This remains a platform-native pure module as proposed; it does not require a companion package.

Reference: RFC 4648